Agents

An agent is the core unit in VOCALS. It defines how an AI voice assistant behaves on a call -- what it says, how it sounds, and which providers power it. Each phone number is assigned to one agent.

Creating an Agent

1. Navigate to Agents in the dashboard.
2. Click Create Agent.
3. Give the agent a descriptive name (e.g., "Inbound Sales - English" or "Support Tier 1").
4. Configure the settings described below.
5. Click Save.

Agent Settings

System Prompt

The system prompt defines the agent's personality, instructions, and constraints. This is the most important setting -- it determines everything about how the agent behaves in conversation.

You are a friendly customer support agent for Acme Corp. Your name is Sarah.

Your responsibilities:
- Answer questions about our products and pricing
- Help customers troubleshoot common issues
- Escalate complex technical problems to a human agent

Rules:
- Never discuss competitor products
- Always confirm the customer's name before making account changes
- Keep responses concise -- aim for 1-2 sentences per turn

Best practices for system prompts:

• Be specific about response length. Phone conversations need short replies. Instruct the agent to respond in 1-2 sentences unless the caller asks for detail.
• Define a persona. Give the agent a name, tone, and personality. Callers engage better with a consistent character.
• Set boundaries. Explicitly state what the agent should and should not discuss. List topics to escalate to a human.
• Include example phrases. If you want the agent to use specific greetings, confirmations, or closings, include them in the prompt.
• Handle edge cases. Tell the agent what to do when it does not know the answer, when the caller is upset, or when the conversation goes off-topic.
• Keep it structured. Use sections with headers, bullet points, and numbered steps. LLMs follow structured prompts more reliably.

caution

Avoid overly long system prompts. Each token in the system prompt adds latency and cost to every LLM call. Aim for 200-500 words. If you need more, consider whether some information could be retrieved dynamically via function calling instead.

Welcome Message

The first thing the agent says when a call connects. This plays as TTS audio before the agent starts listening.

Examples:

• "Hello, thank you for calling Acme Corp. How can I help you today?"
• "Hi there! This is Sarah from Acme support. What can I do for you?"

Leave this blank if you want the agent to wait for the caller to speak first (useful for outbound calls where the callee answers with "Hello?").

Dynamic Variables

System prompts and welcome messages can include {{variable}} placeholders that are filled in with real values at the moment each call starts. This lets one agent adapt to call-time context -- today's date, the caller's number, a customer's name -- without you editing the prompt for every call.

A placeholder is written as double curly braces around a lowercase name, for example {{date}} or {{customer_name}}. Names may contain lowercase letters, digits, and underscores. Every placeholder is resolved once, at call start, before the system prompt reaches the AI and before the welcome message is spoken. If a placeholder name is not recognised at call time, it resolves to an empty string, so a stray {{...}} is never read aloud or sent to the model.

There are two kinds of variable: built-in variables the system always provides, and custom variables you define per agent.

Built-in variables

These are available on every agent with no configuration. They resolve to the value current at call start.

Variable	Resolves to
{{date}}	The date the call starts, e.g. 2026-07-01.
{{time}}	The time the call starts.
{{timezone}}	The timezone used for date and time. Currently always UTC.
{{caller_number}}	The caller's phone number.
{{called_number}}	The number that was dialed.
{{call_duration}}	Call length in seconds. Always 0 at call start (variables resolve only once).
{{agent_id}}	The agent's unique ID.
{{conversation_id}}	The VOCALS call log ID for this conversation.
{{call_id}}	The telephony provider's call identifier (Call SID).
{{total_turns}}	Total conversation turns so far. Always 0 at call start.
{{agent_turns}}	Turns taken by the agent so far. Always 0 at call start.
{{subagent_turns}}	Turns taken by sub-agents so far. Always 0 at call start.
{{is_text_only}}	true for text-only conversations, false for voice calls.

note

Variables are resolved a single time, when the call begins. Values that change during a call (such as call_duration or total_turns) reflect their call-start value and are not updated mid-call.

Custom variables

