# Setup Guide

> Configure your first AI Agent via Dashboard or API

## AI Agent Setup Guide

This guide walks you through setting up an AI Agent for your sender. You can configure agents through the Dashboard UI or programmatically via the API.

## Agents have their own ids

An agent is a standalone object: it can answer on several senders, and it can
exist with none while you build it.

```bash
npx zavudev agents list          # every agent in the project, with its id
```

| | |
|---|---|
| `GET /v1/agents` | List, including agents connected to no sender |
| `POST /v1/agents` | Create standalone — no sender required |
| `GET /v1/agents/{agentId}` | Fetch one |
| `PATCH /v1/agents/{agentId}` | Update |
| `DELETE /v1/agents/{agentId}` | Delete |
| `POST /v1/agents/{agentId}/test` | Run it and return the reply |
| `POST /v1/agents/{agentId}/senders` | Connect a sender |
| `DELETE /v1/agents/{agentId}/senders/{senderId}` | Disconnect a sender |

The `/v1/senders/{senderId}/agent` routes still work. They resolve a sender to
the one agent that answers on it: the agent created on it, else the agent
connected to it with `POST /v1/agents/{agentId}/senders`. They cannot reach an
agent with no sender. `POST /v1/agents` takes `apiKey` the same way the
sender-scoped create does, so a standalone agent can use any provider.

```bash
npx zavudev agents senders connect    --agent <agentId> --sender <senderId>
npx zavudev agents senders disconnect --agent <agentId> --sender <senderId>
```

> **Note:**
> A sender answers with at most one agent. Connecting one that is already in use
> returns `400` naming the agent that holds it — otherwise you would have an agent
> that looks connected and never receives a message.

## Test it without sending anything

Once the agent exists, run it and read what it would say. Nothing is delivered
and no execution is logged. A test run is billed like a live reply: on a `zavu`
provider agent it is charged to your balance at the same per-token price (the
response's `cost`); on a bring-your-own-key agent it costs your provider.

```bash
npx zavudev agents list                       # agents in the project, with their ids
npx zavudev agents test --agent <agentId> --message "where is order ORD-001?"
```

It prints the reply plus tokens, latency, and how many knowledge-base chunks
were retrieved. The model is offered the agent's tools but none runs: if it
picks one, the reply stops at that choice. Pass `executeTools` on
the API to run them for real. It also warns about what a dry
run cannot prove: an agent that is still disabled, a sender without the channels
the agent triggers on, and contact metadata that exists on a real conversation
but not here.

Multi-turn, and isolating the prompt from retrieval:

```bash
npx zavudev agents test --agent <agentId> \
  --turn "I need to change my booking" --turn "Sure — which one?" \
  --message "the one on Friday"

npx zavudev agents test --agent <agentId> --message "what do you cost?" --no-knowledge
```

## Via Dashboard

  
#### Navigate to Agent Settings

    Go to **Senders** in the sidebar, select your sender, and click the **Agent** tab.
  

  
#### Enable the Agent

    Toggle the **Enable Agent** switch to activate automated responses for this sender.
  

  
#### Configure LLM Provider

    Choose your AI provider and model:

    - **Provider**: Select OpenAI, Anthropic, Google, Mistral, or Zavu (managed)
    - **Model**: Choose from available models (e.g., gpt-4o-mini, claude-3-5-haiku)
    - **API Key**: Enter your provider API key (not needed for Zavu provider)
  

  
#### Write System Prompt

    The system prompt defines your agent's personality and behavior. Write clear instructions:

    ```text
    You are a helpful customer support agent for [Company Name].

    Guidelines:
    - Be friendly and professional
    - Keep responses concise (under 160 characters for SMS)
    - If you don't know the answer, say so
    - For billing issues, direct customers to billing@company.com
    - Never share sensitive information
    ```
  

  
#### Set Trigger Channels

    Select which channels should trigger the agent:
    - **SMS**: Text messages
    - **WhatsApp**: WhatsApp messages

    > **Info:**
> You can enable the agent on both channels or just one.
  

  
#### Configure Advanced Settings

    Adjust these optional settings:

    | Setting | Description | Default |
    |---------|-------------|---------|
    | Temperature | Creativity level (0-2) | 0.7 |
    | Max Tokens | Maximum response length | 500 |
    | Context Window | Previous messages to include | 10 |
  

  
#### Save and Test

    Click **Save** to apply your configuration. Send a test message to your sender's phone number to verify the agent responds correctly.
  

## Via API

### Create Agent

A sender answers with one agent. Creating one on a sender that already answers
with an agent (created on it, or connected to it) returns `409 conflict`.

The agent is created **disabled**, so it answers nothing until you switch it on
(below). `name`, `provider`, `model` and `systemPrompt` are required.

```typescript
import Zavudev from "@zavudev/sdk";

const zavu = new Zavudev({
  apiKey: process.env["ZAVUDEV_API_KEY"],
});

const { agent } = await zavu.senders.agent.create("sender_abc123", {
  name: "Acme Support",
  provider: "openai",
  model: "gpt-4o-mini",
  apiKey: process.env.OPENAI_API_KEY, // Not needed for Zavu provider
  systemPrompt: `You are a helpful customer support agent for Acme Corp.
Be friendly and concise. If you don't know the answer, say so.`,
  temperature: 0.7,
  maxTokens: 500,
  contextWindowMessages: 10,
  triggerOnChannels: ["sms", "whatsapp"],
});

