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.

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

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.

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

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.

terminalCopy
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:

terminalCopy
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

1. Navigate to Agent Settings

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

2. Enable the Agent

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

3. 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)

4. Write System Prompt

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

   CodeCopy
   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

5. Set Trigger Channels

   Select which channels should trigger the agent:

   • SMS: Text messages
   • WhatsApp: WhatsApp messages

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

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

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

Update Agent

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

Enable/Disable Agent

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

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

Get Agent Configuration

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

A sender with no agent returns 404.

Configuration Options

System Prompt Best Practices

Example System Prompts

Customer Support Agent:

CodeCopy
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:

CodeCopy
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

Next Steps