Agents
What is an Agent?
An agent is one AI assistant — its personality, voice, and rules in one place.
An agent is your AI assistant. One agent has:
- A name (what callers hear: "Hi, this is Priya...")
- A system prompt — a paragraph telling the AI who it is and what to do
- A voice — which voice it speaks in (Helena, Brian, Hindi voices, etc.)
- A language — English, Hindi, Tamil, etc.
- Tools — optional powers (call your API, book on a calendar, hang up, transfer)
- Settings — fine-tuning knobs you rarely need to touch
You can have as many agents as you want. Common setups:
| You have... | You'd build... |
|---|---|
| One business with one purpose | 1 agent ("Receptionist") |
| Sales + support team | 2 agents (Sales calls go to one, support to another) |
| Many product lines | 1 agent per product, or 1 agent that routes via keypad press |
| Multiple languages | 1 agent per language (Hindi vs Tamil) OR 1 multilingual agent |
How agents talk to people
An agent doesn't care HOW the conversation happens. The same agent can:
- Answer phone calls when you link a phone number to it
- Take chat or voice on your website via the embedded widget
- Reply to WhatsApp messages
- Make outbound calls when you put it in a campaign
You build the agent once. It works everywhere.
The agent list page
Open Agents in the sidebar. Each row shows:
| Column | What it means |
|---|---|
| Name + avatar | What you called the agent |
| Models | The AI brain (LLM), ears (STT), and voice (TTS) it uses |
| Status | Green = active and reachable. Gray = paused. |
| Calls | How many calls this agent has handled |
Click any row to open that agent.
The agent detail page
Three tabs at the top:
1. Overview
The headline numbers:
- Total calls — lifetime
- Avg duration — how long calls typically last
- Success rate — what % completed normally
- Active now — calls happening this second
Plus charts: call volume over 14 days, peak hours, status breakdown.
2. Calls
Just the calls handled by THIS agent. Filter and search as you would on the main Calls page.
3. Configure
Where you change the agent. The big sections:
- Identity — name + avatar + image
- System prompt — the instruction paragraph
- Welcome message — the first thing the bot says
- Providers — which LLM/STT/TTS to use (most users keep defaults)
- Voice — pick a voice, adjust speed/stability
- Background sound — optional office/cafe sound for realism
- Tools — APIs, MCP servers, transfer rules, keypad routes
- Advanced — VAD tuning, recording, voicemail detection, pronunciation, etc.
Buttons on the agent page
| Button | What it does |
|---|---|
| Test call | Talk to the agent from your browser (uses real credits) |
| Configure | Open the editor |
| Delete | Remove the agent forever. You can't undo. |
Common first-day errors (and what to do)
| Symptom | Why | Fix |
|---|---|---|
| Phone rings but bot is silent | TTS provider outage | Check provider health at the top of the agent page. If ElevenLabs/Deepgram shows degraded, swap TTS provider temporarily. Full diagnostics: Troubleshooting. |
| Bot keeps interrupting me mid-sentence | VAD stop_secs too aggressive | Configure → Advanced → VAD → raise vadStopSecs to 0.4. See VAD tuning guide. |
| Bot doesn't react to me at all | VAD confidence too high OR mic permissions denied | Lower vadConfidence to 0.6. Or check browser mic permissions. |
| Bot mishears my company name | STT confusion on rare words | Add it to Knowledge → Boosted Keywords or Pronunciation Dictionary. Most impactful single fix. See Pronunciation & Boost. |
| Agent gives weird/off-topic answers | System prompt too vague | Be explicit about what NOT to do, not just what to do. Examples: "Never mention competitors", "Always end with a question". |
| Test call shows 503 / "Bot startup failed" | Provider key missing/revoked, or LLM API rejecting the model | Verify provider keys in Settings → Providers. If using GPT-5 / o-series, the bot auto-routes — should "just work". |
Invalid dynamicVariables when calling via SDK | A key in your dynamicVariables dict starts with a digit, has consecutive spaces, or has leading/trailing whitespace | Keys now accept letters, digits, underscores, hyphens, dots, and single inline spaces — so Client Name, tracking-id, order.id all work. Reject reasons: leading whitespace, key longer than 64 chars. See Dynamic Variables. |
Next steps
- Create your first agent — full walkthrough
- Write a good system prompt — the most important thing
- Pick a voice — short list of recommended voices
- Give the agent powers — connect APIs, transfer calls
- Every advanced setting — when you need to tune VAD/STT/TTS/etc.
- Build agents from code — same agent, driven via SDK + dynamicVariables
For developers
If you'd rather skip the dashboard for repetitive setup, the examples repo has 4 runnable TypeScript projects:
| Repo example | What |
|---|---|
01-personalized-call/ | Place one call with per-recipient prompt substitution |
02-bulk-campaign/ | Run a campaign from a CSV, watch progress live |
03-webhook-receiver/ | Receive call.completed events with HMAC verification |
04-simulate-before-going-live/ | Test your prompt with client.eval.simulate() — costs ₹0 |
Each ships an npm run check preflight that catches typos / wrong IDs / provider outages BEFORE any chargeable action.