Agents

Agents are standalone voice AI entities that handle conversations end-to-end. Each agent has its own personality (system prompt), voice, language model, and call behavior settings. You configure an agent once, attach a phone number or talk to it in the browser, and it handles calls autonomously.

Agent Editor

The agent editor has two halves. The middle panel is organized into five tabs — Agent, Engine, Tools, Call, and Analytics — that group related configuration. The right panel is a live test surface: three clickable chips select your transcriber, language model, and voice; a cost/latency estimate updates as you pick; and a talk panel runs a real browser call against the agent you are editing.

Right Panel: Transcriber, Model & Voice

The right panel shows three chips — Transcriber, Model, and Voice — reflecting the agent's current speech-to-text, LLM, and text-to-speech selection. Click any chip to expand an inline picker beneath it.

Each picker lists the available providers (the curated lab set), then the models under the selected provider with per-model stats — the same cost and latency data that drives the Cost and Latency bars in the estimate panel. The Voice picker adds a voice list for the chosen TTS provider. Selecting a value updates the estimate bars live.

Cascade resets. Changing a provider resets the dependent fields to that provider's defaults: pick a new STT/LLM provider and the model resets to the provider default; pick a new TTS provider and both the model and voice reset. This guarantees you never save a model or voice that doesn't belong to the selected provider.

Coverage gating. Models that cannot cover your selected languages are greyed out in these pickers with a tooltip explaining why (see Languages below). Only one picker is open at a time; the chip shows an active state while open and the picker closes on select or on re-click.

Agent Tab

The Agent tab contains the core personality and behavior settings -- languages, the welcome message, the system prompt, and the End Call behavior.

Languages

An agent speaks an ordered list of languages — the order is the priority: the first language is the primary, the second is the secondary, and so on.

The chosen list drives coverage gating in the right-panel Transcriber and Voice pickers: any STT or TTS model that cannot cover every selected language is greyed out with a tooltip. For example, picking hi + en greys out English-only models. Pick languages first, then choose models that cover them. The API enforces the same rule — saving or calling with a language the chosen transcriber or voice model does not support returns a 400 naming the unsupported languages.

Welcome Message

The first thing your agent says when a call starts.

System Prompt

The system prompt defines your agent's role, personality, knowledge, and behavior. This is the primary instruction set that shapes every response.

The editor includes an AI Generate button that can automatically draft a system prompt based on your agent's name and description.

The Agent tab also carries a timezone picker (used to resolve system-time variables in the prompt) and the pill-based {{variable}} editor for the system prompt. The timezone is always a concrete IANA zone: new agents are created with your browser's timezone, and API bodies that omit timezone default to Asia/Kolkata.

Variables

Write {{variable_name}} anywhere in the system prompt, the welcome message, or the end-call trigger prompt, and the platform replaces it with a real value when the call starts. Matching is case- and space-insensitive: {{First Name}}, {{first_name}} and {{FIRST_NAME}} all resolve to the same value.

There are two kinds.

System variables

