Agents

← Back to API Reference

Agents define a voice AI assistant: which STT / LLM / TTS providers to use, the system prompt, available tools, and how to route calls.

Two modes:

Mode	How it works
Freeform	Single LLM turn per conversation, driven by prompt. flow_nodes_count = 0.
Flow	Multi-node finite state machine. Each node has its own prompt and transitions. flow_nodes_count > 0. See Flow Nodes.

---

Contents

• List agents
• Get agent
• Stats
• Create agent
• Update agent
• Delete agent
• Generate with AI
• Import / Export
• Field reference

---

GET /api/agents

List all agents with call counts and flow metadata.

Response:

[
  {
    "id": "uuid",
    "name": "sales-agent",
    "prompt": "You are a helpful sales assistant...",
    "greeting": "Hello {{customer_name}}, how can I help?",
    "stt_provider": "deepgram",
    "stt_model": "nova-3-general",
    "stt_language": "en",
    "llm_provider": "openai",
    "llm_model": "gpt-4.1-nano",
    "llm_settings": { "temperature": 0.1, "max_tokens": 150 },
    "tts_provider": "cartesia",
    "tts_model": "sonic-3",
    "voice": "694f9389-aac1-45b6-b726-9d9369183238",
    "pre_call_tool_ids": [],
    "tool_ids": [],
    "webhook_url": null,
    "webhook_events": [],
    "created_at": "2026-03-18T10:00:00",
    "total_calls": 42,
    "flow_nodes_count": 0
  }
]

---

GET /api/agents/{agent_id}

Get a single agent with full configuration.

---

GET /api/agents/stats

Dashboard statistics — total calls, active calls, per-agent aggregates.

Response:

{
  "total_calls": 1250,
  "active_calls": 3,
  "completed_calls": 1200,
  "failed_calls": 47,
  "avg_duration": 63.4,
  "agents": [
    {
      "agent_id": "uuid",
      "agent_name": "sales-agent",
      "total_calls": 400,
      "completed": 385,
      "failed": 15,
      "avg_duration": 72.1
    }
  ]
}

---

POST /api/agents

Create a new agent.

Minimal request:

{
  "name": "support-agent",
  "prompt": "You are a helpful support agent."
}

Full request:

{
  "name": "sales-agent",
  "prompt": "You are a helpful sales assistant. When the user gives their order number, call check_order.",
  "greeting": "Hello {{customer_name}}, how can I help you today?",

  "stt_provider": "deepgram",
  "stt_model": "nova-3-general",
  "stt_language": "en",
  "stt_settings": {},

  "llm_provider": "openai",
  "llm_model": "gpt-4.1-nano",
  "llm_settings": { "temperature": 0.1, "max_tokens": 150 },

  "tts_provider": "cartesia",
  "tts_model": "sonic-3",
  "voice": "694f9389-aac1-45b6-b726-9d9369183238",
  "tts_language": "en",
  "tts_settings": {},

  "pipeline_settings": {
    "idle_warn_secs": 25,
    "idle_end_secs": 50,
    "vad_confidence": 0.5,
    "vad_start_secs": 0.2,
    "vad_stop_secs": 0.2,
    "vad_min_volume": 0.4,
    "min_words": 3
  },

  "pre_call_tool_ids": ["uuid-of-tool"],
  "tool_ids": ["uuid-of-tool"],
  "context_variables": {
    "customer_name": { "type": "string", "description": "Customer's name" }
  },

  "webhook_url": "https://your-server.com/webhook",
  "webhook_events": ["call_started", "call_ended"]
}

---

PATCH /api/agents/{agent_id}

Update agent configuration. Send only the fields you want to change.

---

DELETE /api/agents/{agent_id}

Delete an agent and all its flow nodes. Calls associated with the agent are kept.

---

POST /api/agents/generate

Generate an agent config from a plain-English description using AI. Returns a config object you can review and submit to POST /api/agents.

{
  "description": "A customer support agent for a SaaS product that handles billing questions and technical issues",
  "language": "English"
}

---

Import / Export

GET /api/agents/{agent_id}/export

Export a portable JSON bundle: full agent config + all flow nodes + all referenced tool definitions. Use this to move agents between environments.

POST /api/agents/import

Import an agent bundle.

{
  "version": "1",
  "overwrite": false,
  "agent": { "name": "sales-agent", "prompt": "..." },
  "tools": [{ "id": "tool-ref-1", "name": "lookup_order", "webhook_url": "https://..." }],
  "flow_nodes": [{ "node_key": "greeting", "is_initial": true }]
}

• Tools are matched by name. Existing tools are reused; missing ones are created.
• UUID references in tool_ids / pre_call_tool_ids are remapped to real DB IDs automatically.
• Returns 409 if the agent name already exists and overwrite is false.

---

Field Reference

Core fields

Field	Required	Default	Description
name	Yes	—	Unique slug. No spaces — used in webhook URLs.
prompt	Yes	—	LLM system prompt. For freeform agents, mention tool_ids tools here to tell the LLM when to use them.
greeting	No	—	First TTS message when call connects. Supports placeholders.

STT (Speech-to-Text)

Field	Default	Options
stt_provider	deepgram	deepgram · sarvam · openai · elevenlabs
stt_model	—	nova-3-general, saaras:v3, whisper-1, …
stt_language	en	BCP-47: en, hi-IN, ta-IN, …
stt_mode	—	Sarvam only: transcribe · translate
stt_settings	{}	Provider-specific options as a JSON object

LLM

Field	Default	Options
llm_provider	openai	openai · google · grok
llm_model	gpt-4.1-nano	gpt-4.1-nano, gemini-2.5-flash, grok-3-beta, …
llm_settings	{}	{ "temperature": 0–2, "max_tokens": int }

TTS (Text-to-Speech)

Field	Default	Options
tts_provider	cartesia	cartesia · elevenlabs · sarvam · deepgram · openai
tts_model	—	sonic-3, bulbul:v2, eleven_flash_v2_5, …
voice	—	Voice ID or speaker name (provider-specific)
tts_language	—	Language tag for multilingual TTS providers
tts_settings	{}	Provider-specific options as a JSON object

Pipeline

Field	Default	Description
pipeline_settings.idle_warn_secs	25	Seconds of silence before the agent prompts the user
pipeline_settings.idle_end_secs	50	Seconds of silence before the agent ends the call
pipeline_settings.vad_confidence	0.5	Voice activity detection confidence threshold (0–1)
pipeline_settings.vad_start_secs	0.2	Seconds of speech required to begin transcribing
pipeline_settings.vad_stop_secs	0.2	Seconds of silence required to stop transcribing
pipeline_settings.vad_min_volume	0.4	Minimum audio volume to register as speech (0–1)
pipeline_settings.min_words	3	Minimum word count before the LLM processes a turn

Tools

Field	Description
pre_call_tool_ids	Tool UUIDs that fire in parallel with the greeting (before conversation starts)
tool_ids	Tool UUIDs the LLM can call during conversation. Freeform agents only — flow agents assign tools per node. Mention each tool in prompt to tell the LLM when to use it.

Outbound calls

Field	Description
context_variables	Schema of variables expected for outbound calls: { "var": { "type": "string", "description": "..." } }. Used for substitution in greeting and flow prompts, and injected as LLM context.

Webhooks

Field	Description
webhook_url	Your endpoint that receives call event notifications
webhook_events	Events to subscribe to: ["call_started", "call_ended"]

See Webhooks for payload formats.