Agent Config schema

AgentConfig is one schema used everywhere an agent is described:

• POST /agents and PATCH /agents/{uuid} — the saved agent's config
• POST /call agent field — a transient inline agent (nothing saved)
• POST /agents/preview-snapshot — resolve and inspect without saving
• Every call's stored config_snapshot — the exact config the call ran with

There are no separate "saved" and "call-time" flavors: the same fields, defaults, and validation apply on every path. Field names are camelCase on the wire.

For the dashboard UI that produces this config, see Agents.

Minimal valid config

Only three things are required: a name and an llm block with provider + model. Everything else has a sensible default.

{
  "name": "Support Agent",
  "systemPrompt": "You help customers with orders. Be brief and warm.",
  "llm": { "provider": "openai", "model": "gpt-5.4-mini" }
}

name, llm, stt, and tts are required — for stt/tts, { "provider": ... } is enough (a null model resolves to the provider default). Omitted optional sections are filled with the defaults shown throughout this page, and an end_call tool is always seeded (see tools).

Top-level fields

Languages

languages is an ordered list of language ids — the first entry is the primary language; there is no separate "primary" field. Later entries are secondary hints for code-switching (how they are consumed depends on the transcriber: Soniox, Flux multi, and AssemblyAI take the whole list as hints; Sarvam uses the single language, or auto-detects when several are selected; Cartesia detects the language itself).

Valid ids: en, hi, gu, ta, te, es, fr, ja, de, zh, ar, pt, ru, mr, bn, kn, ml, pa, ur, id, or, ne.