Resolved by the platform itself on every call. You never set these — type {{ in any prompt field to pick them from the menu.

Your own variables (context variables)

Every other {{token}} is yours. Open Test Inputs (the {} button in the right panel) to see every variable found in your prompts, give each one a value, then save the agent — the values persist in the agent config as contextVariables and are reused on every future call. Reopen the agent and the rows come back filled in.

Saved values are defaults, not constants: a campaign row or an API call can override any of them per call.

Resolution order

Lowest to highest — the highest-priority source that produces a value wins:

For example, with the prompt Calling about your {{plan}} plan in {{city}}. and saved defaults plan = "free", city = "Pune":

// Campaign row, or a POST /api/v1/call body
{ "contextVariables": { "plan": "pro", "city": "" } }

The agent says: "Calling about your pro plan in Pune." — plan was overridden, and city fell back to the saved default because the row was blank.

End Call

A voice call can end several ways: the agent decides the conversation is done, the caller hangs up, the duration cap is hit, or the silence timeout fires. This section — at the bottom of the Agent tab — configures the endCall tool that owns the graceful path and the farewell spoken on every path.

Every agent has an endCall tool. It is mandatory: if a config is saved without one, the platform auto-seeds a default tool named end_call with the default trigger prompt below. There is no on/off toggle — the LLM can always end the call gracefully.

Fields

Default trigger prompt

Every agent starts with this prompt. Replace it with your own conditions if your use case has different end-of-conversation cues:

When the conversation is complete, use the end_call tool. A conversation is complete if:
1. The user explicitly says they want to stop (e.g., "That's all," "I'm done," "Goodbye").
2. The user seems satisfied and their goal appears achieved.
3. The user's goal appears achieved based on conversation history, even without explicit confirmation.
Only end the call when you are confident the conversation is truly complete.

How farewell behavior works

The farewell resolves the same way on every end path — the agent calling endCall, the idle-retry limit, or the max-duration cap:

What ends up in the call config snapshot

Whatever you configure here becomes an entry in the canonical snapshot's tools[] array. After resolution, the snapshot contains:

{
  "tools": [
    {
      "type": "endCall",
      "name": "end_call",
      "description": "<your When-to-end prompt>",
      "config": {
        "messageType":    "custom",
        "customMessages": ["<farewell variant 1>", "<farewell variant 2>"]
      }
    }
  ]
}

If you save or POST a config without any endCall entry, this exact tool is auto-seeded with the default trigger prompt and messageType: "custom" speaking the single farewell "Goodbye!" — a round-trip always returns at least one.

Multiple endCall tools are allowed via the API — give each a distinct name (e.g. end_call and end_call_escalate) and its own trigger description, and the LLM sees them all as separate functions. The first endCall entry is canonical: its delivery config drives the farewell for the automatic end paths (idle timeout, max duration), and this section edits it. Additional entries appear read-only in the Tools tab. See Inline tool format → endCall.

End reason is captured automatically

You do not configure or request an end reason. The runtime sets call.end_reason to exactly one of these enum values based on which exit branch fired:

These enum values map 1:1 onto the public endedReason field on the call row and webhooks (agent_hangup, user_hangup, max_duration, silence_timeout, voicemail; disconnect surfaces as cancelled, error as pipeline_error) — see endedReason values.

Programmatic equivalent

Setting the trigger prompt, farewell custom, and message Thanks for calling — goodbye! in this section produces the same snapshot as POSTing this endCall block via the saved-tool API:

curl -X POST https://dashboard.zoxa.ai/api/v1/tools \
  -H "X-API-Key: zsk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "End call when done",
    "description": "<your trigger conditions>",
    "category": "endCall",
    "definition": {
      "schema_version": 1,
      "type": "endCall",
      "config": {
        "messageType":   "custom",
        "customMessage": "Thanks for calling — goodbye!"
      }
    }
  }'

Or directly inline on a transient POST /api/v1/call — see inline endCall.

Tools Tab

Attach Tools

The Tools tab attaches saved tools to extend your agent's capabilities during calls — looking up data, booking appointments, calling external APIs. Use the Add Tools button in the section header.

The config.tools[] array holds a mix of UUID string references (saved tools you select here) and inline tool objects (the mandatory endCall entry configured on the Agent tab, plus any function/query/transferCall tools added via the API). Inline tools created through the API — including any additional endCall tools beyond the first — are shown read-only here so they survive edits. See Tools → tool types and inline tool format.

Engine Tab

The Engine tab holds every model-specific setting plus the low-level pipeline behavior. The middle tabs never select a model — the right-panel chips do — so the Engine tab's Transcriber, Voice, and Model sections always follow whatever the chips have selected. Their available knobs change with the provider.

Sections, top to bottom:

Turn Taking

How the agent decides you've finished speaking, and when you may barge in.

Turn detection is always provider-native: each transcriber's own turn model decides when you've finished speaking, and there is nothing to configure. Tune end-of-turn behavior with each provider's own dials in the transcriber section (uniform 2 s silence cap by default).

The one turn-taking setting is barge-in:

Noise Suppression

Voice isolation applied to the caller's audio before transcription — a single on/off card in the editor, on by default. When on, the engine isolates the nearest speaker and removes background voices at full strength.

Turning the toggle on reveals two knobs, mirrored in the API (noiseGate.model — voice-focus or noise-suppression — and noiseGate.enhancementLevel, 0–1, default 0.8). Voice focus isolates the nearest speaker and removes background voices; noise suppression is general background cleanup. See the Agent Config schema.

Transcriber Settings

Advanced tuning for the currently selected STT provider + model (the Transcriber chip). The available knobs differ per provider — for example:

Full per-provider tables live on the STT Providers page.

Voice Settings

Advanced tuning for the currently selected TTS provider + model (the Voice chip). Examples:

Full per-provider tables live on the TTS Providers page.

Model Settings

Exactly two dials for the currently selected LLM provider + model (the Model chip): temperature (default 1.0) and max output tokens (default 251). Both are always-on sliders — there is nothing to enable or disable, and no other sampling knobs exist.

Prewarm — the throwaway request that warms the model the instant a call starts so the first reply is as quick as the rest — is always on behind the scenes; there is no switch for it.

See LLM Providers for the model catalog and per-model metadata.

Call Tab

The Call tab configures call duration limits, idle behavior, and the human-feel audio layer (background sound, task sound, acknowledge sounds, filler words).

Call Limits

Voicemail Detection

Recording

Background Sound

A faint, continuous environment sound mixed under the whole call — it removes the tell-tale digital silence of a bot line. Off by default; knobs appear when enabled. Config key: backgroundSound.

Task Sound

Keyboard typing or page-turning while the agent runs tools and lookups — like a human agent working at their desk. Purely an audio layer: what the agent says before a tool runs is owned by the tool's own messages. If the tool speaks one, the sound starts after that line finishes (plus the start delay); for silent tools it starts straight into the dead air. Either way it stops the instant the agent starts speaking again. Off by default. Config key: taskSound.

Acknowledge Sounds

Short acknowledgements ("hmm", "okay") in the agent's own voice while the caller speaks at length — signals active listening the way a human agent does. The words are captured once per call in the agent's real TTS voice and mixed directly into the audio, so they never appear in transcripts and can never interrupt or be interrupted by real speech. Off by default. Config key: acknowledgeSounds.

Filler Words

Natural speech fillers over response latency — the trick human agents (and leading voice assistants) use to cover the thinking gap. If the answer hasn't started within the threshold after the caller finishes speaking, the agent instantly says a filler word ("so", "yeah") in its own voice. The word does appear in the transcript — as the spoken prefix of the answer it precedes, exactly as heard. Off by default. Config key: fillerWords.

There is deliberately no volume knob: the filler is the spoken prefix of the answer the voice then continues, so it always plays at exactly the agent's voice level — any offset would make the seam between the filler and the answer audible.

Analytics Tab

The Analytics tab configures post-call processing: webhooks and conversation summarization.

Post Call Tasks

Testing Your Agent

The right panel is a live test surface. You can:

• Browser call -- Click the "Talk to Agent" button or press Alt+T / Option+T to start a test call directly in your browser. The connection uses SmallWebRTC (peer-to-peer WebRTC with a data channel for live transcript events) — no third-party room service. The talk panel streams the conversation as it happens: your interim speech updates in place until it finalizes, and the agent's reply streams in token by token. During the call, mute with Cmd+M / Ctrl+M and end with Cmd+E / Ctrl+E.
• Telephony mode -- A test-only toggle above the talk panel. When on, the browser test call is fed through the same 8 kHz μ-law audio path a real phone call uses, so you hear exactly what a caller would hear. It is never saved to the agent and is forced off on real telephony calls. See the callout below.
• Phone call -- Click "Get Call" to open the phone dialog and place a test call to a real phone number via your configured telephony provider (v2 outbound call).
• Code preview -- Click the code icon to view the full agent configuration as JSON. This is literally the API request body — copy it straight into POST /api/v1/agents.

Save your agent with Cmd+S (Mac) or Ctrl+S (Windows). The editor shows an "Unsaved" badge when you have pending changes.