Overview

An agent is one object, config, sent to POST /v1/agents. It decides the channel, the models, what the agent says and what it can do. Tools, MCP servers, FAQs and handoff targets are attached by id inside it. Phone numbers, web call tokens, chats and campaigns all point at an agent.

{
  "config": {
    "name": "Northwind support",
    "channel": "voice",
    "prompt": "You are the support line for Northwind Tools. Answer questions about orders and returns. Look an order up before you talk about it.",
    "greeting": {"message": "Northwind support, how can I help?"},
    "language": "en",
    "timezone": "Asia/Kolkata",
    "stt": { "provider": "deepgram", "model": "nova-3-general" },
    "llm": { "provider": "openai", "model": "gpt-5.6-luna" },
    "tts": { "provider": "deepgram", "model": "aura-2", "voice": "aura-2-thalia-en" },
    "tools": [{ "tool_id": "3f8b0f4c-9a1e-4a7d-9c2b-1d5e6f70a821" }]
  }
}

Only name is required; every other field has a default. The tool id must be a published tool from GET /v1/tools.

Config reference

“Channels” is where a field has an effect. Outside its channels a field is cleared on save, or refused if you switched it on. See channels.

Field	Channels	Default	Meaning
`name`	all	required	Display name, unique in the workspace.
`channel`	all	`voice`	`voice`, `video` or `text`. Decides which model slots exist. Channels
`prompt`	all	`"You are a helpful, concise voice assistant."`	The system prompt. Prompting
`greeting`	voice, video	`{"message": "Hello! How can I help you today?"}`	How the agent opens, on connect and on arrival from a handoff: a fixed `message` or `instructions` for the model. `null`: the agent waits for the caller. Greeting
`greeting_interruptible`	voice, video	`true`	`false` stops the caller cutting the greeting off. Refused on `realtime`.
`language`	voice, video; text with `stt`	`null` (Auto)	The one language every speech model uses. Language
`timezone`	all	`null`	IANA zone for `{{system_vars.now/date/time}}`; required once one is used. Variables
`vars`	all	`[]`	Declared `{{vars.*}}` with defaults. Variables
`elapsed_time`	all	`false`	Prefix each user message the model reads with time since session start. Refused on `realtime`. Prompting
`stt`	voice, video; text (optional)	`sarvam/saaras:v4`; `null` on text	Speech-to-text and its `fallback`; on text it transcribes voice notes. Speech-to-text
`llm`	all	`openai/gpt-5.6-luna`	Language model: `reasoning_effort`, `priority`, `builtin_tools`, `hosts`, `fallback`. Models
`tts`	voice, video	`sarvam/bulbul:v3`	Text-to-speech: `voice`, `speed`, `expressive`, `stability`, `similarity_boost`, `fallback`. Voices
`realtime`	voice, video	`null`	A speech-to-speech model replacing `stt`, `llm` and `tts`. Realtime
`turn_handling`	voice, video	see page	Endpointing, interruptions, preemptive generation. Turn handling
`tools`	all	`[]`	`{"tool_id"}` or an inline `tool`. Tools
`mcps`	all	`[]`	`{"integration_id"}` or an inline `mcp`. MCP servers
`faqs`	all	`[]`	`{"faq_id"}` or an inline `faq`; at most 10. FAQs
`handoffs`	all	`[]`	Agents this one may hand the conversation to. Handoffs
`tasks`	all	`[]`	Agent tasks this agent can enter and return from. Agent tasks
`on_enter`, `on_exit`, `on_user_turn_completed`	all	`null`	Tools run at lifecycle points. `on_user_turn_completed` is refused on `realtime`. Lifecycle hooks
`max_steps`	all	`null` (4 on voice/video, 25 on text)	LLM → tools rounds per turn, 1–50. A handoff keeps the starting agent’s value.
`silence`	voice, video	on, 10 s, 2 check-ins	Check-ins on a quiet caller, then hang up. Silence and call length
`max_duration_seconds`	voice, video	`1800`	30 to 10800; `null` means the 3-hour platform cap. Silence and call length
`background_audio`	voice, video	off	Ambient and thinking sounds. Audio processing
`noise_cancellation`	voice, video	off	Cleans caller audio; needs an ai-coustics key when on. Audio processing
`vision_input`	voice, video	screen share off	Live screen share on web calls; cascade only. Vision and images
`keypad_input`	voice	off	DTMF from the caller. Refused on video and text. Keypad
`voicemail_detection`	voice	off	Outbound voicemail detection. Refused on video and text. Voicemail
`recording`	voice, video	on, `notice: null`	Call recording and the spoken recording notice. Recording
`analysis`	all	on, summary on	Post-call summary, outcome and fields. Call analysis
`conversation`	all	`context: "none"`	What a new session knows about earlier ones. Conversation memory
`avatar`	video	`anam/anam`, default face	The Anam face. Video avatars

An unknown field is refused, not ignored. Defining a tool, MCP server or FAQ inline on POST/PATCH /v1/agents creates it as a stored object and saves its id; on a call request it lasts for that call only (per-call configuration).

Updating an agent

PATCH /v1/agents/{agent_id} takes only the fields you change:

You send	Result
Field omitted	Kept.
`null`	Field cleared. Refused on a field that cannot be null.
An object	Merged key by key, recursively.
An object naming a different `provider`	Started over: the old voice, speed and settings belonged to the old provider. Nested specs like `fallback` still merge.
A list (`tools`, `handoffs`, …) or scalar	Replaced whole. To add a tool, send the full list.
A tool, MCP, FAQ or handoff entry	Replaced whole; a partial entry is refused.
A new `llm.model` without `reasoning_effort`	The old effort is dropped; the new model starts at its fastest.

curl -X PATCH https://api.talqing.com/v1/agents/0f9a1c3e-5d42-4b8a-9c11-6e2f7a4d8b30 \
  -H "Authorization: Bearer $TALQING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"config": {"greeting": {"message": "Northwind support, how can I help?"}}}'

const agent_id = "0f9a1c3e-5d42-4b8a-9c11-6e2f7a4d8b30";

await talqing.agents.update({
  agent_id,
  updateAgentRequest: { config: { greeting: { message: "Northwind support, how can I help?" } } },
});
await talqing.agents.publish({ agent_id });

agent_id = "0f9a1c3e-5d42-4b8a-9c11-6e2f7a4d8b30"

talqing.agents.update(agent_id, config={"greeting": {"message": "Northwind support, how can I help?"}})
talqing.agents.publish(agent_id)

get, create and update return the same shape. Some fields are normalized on save (switching to text clears the speech stack; setting realtime clears the cascade), so read the response rather than assuming your input survived. Every write lands on the draft; live traffic runs the last published version, and publishing pins each attached tool’s version. See versions and validation. In the dashboard, agents are at https://app.talqing.com/agents; the editor opens at /agents/detail?id=<agent id>, with a cost estimate, a test call panel and the CoPilot beside it.

Channels

What voice, video and text each have, and what switching clears.

Models

The catalog, the model slots and their settings.

Get started

Build

Guides

Config reference

Updating an agent

Next

Channels

Models

​Config reference

​Updating an agent

​Next

Channels

Models

Config reference

Updating an agent

Next