console.log("Agent ID:", agent.id);

// Created disabled. Switch it on once it is configured:
await zavu.senders.agent.update("sender_abc123", { enabled: true });
```

```bash
curl -X POST https://api.zavu.dev/v1/senders/sender_abc123/agent \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Support",
    "provider": "openai",
    "model": "gpt-4o-mini",
    "apiKey": "sk-...",
    "systemPrompt": "You are a helpful customer support agent for Acme Corp.\nBe friendly and concise.",
    "temperature": 0.7,
    "maxTokens": 500,
    "contextWindowMessages": 10,
    "triggerOnChannels": ["sms", "whatsapp"]
  }'

# Created disabled. Switch it on once it is configured:
curl -X PATCH https://api.zavu.dev/v1/senders/sender_abc123/agent \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true }'
```

### Update Agent

```typescript
const agent = await zavu.senders.agent.update("sender_abc123", {
  systemPrompt: "Updated system prompt...",
  temperature: 0.5,
  model: "gpt-4o", // Upgrade to more powerful model
});
```

```bash
curl -X PATCH https://api.zavu.dev/v1/senders/sender_abc123/agent \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "systemPrompt": "Updated system prompt...",
    "temperature": 0.5,
    "model": "gpt-4o"
  }'
```

### Enable/Disable Agent

```typescript
// Disable agent
await zavu.senders.agent.update("sender_abc123", {
  enabled: false,
});

// Re-enable agent
await zavu.senders.agent.update("sender_abc123", {
  enabled: true,
});
```

```bash
# Disable agent
curl -X PATCH https://api.zavu.dev/v1/senders/sender_abc123/agent \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}'
```

### Get Agent Configuration

```typescript
const agent = await zavu.senders.agent.retrieve("sender_abc123");

console.log("Provider:", agent.provider);
console.log("Model:", agent.model);
console.log("Enabled:", agent.enabled);
console.log("Stats:", agent.stats);
```

```bash
curl https://api.zavu.dev/v1/senders/sender_abc123/agent \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY"
```

A sender with no agent returns `404`.

## Configuration Options

| Option | Type | Description |
|--------|------|-------------|
| `enabled` | boolean | Whether the agent responds to messages |
| `provider` | string | LLM provider: `openai`, `anthropic`, `google`, `mistral`, `zavu` |
| `model` | string | Model ID. With your own key, the vendor's name (`gpt-4o-mini`). With `zavu`, `vendor/model` as the dashboard's model picker lists it (`openai/gpt-5.6-luna`, the default); see [Zavu models](https://www.zavu.dev/docs/guides/functions/defining-agents#zavu-managed-gateway-recommended-for-getting-started). |
| `apiKey` | string | Provider API key (not needed for `zavu` provider) |
| `systemPrompt` | string | Instructions that define the agent's behavior |
| `temperature` | number | Response creativity (0 = deterministic, 2 = creative) |
| `maxTokens` | number | Maximum tokens in the response |
| `contextWindowMessages` | number | Number of previous messages to include as context |
| `triggerOnChannels` | array | Channels that activate the agent: `["sms", "whatsapp"]` |

## System Prompt Best Practices

  - **Be Specific**: Define exactly what the agent should and shouldn't do. Include examples of good responses.
  - **Set Boundaries**: Specify what topics to avoid and when to escalate to humans.
  - **Match the Channel**: For SMS, instruct the agent to keep responses under 160 characters when possible.
  - **Include Context**: Mention your company name, products, and common customer questions.

### Example System Prompts

**Customer Support Agent:**
```text
You are a friendly customer support agent for TechCo.

Your responsibilities:
- Answer questions about our products and services
- Help troubleshoot common issues
- Direct billing questions to billing@techco.com
- Escalate complex technical issues to our support team

Guidelines:
- Be concise and helpful
- Use simple language
- Never share customer account details
- If unsure, say "I'll connect you with a specialist"
```

**Lead Qualification Agent:**
```text
You are a sales assistant for RealEstate Inc.

Your goal is to qualify leads by collecting:
1. Their name
2. Type of property they're looking for
3. Budget range
4. Preferred location
5. Timeline for purchase

Be friendly and conversational. After collecting this info, let them know an agent will contact them within 24 hours.
```

## Testing Your Agent

After configuring your agent, test it thoroughly:

1. **Send test messages** from different phone numbers
2. **Test edge cases** like questions the agent shouldn't answer
3. **Verify escalation** works correctly
4. **Check response quality** across different topics
5. **Monitor logs** in the Dashboard under Agent > Execution Logs

> **Warning:**
> Always test your agent before enabling it for production traffic. Poorly configured agents can frustrate customers.

## Next Steps

  - [Add Flows](https://www.zavu.dev/docs/guides/ai-agents/flows): Create structured conversation paths
  - [Add Tools](https://www.zavu.dev/docs/guides/ai-agents/tools): Let your agent execute actions
  - [Add Knowledge Base](https://www.zavu.dev/docs/guides/ai-agents/knowledge-base): Upload documents for the agent to reference
  - [AI Agents Concept](https://www.zavu.dev/docs/concepts/ai-agents): Learn how agents work under the hood