Validation is fail-closed: every listed language must be supported by both the chosen STT model and the chosen TTS model, or the request is rejected with a message naming the unsupported languages. Unknown ids are a hard error (never silently dropped — that could silently change your primary). Duplicates are deduplicated keeping the first occurrence. With AssemblyAI STT, at most 10 languages can be selected (AssemblyAI's per-session limit); more is rejected. Per-provider support matrices: STT providers · TTS providers.

{ "languages": ["en", "hi"] }

Greeting

Controls the opening moments of every call.

{
  "greeting": {
    "firstMessages": ["Hi, this is Maya from Acme — how can I help?"],
    "interruptible": false,
    "speakFirst": "agent",
    "agentDelayS": 0.0,
    "userTimeoutS": 3.0
  }
}

LLM

{
  "llm": {
    "provider": "openai",
    "model": "gpt-5.4-mini",
    "temperature": 1.0,
    "maxTokens": 251,
    "prewarm": true
  }
}

These are deliberately the only sampling knobs — topP, penalties, and seeds are not exposed; providers run on their own defaults.

Transcriber (stt)

Top-level selection plus one tuning block per provider. Only the block matching provider is used — the others may be present (handy when switching) and are simply ignored.

{
  "stt": {
    "provider": "soniox",
    "model": null,
    "interruptionMinWords": 0,
    "soniox": { "contextTerms": "", "endpointSensitivity": 0.3, "endpointLatencyAdjustmentLevel": 2, "maxEndpointDelayMs": 2000 }
  }
}

stt.soniox

stt.flux

stt.assemblyai

stt.sarvam

stt.cartesia

Thresholds must satisfy turnEndThreshold < turnEagerEndThreshold < turnStartThreshold — violations are rejected.

Voice (tts)

Same pattern as the transcriber: top-level provider / model / voice, plus one tuning block per provider.

{
  "tts": {
    "provider": "elevenlabs",
    "model": null,
    "voice": null,
    "elevenlabs": { "stability": 0.5, "similarityBoost": 0.75, "style": 0.0, "useSpeakerBoost": true, "speed": 1.0, "autoMode": true, "applyTextNormalization": "auto" }
  }
}

Per-provider voice tuning

Eleven v3 (eleven_v3_conversational) and Eleven v4 Turbo (eleven_v4_turbo) stream over ElevenLabs' Text-to-Dialogue connection, which accepts only stability. The other tts.elevenlabs fields are still validated and saved, but have no effect on those two models — they apply to eleven_flash_v2_5. To change speaking pace on v3 or v4 Turbo, use a different model; neither offers a speed control.

Noise gate

Input noise suppression / voice isolation applied to caller audio before transcription. On by default.

{ "noiseGate": { "enabled": true, "model": "voice-focus", "enhancementLevel": 0.8 } }

Human-feel audio

Four independent sections that make the agent sound less like a bot. All off by default — a disabled section has zero runtime footprint.

backgroundSound

Faint continuous ambience under the whole call — removes the tell-tale digital silence of a bot line.

taskSound

Keyboard typing or page turns while the agent runs tools — like a human agent working. Audio-only: what the agent says before a tool is owned by the tool's own messages. Starts after the tool's spoken message finishes (or straight into the silence for silent tools); stops the instant the agent speaks again.

acknowledgeSounds

Short acknowledgements ("hmm", "okay") in the agent's own voice while the caller speaks at length. Never appears in transcripts.

fillerWords

If the answer hasn't started within the threshold after the caller finishes, the agent instantly speaks a natural filler ("so", "yeah") to cover the thinking gap. The word does appear in the transcript — as the spoken prefix of the answer.

There is deliberately no volume knob: the filler is the spoken prefix of the answer, so it always plays at exactly the voice's level.

Tools

tools is a single array mixing two kinds of entries:

• UUID strings — references to saved tools from POST /tools
• Inline tool objects — full definitions living inside the config

{
  "tools": [
    "b7e2a1c4-5d6f-4a8b-9c0d-1e2f3a4b5c6d",
    {
      "type": "function",
      "name": "check_order_status",
      "description": "Look up the status of the caller's order by order id.",
      "config": {
        "server": { "url": "https://api.acme.com/orders/status", "method": "POST" },
        "parameters": { "type": "object", "properties": { "order_id": { "type": "string" } }, "required": ["order_id"] },
        "messages": ["Let me pull that up for you."]
      }
    },
    {
      "type": "endCall",
      "name": "end_call",
      "description": "End the call when the user says goodbye or the conversation is finished.",
      "config": { "messageType": "custom", "customMessages": ["Thanks for calling. Goodbye!"] }
    }
  ]
}

Inline types: function (HTTP), query (knowledge base), endCall, transferCall, testTool. Full field reference for each: Tool types.

Rules enforced at validation:

• endCall is mandatory and auto-seeded. If your config has no endCall tool, the default one (name: "end_call", farewell "Goodbye!") is appended automatically — every stored and returned config includes it.
• Tool names are 1–64 chars of [a-zA-Z0-9_-], must be unique after sanitization to LLM-function form (book-slot and book_slot collide), and must not use the reserved names end_call / retrieve_from_knowledge_base / safe_calculator (except endCall-type tools, which may use end_call).
• Spoken messages arrays on tools follow the same variant rules as everywhere else: ≤5 entries, blanks dropped, ONE spoken per invocation. Tool messages additionally carry a messagesOrder knob ("random" default / "in-order" = sequential within a call, wrapping); greeting and endCall variants are always random.

Message variants

Every spoken static message in the config is a list of up to 5 entries. How the list is consumed is fixed per context:

Validation summary

• Strict schema — unknown keys anywhere fail with 400 and the exact field path.
• languages: unknown ids rejected; every language must be supported by both the chosen STT and TTS model; at most 10 with AssemblyAI STT.
• llm.temperature above 1.0 is clamped for Anthropic.
• Cartesia STT threshold ordering (end < eagerEnd < start) is enforced.
• xAI voices and Inworld model ids are validated against their fixed catalogs.
• HTTP tool URLs must be http(s):// and may not target private/internal IPs or metadata endpoints.
• endCall is seeded when absent; messageType: "custom" requires a non-empty customMessages, "audio" requires audioRecordingId.