Setup Guide

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.

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 exactly one agent, so they cannot reach an agent with no sender, or the second agent on a shared one.

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

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, nothing is charged, and no execution is logged — so it is safe to run on every edit while you shape the prompt.

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. It also warns about what a dry run cannot prove: an agent that is still disabled, tools its channels will never call, and contact metadata that exists on a real conversation but not here. Multi-turn, and isolating the prompt from retrieval:

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:

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

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

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);

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}")

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}"

agent, _ := client.Senders.Agent.New(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)

$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";

curl -X POST https://api.zavu.dev/v1/senders/sender_abc123/agent \
  -H "Authorization: Bearer $ZAVUDEV_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"]
  }'

Update Agent

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

agent = zavu.senders.agent.update(
    "sender_abc123",
    system_prompt="Updated system prompt...",
    temperature=0.5,
    model="gpt-4o",  # Upgrade to more powerful model
)

agent = client.senders.agent.update("sender_abc123",
  system_prompt: "Updated system prompt...",
  temperature: 0.5,
  model: "gpt-4o"
)

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"),
})

$agent = $client->senders->agent->update('sender_abc123', [
    'systemPrompt' => 'Updated system prompt...',
    'temperature' => 0.5,
    'model' => 'gpt-4o',
]);

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

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

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

# Disable agent
zavu.senders.agent.update("sender_abc123", enabled=False)

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

# Disable agent
client.senders.agent.update("sender_abc123", enabled: false)

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

// 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),
})

// Disable agent
$client->senders->agent->update('sender_abc123', ['enabled' => false]);

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

# 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

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);

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}")

agent = client.senders.agent.retrieve("sender_abc123")

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

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)

$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";

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

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

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:

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:

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:

Send test messages from different phone numbers
Test edge cases like questions the agent shouldn’t answer
Verify escalation works correctly
Check response quality across different topics
Monitor logs in the Dashboard under Agent > Execution Logs

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

Next Steps

Add Flows

Create structured conversation paths

Add Tools

Let your agent execute actions

Add Knowledge Base

Upload documents for the agent to reference

AI Agents Concept

Learn how agents work under the hood

Getting Started

Build agents

Send & receive

Operate

Developer tools

Integrations

Setup Guide

AI Agent Setup Guide

Agents have their own ids

Test it without sending anything

Via Dashboard

Via API

Create Agent

Update Agent

Enable/Disable Agent

Get Agent Configuration

Configuration Options

System Prompt Best Practices

Be Specific

Set Boundaries

Match the Channel

Include Context

Example System Prompts

Testing Your Agent

Next Steps

Add Flows

Add Tools

Add Knowledge Base

AI Agents Concept

​AI Agent Setup Guide

​Agents have their own ids

​Test it without sending anything

​Via Dashboard

​Via API

​Create Agent

​Update Agent

​Enable/Disable Agent

​Get Agent Configuration

​Configuration Options

​System Prompt Best Practices

Be Specific

Set Boundaries

Match the Channel

Include Context

​Example System Prompts

​Testing Your Agent

​Next Steps

Add Flows

Add Tools

Add Knowledge Base

AI Agents Concept

AI Agent Setup Guide

Agents have their own ids

Test it without sending anything

Via Dashboard

Via API

Create Agent

Update Agent

Enable/Disable Agent

Get Agent Configuration

Configuration Options

System Prompt Best Practices

Example System Prompts

Testing Your Agent

Next Steps