> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zavu.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

## Via Dashboard

<Steps>
  <Step title="Navigate to Agent Settings">
    Go to **Senders** in the sidebar, select your sender, and click the **Agent** tab.
  </Step>

  <Step title="Enable the Agent">
    Toggle the **Enable Agent** switch to activate automated responses for this sender.
  </Step>

  <Step title="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)
  </Step>

  <Step title="Write System Prompt">
    The system prompt defines your agent's personality and behavior. Write clear instructions:

    ```text theme={null}
    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
    ```
  </Step>

  <Step title="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.
    </Info>
  </Step>

  <Step title="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      |
  </Step>

  <Step title="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.
  </Step>
</Steps>

## Via API

### Create Agent

<CodeGroup>
  ```typescript TypeScript theme={null}
  import Zavudev from "@zavudev/sdk";

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

  const agent = await zavu.senders.agent.create("sender_abc123", {
    enabled: true,
    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);
  ```

  ```python Python theme={null}
  import os
  from zavudev import Zavudev

  zavu = Zavudev(
      api_key=os.environ.get("ZAVUDEV_API_KEY"),
  )

  agent = zavu.senders.agent.create(
      "sender_abc123",
      enabled=True,
      provider="openai",
      model="gpt-4o-mini",
      api_key=os.environ.get("OPENAI_API_KEY"),  # Not needed for Zavu provider
      system_prompt="""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,
      max_tokens=500,
      context_window_messages=10,
      trigger_on_channels=["sms", "whatsapp"],
  )

  print(f"Agent ID: {agent.id}")
  ```

  ```ruby Ruby theme={null}
  require "zavudev"

  client = Zavudev::Client.new(api_key: ENV["ZAVUDEV_API_KEY"])

  agent = client.senders.agent.create("sender_abc123",
    enabled: true,
    provider: "openai",
    model: "gpt-4o-mini",
    api_key: ENV["OPENAI_API_KEY"],
    system_prompt: "You are a helpful customer support agent for Acme Corp.\nBe friendly and concise. If you don't know the answer, say so.",
    temperature: 0.7,
    max_tokens: 500,
    context_window_messages: 10,
    trigger_on_channels: ["sms", "whatsapp"]
  )

  puts "Agent ID: #{agent.id}"
  ```

  ```go Go theme={null}
  agent, _ := client.Senders.Agent.Create(context.TODO(), "sender_abc123", zavudev.AgentCreateParams{
  	Enabled:               zavudev.Bool(true),
  	Provider:              zavudev.String("openai"),
  	Model:                 zavudev.String("gpt-4o-mini"),
  	APIKey:                zavudev.String(os.Getenv("OPENAI_API_KEY")),
  	SystemPrompt:          zavudev.String("You are a helpful customer support agent for Acme Corp.\nBe friendly and concise."),
  	Temperature:           zavudev.Float(0.7),
  	MaxTokens:             zavudev.Int(500),
  	ContextWindowMessages: zavudev.Int(10),
  	TriggerOnChannels:     []string{"sms", "whatsapp"},
  })

  fmt.Printf("Agent ID: %s\n", agent.ID)
  ```

  ```php PHP theme={null}
  $agent = $client->senders->agent->create('sender_abc123', [
      'enabled' => true,
      'provider' => 'openai',
      'model' => 'gpt-4o-mini',
      'apiKey' => getenv('OPENAI_API_KEY'),
      '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'],
  ]);

  echo "Agent ID: {$agent->id}\n";
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.zavu.dev/v1/senders/sender_abc123/agent \
    -H "Authorization: Bearer $ZAVU_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "enabled": true,
      "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"]
    }'
  ```
</CodeGroup>

### Update Agent

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

  ```python Python theme={null}
  agent = zavu.senders.agent.update(
      "sender_abc123",
      system_prompt="Updated system prompt...",
      temperature=0.5,
      model="gpt-4o",  # Upgrade to more powerful model
  )
  ```

  ```ruby Ruby theme={null}
  agent = client.senders.agent.update("sender_abc123",
    system_prompt: "Updated system prompt...",
    temperature: 0.5,
    model: "gpt-4o"
  )
  ```

  ```go Go theme={null}
  agent, _ := client.Senders.Agent.Update(context.TODO(), "sender_abc123", zavudev.AgentUpdateParams{
  	SystemPrompt: zavudev.String("Updated system prompt..."),
  	Temperature:  zavudev.Float(0.5),
  	Model:        zavudev.String("gpt-4o"),
  })
  ```

  ```php PHP theme={null}
  $agent = $client->senders->agent->update('sender_abc123', [
      'systemPrompt' => 'Updated system prompt...',
      'temperature' => 0.5,
      'model' => 'gpt-4o',
  ]);
  ```

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