Custom variables let you inject your own business values -- a company name, support hours, a customer's first name -- into prompts and welcome messages. Define them in the Custom Variables editor next to the system prompt and welcome message:

1. Add a variable and give it a name (lowercase letters, digits, underscores).
2. Give it a default value. The default is required and cannot be empty -- an agent with a custom variable that has a blank default cannot be saved, and the editor shows an error naming the offending variable.
3. Reference it anywhere in the system prompt or welcome message as {{your_name}}.

The default value guarantees the variable always resolves to something. You can override a custom variable's value for a single call through the call-trigger API -- for example to pass a specific caller's name at dial time -- without changing the saved default.

Authoring help and validation

While editing a system prompt or welcome message:

• Type {{ to open a picker listing every variable available to this agent (all built-ins plus your custom variables). Keep typing to filter the list; select an item to insert the full {{name}} placeholder. Press Escape or click away to close it without inserting.
• Recognised placeholders and unrecognised ones are highlighted in different colours, so a typo like {{ddate}} stands out from a valid {{date}}.
• Saving an agent that still contains an unrecognised placeholder is allowed. A warning names each unrecognised placeholder before you save so you can fix a typo or keep it intentionally.

Dashboard warns, API rejects

The dashboard is a human authoring surface, so it only warns about unrecognised placeholders and lets you save. The call-trigger API is a machine integration surface, so it is strict: passing a variables key that is not a defined custom variable (or that matches a built-in name) is rejected with an HTTP 422 error. See the call-trigger API reference for the exact rules.

Language

The primary language for the conversation. This setting is passed to the STT provider to improve transcription accuracy. Set this to match the language your callers will speak.

Common values: en-US, en-GB, es-ES, es-MX, pt-BR, fr-FR, de-DE, zh-CN, ja-JP.

Barge-in Sensitivity

Controls how easily the caller can interrupt the agent while it is speaking. Barge-in (also called "interruption") stops the current TTS playback and processes what the caller said.

Level	Behavior
Very Low	Requires sustained, clear speech to interrupt. Best for very noisy environments (call centers, streets, factories).
Low	Caller must speak loudly or for a longer duration to interrupt. Reduces false triggers from background noise.
Medium	Balanced setting. Works well for most environments.
High	Agent stops speaking quickly when caller speech is detected. Best for quiet environments.
Very High	Agent stops speaking at the first sign of caller speech. Best for very quiet environments and fast-paced conversations.

tip

If you notice the agent getting interrupted by background noise, lower the barge-in sensitivity. If callers complain the agent talks over them, raise it.

Interruptible

A boolean toggle that enables or disables barge-in entirely.

• Enabled (default): The caller can interrupt the agent mid-sentence.
• Disabled: The agent always finishes its current response before listening. Use this for prompts where the full message must be heard (e.g., legal disclaimers, compliance statements).

Max Call Duration

The maximum length of a call in seconds. When the limit is reached, the agent will say a configurable closing message and hang up.

• Default: 600 (10 minutes)
• Set lower for simple use cases (appointment confirmations, surveys) to control costs.
• Set higher for complex support calls that may need extended conversation.

Silence Threshold

Controls the Voice Activity Detection (VAD) sensitivity for barge-in. This is a float value (default 0.5) that determines how confidently the system must detect speech before triggering a barge-in interruption.

• Higher values (e.g., 0.7 - 0.9) require more confident speech detection, reducing false barge-ins from background noise.
• Lower values (e.g., 0.2 - 0.4) make barge-in more sensitive, picking up quieter speech but also more susceptible to noise.

This works alongside the barge-in sensitivity setting to fine-tune how the agent responds to caller interruptions.

Assigning Providers

Each agent needs one provider for each pipeline stage:

1. In the agent configuration, find the Providers section.
2. Select an STT Provider from your configured providers.
3. Select an LLM Provider.
4. Select a TTS Provider.

You can assign different providers to different agents. For example, your English sales agent might use Deepgram + GPT-4o + ElevenLabs, while your Chinese support agent uses Qwen + Kimi + ElevenLabs.

note

Changing providers on a live agent takes effect on the next call. Active calls continue using the providers that were configured when the call started.

Custom Endpoints

Custom Endpoints let an agent call your own HTTP API during a live call -- with no code and no engineering help. You define an outbound "tool" (for example, "create a lead in my CRM" or "look up an order status"), and the agent decides when to use it based on the conversation. When the agent calls it, VOCALS makes the HTTP request, waits for the response, and feeds the result back into the same turn so the agent can act on it.

You manage an agent's Custom Endpoints from the Custom Endpoints section on the agent detail page, next to Integrations, so all of an agent's callable tools live in one place.

Adding an endpoint

Click Add endpoint and fill in the editor:

• Tool name -- a short lowercase name (letters, digits, underscores) the AI uses to refer to this tool, e.g. create_lead.
• Description -- tells the AI when and why to call this tool. A clear description is the single biggest factor in the AI choosing the tool at the right moment.
• Method -- the HTTP method: GET, POST, PUT, PATCH, or DELETE.
• URL -- the target address, e.g. https://api.example.com/leads. The URL must be a public http/https address.
• Headers -- static request headers, including authentication (see below).
• Request body -- optional. The payload sent with the request, typically JSON.
• Parameters -- values the AI collects from the conversation and supplies when it calls the tool (see below).
• Timeout -- how long to wait for a response, from 1 to 60 seconds (10 seconds by default). If the endpoint does not respond in time, the call is treated as a failure and the conversation continues.
• Enabled -- toggles whether the agent can use the endpoint. A disabled endpoint keeps its configuration but is not offered to the AI.

Click Save. You can add up to 20 endpoints per agent.

Authentication and header security

Add an authentication header (for example Authorization with a value like Bearer <your token>) under Headers.

Header values are treated as secrets: they are encrypted when saved and never shown again. After you save, a stored header value appears as "Value set (hidden)" with a Replace button -- you can overwrite it with a new value, but you can never read the old one back. This is the same write-only handling used for provider API keys.

If an endpoint has an authentication-style header (such as Authorization or X-API-Key) with no stored value, the list shows an Auth missing hint so you can catch the misconfiguration before it fails on a live call.

Using variables and parameters

The URL, each header value, and the request body support the same {{variable}} placeholders as system prompts and welcome messages. Type {{ in any of these fields to open a picker listing everything available here:

• Built-in variables such as {{caller_number}} and {{called_number}} (see Dynamic Variables).
• Custom variables defined on this agent.
• Parameters defined on this endpoint.

Parameters are the values the AI gathers during the conversation and passes in when it invokes the tool. Each parameter has a name, a description (so the AI knows what to collect), a type (string, number, integer, or boolean), and a required/optional flag. For example, define a customer_name parameter, then reference it in the body as {"name": "{{customer_name}}"} -- the AI fills it in from what the caller said.

Editing, disabling, and deleting

• Use the toggle on each endpoint to enable or disable it without losing its configuration.
• Use the pencil icon to edit an endpoint. Stored header values stay hidden; leave them as "Value set (hidden)" to keep them, or click Replace to set a new one.
• Use the trash icon to delete an endpoint you no longer need.

Changes take effect on the next call; calls already in progress are unaffected.

note

If a custom endpoint fails, times out, or returns an error during a call, the agent is told the tool did not succeed and keeps the conversation going. A failed endpoint never drops the call.

Cloning an Agent

To create a variant of an existing agent:

1. Open the agent you want to clone.
2. Click Clone Agent.
3. Modify the settings as needed (e.g., change the language, swap the TTS voice, adjust the system prompt).
4. Save with a new name.

This is useful when you need similar agents for different languages or departments.

Testing an Agent

Coming Soon

Web-based agent testing is a planned feature. Once available, you will be able to test agents directly from the dashboard without making a real phone call.

In the meantime, test your agents by assigning them to a phone number and making a call. Review the call transcript and audio playback in History after the call ends.