Agents

What an agent is, what it is made of, and how changes are tracked.

An agent is a saved configuration for a voice conversation. It holds a personality, a voice, a language, call behaviour, and links to whatever tools and knowledge it should have. Create it once and reach it from anywhere — a phone number, an outbound call, the browser, or your own WebSocket.

Anatomy

An agent has a top level and a config block.

name · string · required

Human-readable name, shown in the dashboard and call logs. Maximum 100 characters.

description · string

Free text for your own reference. Not sent to the model.

status · enum

ACTIVE, INACTIVE, or SUSPENDED. Only ACTIVE agents accept calls.

config · object · required

Everything about how the agent sounds and behaves. Detailed below.

functions · array

Built-in call functions. Each has a type of CALL_TRANSFER, END_CALL, CALENDAR_CHECK, or CALENDAR_BOOK, plus name, description, and config.

corpora · string[]

Corpus IDs to attach. Each becomes a search_{name} tool on the agent automatically. See Corpora.

kbSearchAnnouncement · string

Spoken verbatim before a corpus search, to cover the lookup pause. Maximum 300 characters. See Corpora.

changeNote · string

A note recorded against the version this update creates. Only meaningful on PATCH.

Request and response are not symmetric. You send configuration under config; the API returns it under standardConfig (or customProvider for custom-provider agents), alongside a type discriminator of "standard" or "custom". Read from standardConfig, write to config.

Personality

These four fields are assembled into the agent’s system prompt, in this order.

Field	Purpose
basePrompt	Who the agent is. Role, tone, boundaries. The most important field.
greeting	The exact opening line, spoken verbatim when the agent speaks first.
context	Background facts — hours, address, policies, product names.
customInstructions	Rules of engagement — what to always do, what to never do.
questions	Follow-up questions the agent should work toward answering.

These five fields are assembled into one system prompt in a defined order, with empty fields omitted — see Writing agent prompts.

Put identity in basePrompt and facts in context. Prompts that mix the two tend to drift, because the model cannot tell which parts are its character and which are merely true today. Facts that change often belong in a corpus instead.

Voice and language

languageId · string · required

From GET /languages. Sets the primary language, though the agent auto-detects and can switch mid-call.

voiceId · string · required

From GET /voices. Filter by languageCode and preview with each voice’s previewUrl before choosing.

Model

model · enum · default: "llama"

Which model reasons during the call.

Value	Model	Best for
llama	Meta Llama 3.3 70B	Default. Strongest general reasoning.
gemma	Google Gemma 3 27B	Faster and lighter for simple flows.
glm	GLM 4	Strong multilingual performance.

Call behaviour

See Calls for the full picture. In brief:

temperature · number · default: "0"

Response variability. Accepted range 0–1. Keep at 0 for transactional agents where consistency matters more than personality.

maxDuration · integer · default: "3000"

Hard cap in seconds. Accepted range 60–7200; the default of 3000 is 50 minutes.

firstSpeaker · enum · default: "agent"

agent opens with the greeting. user waits for the caller. Outbound calls always wait, whatever this says — the person answering speaks first.

interruptible · boolean · default: "false"

Whether the caller can talk over the agent’s first message. Later turns are always interruptible.

recordingEnabled · boolean · default: "true"

Whether audio is stored and retrievable after the call.

Attachments

Agents gain capability by linking to other resources:

Tools

Let the agent call your API mid-conversation.

Corpora

Ground answers in your indexed documents.

Phone numbers

Answer inbound calls on a number you own.

Call records

Transcripts, duration, and cost after each call.

Versioning

Every update that actually changes something creates a version — a snapshot of the agent as it was before the edit, with an optional change note.

Updates that change nothing do not create a version, so history stays readable rather than filling with no-op saves. Browse and restore versions from the agent page in the dashboard.

A version snapshot captures the personality fields, language, and voice. It does not currently capture tool assignments, linked knowledge bases, or the call-behaviour settings. Restoring an old version brings back the older wording, but leaves today’s tools and call settings in place.

Workspaces

Agents belong to a workspace. An API key reaches only its own workspace’s agents, and all usage bills to that workspace’s owner — so a team member’s calls are paid by the account that owns the workspace, not by the member.

Lifecycle

# create
POST   /agents

# list
GET    /agents?page=1&limit=50&status=ACTIVE

# read
GET    /agents/{id}

# update — partial, creates a version
PATCH  /agents/{id}

# delete — cascades to config, tools, versions
DELETE /agents/{id}

Updates use PATCH, not PUT. Send only the fields you are changing; omitted fields keep their current values. There is no PUT handler on this resource — a PUT request will not update the agent.

Deleting an agent also deletes its config, tool assignments, and version history. Call records are kept for billing and audit.