### Enable/Disable Agent

<CodeGroup>
  ```typescript TypeScript theme={null}
  // Disable agent
  await zavu.senders.agent.update("sender_abc123", {
    enabled: false,
  });

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

  ```python Python theme={null}
  # Disable agent
  zavu.senders.agent.update("sender_abc123", enabled=False)

  # Re-enable agent
  zavu.senders.agent.update("sender_abc123", enabled=True)
  ```

  ```ruby Ruby theme={null}
  # Disable agent
  client.senders.agent.update("sender_abc123", enabled: false)

  # Re-enable agent
  client.senders.agent.update("sender_abc123", enabled: true)
  ```

  ```go Go theme={null}
  // Disable agent
  client.Senders.Agent.Update(context.TODO(), "sender_abc123", zavudev.AgentUpdateParams{
  	Enabled: zavudev.Bool(false),
  })

  // Re-enable agent
  client.Senders.Agent.Update(context.TODO(), "sender_abc123", zavudev.AgentUpdateParams{
  	Enabled: zavudev.Bool(true),
  })
  ```

  ```php PHP theme={null}
  // Disable agent
  $client->senders->agent->update('sender_abc123', ['enabled' => false]);

  // Re-enable agent
  $client->senders->agent->update('sender_abc123', ['enabled' => true]);
  ```

  ```bash cURL theme={null}
  # Disable agent
  curl -X PATCH https://api.zavu.dev/v1/senders/sender_abc123/agent \
    -H "Authorization: Bearer $ZAVU_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"enabled": false}'
  ```
</CodeGroup>

### Get Agent Configuration

<CodeGroup>
  ```typescript TypeScript theme={null}
  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);
  ```

  ```python Python theme={null}
  agent = zavu.senders.agent.retrieve("sender_abc123")

  print(f"Provider: {agent.provider}")
  print(f"Model: {agent.model}")
  print(f"Enabled: {agent.enabled}")
  print(f"Stats: {agent.stats}")
  ```

  ```ruby Ruby theme={null}
  agent = client.senders.agent.retrieve("sender_abc123")

  puts "Provider: #{agent.provider}"
  puts "Model: #{agent.model}"
  puts "Enabled: #{agent.enabled}"
  puts "Stats: #{agent.stats}"
  ```

  ```go Go theme={null}
  agent, _ := client.Senders.Agent.Get(context.TODO(), "sender_abc123")

  fmt.Printf("Provider: %s\n", agent.Provider)
  fmt.Printf("Model: %s\n", agent.Model)
  fmt.Printf("Enabled: %v\n", agent.Enabled)
  fmt.Printf("Stats: %+v\n", agent.Stats)
  ```

  ```php PHP theme={null}
  $agent = $client->senders->agent->retrieve('sender_abc123');

  echo "Provider: {$agent->provider}\n";
  echo "Model: {$agent->model}\n";
  echo "Enabled: {$agent->enabled}\n";
  echo "Stats: " . json_encode($agent->stats) . "\n";
  ```

  ```bash cURL theme={null}
  curl https://api.zavu.dev/v1/senders/sender_abc123/agent \
    -H "Authorization: Bearer $ZAVU_API_KEY"
  ```
</CodeGroup>

## 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 (e.g., `gpt-4o-mini`, `claude-3-5-haiku`)               |
| `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

<CardGroup cols={2}>
  <Card title="Be Specific" icon="bullseye">
    Define exactly what the agent should and shouldn't do. Include examples of good responses.
  </Card>

  <Card title="Set Boundaries" icon="shield">
    Specify what topics to avoid and when to escalate to humans.
  </Card>

  <Card title="Match the Channel" icon="message">
    For SMS, instruct the agent to keep responses under 160 characters when possible.
  </Card>

  <Card title="Include Context" icon="building">
    Mention your company name, products, and common customer questions.
  </Card>
</CardGroup>

### Example System Prompts

**Customer Support Agent:**

```text theme={null}
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 theme={null}
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.
</Warning>

## Next Steps

<CardGroup cols={2}>
  <Card title="Add Flows" icon="diagram-project" href="/guides/ai-agents/flows">
    Create structured conversation paths
  </Card>

  <Card title="Add Tools" icon="wrench" href="/guides/ai-agents/tools">
    Let your agent execute actions
  </Card>

  <Card title="Add Knowledge Base" icon="book" href="/guides/ai-agents/knowledge-base">
    Upload documents for the agent to reference
  </Card>

  <Card title="AI Agents Concept" icon="brain" href="/concepts/ai-agents">
    Learn how agents work under the hood
  </Card>
</CardGroup>