# AI Agents

> Automate conversations with AI-powered agents that respond to incoming WhatsApp, SMS and Email messages.

## AI Agents

An **AI Agent** is an automated responder attached to a sender that uses large language models (LLMs) to handle incoming messages. When a customer sends a message, the agent processes it and generates an intelligent response.

## What is an AI Agent?

Think of an AI Agent as a virtual assistant for your messaging. It can:

- **Answer customer questions** using your knowledge base
- **Collect information** through conversational flows
- **Execute actions** via webhook integrations
- **Escalate to humans** when needed

```json
{
  "id": "agent_abc123",
  "name": "Support Agent",
  "enabled": true,
  "provider": "openai",
  "model": "gpt-4o-mini",
  "systemPrompt": "You are a helpful customer support agent for Acme Corp...",
  "contextWindowMessages": 10,
  "triggerOnChannels": ["sms", "whatsapp"],
  "stats": {
    "totalInvocations": 1250,
    "totalTokensUsed": 450000,
    "totalCost": 0.85
  }
}
```

## How Agents Work

When a message arrives, the agent processes it through several stages:

```
Inbound Message (SMS/WhatsApp)
        |
        v
   Agent Enabled?
        |
    +---+---+
    |       |
   No      Yes
    |       |
    v       v
 Webhook   Check Active Flow
  Only          |
            +---+---+
            |       |
        Has Flow   No Flow
            |       |
            v       v
      Continue   Check KB
        Flow    for Context
            |       |
            v       v
      Execute   Generate
        Step    Response
            |       |
            +---+---+
                |
                v
         Send Response
```

### Processing Flow

1. **Check for active flow**: If the contact is in a conversational flow, continue that flow
2. **Match flow triggers**: Check if the message should start a new flow (`keyword`, `always`, and `intent` — the last judged by a classifier rather than by matching words; see [Flows](https://www.zavu.dev/docs/guides/ai-agents/flows))
3. **Retrieve context**: Get conversation history and relevant knowledge base chunks
4. **Generate response**: Call the LLM with context and system prompt
5. **Send response**: Deliver the response via the same channel

## Key Components

### LLM Configuration

Configure which AI model powers your agent:

| Setting | Description |
|---------|-------------|
| **Provider** | OpenAI, Anthropic, Google, Mistral, or Zavu (managed) |
| **Model** | The specific model (e.g., `gpt-4o-mini`, `claude-3-5-sonnet`) |
| **System Prompt** | Instructions that define the agent's personality and behavior |
| **Temperature** | Creativity level (0 = deterministic, 2 = creative) |
| **Max Tokens** | Maximum response length |
| **Context Window** | Number of previous messages to include |

### Flows

**Flows** are deterministic conversation paths for structured interactions like lead capture or appointment booking. They combine fixed messages, data collection, and AI-generated responses.

```
[Welcome] → [Ask Name] → [Ask Email] → [Confirm] → [End]
```

Flows are useful when you need:
- Guaranteed data collection (name, email, phone)
- Consistent messaging for compliance
- Step-by-step processes (booking, ordering)

### Tools

**Tools** allow your agent to execute actions by calling your webhooks. The LLM can decide when to use a tool based on the conversation.

| Example Tool | Use Case |
|--------------|----------|
| `check_order_status` | Look up order tracking info |
| `create_ticket` | Open a support ticket |
| `book_appointment` | Schedule a calendar event |
| `get_inventory` | Check product availability |

### Knowledge Base

A **Knowledge Base** stores documents that the agent can reference when answering questions. Using RAG (Retrieval Augmented Generation), the agent searches for relevant content and includes it in its context.

- Upload FAQs, product docs, policies
- Automatic chunking and embedding
- Semantic search for relevant context

## Pricing

AI Agent costs are **pass-through** with no markup. You pay exactly what the AI providers charge:

| Provider | Model | Input | Output | ~Cost/Message |
|----------|-------|-------|--------|---------------|
| OpenAI | gpt-5.6-luna | $0.20/1M | $1.20/1M | ~$0.0004 |
| OpenAI | gpt-4o-mini | $0.15/1M | $0.60/1M | ~$0.0002 |
| OpenAI | gpt-4o | $2.50/1M | $10/1M | ~$0.004 |
| Anthropic | claude-3-5-haiku | $0.80/1M | $4/1M | ~$0.0014 |
| Anthropic | claude-3-5-sonnet | $3/1M | $15/1M | ~$0.005 |
| Google | gemini-2.5-flash-lite | $0.10/1M | $0.40/1M | ~$0.0002 |
| Google | gemini-2.5-flash | $0.30/1M | $2.50/1M | ~$0.0007 |

`~Cost/Message` assumes roughly 1,000 input and 150 output tokens. Provider
prices move: the agent's model picker in the dashboard lists the catalog
currently in force, and is what billing charges against.

> **Info:**
> If you use the **Zavu** provider, we handle the API key and charge your account balance directly.

## Best Practices

  - **Write Clear Prompts**: Your system prompt defines the agent's behavior. Be specific about tone, limitations, and when to escalate.
  - **Use Flows for Structure**: For data collection or multi-step processes, use flows instead of relying on the LLM to remember steps.
  - **Add Knowledge Base**: Upload FAQs and product docs so the agent can provide accurate, specific answers.
  - **Monitor Costs**: Check execution logs regularly. Use smaller models like gpt-4o-mini for cost efficiency.

## Next Steps

  - [Setup Guide](https://www.zavu.dev/docs/guides/ai-agents/setup): Configure your first AI Agent
  - [Flows Guide](https://www.zavu.dev/docs/guides/ai-agents/flows): Build conversational flows
  - [Tools Guide](https://www.zavu.dev/docs/guides/ai-agents/tools): Add webhook integrations
  - [Knowledge Base](https://www.zavu.dev/docs/guides/ai-agents/knowledge-base): Set up RAG with your documents