Validation

POST /v1/agents/{agent_id}/validate runs every check a publish runs and publishes nothing. It returns {"errors": [...], "warnings": [...]}. Errors block a publish; warnings do not. Publishing returns the same warnings on success. Needs the editor role.

curl -X POST https://api.talqing.com/v1/agents/9f1c0a3e-4b21-4f7a-9c6d-2a5b8e13d704/validate \
  -H "Authorization: Bearer $TALQING_API_KEY"

const report = await talqing.agents.validate({ agent_id: "9f1c0a3e-4b21-4f7a-9c6d-2a5b8e13d704" });
if (report.errors.length) throw new Error(report.errors.join("\n"));
report.warnings.forEach((w) => console.warn(w));

report = talqing.agents.validate("9f1c0a3e-4b21-4f7a-9c6d-2a5b8e13d704")
if report["errors"]:
    raise SystemExit("\n".join(report["errors"]))

When checks run

Most checks also run on every create and PATCH, so a stored draft is never arbitrarily broken. These run only on validate, publish and per-call resolution:

A provider key for every provider the agent needs.
The operation trees of attached and hook tools, against this agent’s variables.
What the agent is assigned to (phone numbers, streams, triggers, batches).
Warnings about inactive integrations and empty FAQs.

A few states fail earlier, at parse time, as a 422 naming the field — they can never be stored, so validate never reports them: out-of-range values, unknown fields, a bad IANA timezone, and keypad_input, voicemail_detection or vision_input.screenshare enabled on a channel or pipeline that cannot use them.

The error envelope

Failures are a 400 in the standard error envelope:

{
  "detail": {
    "message": "this agent has validation errors",
    "errors": ["tool 'check_order' has no published version - publish it before attaching"]
  }
}

Request	`message`
`POST /v1/agents`, `PATCH /v1/agents/{agent_id}`	`this agent config has problems`
`POST /v1/agents/{agent_id}/publish`	`this agent has validation errors`
`POST /v1/agents/{agent_id}/versions/{version}/rollback`	`rolling back would break what this agent is assigned to`
A call request with `agent`, `agent_override` or `agent_team`	`the resolved agent config is invalid`

The SDKs expose the list as error.errors.

Common refusals

Messages are abbreviated; search for the quoted fragment.

Models

Refused when	Message contains	Fix
A slot the channel needs is empty	`voice agents need a text-to-speech model`	Voice/video need `stt`+`llm`+`tts` or `realtime`; text needs `llm`
A `provider`/`model` pair is not in the catalog	`unknown LLM model 'openai/…' - pick from:`	Use an exact pair from `GET /v1/catalog`
The model does not run on this channel	`does not support channel`	Pick a model listing the channel
`fallback` equals the primary	`same model as the primary`	Pick another, or remove it
STT fallback is batch and primary streaming (or reverse)	`speech-to-text fallback must match the primary`	Same kind on both. See model fallbacks
`speed` unsupported or out of range	`does not support speed` / `must be between`	Use the catalog range, or `1.0`
`reasoning_effort` unsupported or not offered	`has no thinking setting` / `does not support thinking effort`	Use a value the entry lists. See reasoning
`priority: true` with no lane, or on the analysis model	`has no priority lane` / `cannot use the priority lane`	Turn it off. See priority lane
A built-in tool the model lacks, duplicated, or with unknown/missing/conflicting options	`has no built-in tool` / `is switched on twice` / `has no option` / `needs` / `cannot set both`	Match the model’s catalog entry
Realtime with `greeting_interruptible: false`	`the greeting cannot be protected`	Make it interruptible, or use the cascade
Realtime with `on_user_turn_completed`	`hook would never run`	Remove the hook. See lifecycle hooks
`max_silence_duration` < `min_silence_duration`	`maximum silence must be at least the minimum`	Fix the pair. See turn handling

Voice, avatar, language

Refused when	Message contains	Fix
`stability`/`similarity_boost` on a non-ElevenLabs model	`has no stability or similarity_boost setting`	Clear them. See voices
`expressive: true` on a model without a tag dialect, or differing between primary and fallback	`cannot speak delivery tags` / `set both the same`	See expressive delivery
Video without `avatar_id` / `model`, or an unknown avatar model	`video agents need an avatar` / `need an avatar model` / `unknown avatar model`	See video avatars
Unknown noise-cancellation model (only while enabled)	`unknown noise cancellation model`	See audio processing
Unknown `language`, a model (or fallback) that does not speak it, or Auto on a model that cannot detect	`unknown language` / `does not support Tamil` / `does not detect languages on its own`	See language

Prompt, greeting and variables

Full rules on variables.

Refused when	Message contains
Unknown template root (`{{name}}`, `{{customer.number}}`)	`which is not a variable - it would be sent exactly as written`
A whole bag (`{{userdata}}`)	`which is the whole userdata bag`
Unknown `system_vars` key	`which is not a system variable`
Clock variable without `timezone`	`but this has no timezone`
`{{secrets.}}`, `{{args.}}`, `{{tooldata.*}}` in prose; `{{recording.notice}}` outside the greeting	`cannot use {{…}}`
`{{consent.notice}}` anywhere	`which was renamed - write {{recording.notice}} instead`
A variable declared twice	`declared more than once`
A `required` variable with no default on an agent that answers a phone number	`is required and has no default, and this agent answers inbound calls on`

What the agent is assigned to

Checked on publish and rollback. A batch with its own pinned cast and a disabled trigger are not checked here.

Refused when	Message contains	Fix
Leaving `voice` with a phone number, stream connection or active batch on it	`needs a voice agent and this agent is`	Switch back, unassign, or cancel the batch
Leaving `text` with an enabled integration trigger on it	`needs a text agent`	Switch back, or repoint the trigger
A new required variable an active batch cannot supply	`supplies no value for it`	Give it a default or cancel the batch

Tools, MCP servers, FAQs, tasks

Refused when	Message contains
Tool id malformed or missing	`is not a valid id` / `not found`
Tool never published	`has no published version - publish it before attaching`
Two tools (attached, hook, generated) share a name, or a tool shadows a built-in tool	`two tools on this agent are named` / `which is what the model's own built-in tool is called`
Inline tool with a reserved name or no operations	`is reserved by the platform` / `add at least one operation`
Hook tool containing a `transfer`, or reading args it is not given	`hook cannot use tool` / `is not a declared tool parameter`
A `{{secrets.…}}` in any operation but `http` (a `code` op reads `input.secrets`)	`a secret can only be sent by an http operation or read by a code operation`
Integration missing, not MCP-capable, or attached twice	`not found` / `is not MCP-capable` / `is attached twice`
Two MCP servers under one `tools_namespace`	`both present their tools under`
FAQ missing or attached twice	`FAQ … not found` / `is attached twice`
Attached task unpublished, or its tools contain a `handoff`	`has no published version` / `contains a handoff`

Tool operation-tree errors are described on templating and data.

Handoffs

Refused when	Message contains
Duplicate destination names, or a name with no letters/digits	`names must be unique` / `has no letters or digits`
Target missing or unpublished	`not found` / `has no published version`
Target on another channel or pipeline	`does not match source channel` / `must use the same pipeline`
Video target with a different face	`video handoffs require the same avatar`
Expressive source handing to a different voice	`must keep the same voice`
Name-only destination with no matching team member	`is neither a team member nor a published agent`

See handoffs.

Recording, analysis, memory, vision

Refused when	Message contains
`recording.notice` set with recording off, on realtime, with no greeting, or a greeting without `{{recording.notice}}`	`a recording notice …` / `recording.notice is set, so the greeting must contain`
A greeting containing `{{recording.notice}}` while `recording.notice` is `null`	`but recording.notice is not set`
Analysis enabled but producing nothing	`nothing is switched on to produce`
Unknown analysis model, or none to inherit	`unknown analysis model` / `has no model to run on`
`conversation.context: "summary"` without analysis summaries	`needs call analysis to be writing summaries`
Screen share on an LLM (or fallback) without vision	`cannot read images, so it cannot see a screen`

See recording, call analysis, conversation memory, vision.

Provider keys

no Deepgram API key for this workspace - add one under Provider keys — every provider the agent uses needs a key: LLM, STT, TTS, realtime, avatar, noise cancellation (while enabled), every fallback, the analysis model if set, and every attached task’s model.

Warnings

Warning contains	Meaning
`cannot read images, so photos and scanned PDF pages people send are kept but not seen`	Model has no vision
`reads images but the fallback … cannot`	Images stop after a failover
`which is not declared` (`{{vars.x}}`)	Empty unless the request supplies it
`is not a workspace secret - every session must supply it`	A tool reads a secret only a session’s `secrets` can provide; an inbound session gets it only from your inbound webhook
`never runs on a phone number - this will always be empty`	A phone `system_vars` key on a video agent
`a machine timestamp a text-to-speech voice cannot say`	`{{system_vars.now}}` in a spoken line
`word-count interruption needs interim transcripts`	`min_words` on batch STT
`resolves only when this agent runs in a team`	Name-only handoff destination
`recording cannot start part-way through a call`	Handoff into a recording-on agent from one with it off
`nothing hands off to '…'`	Unreachable team member
`requires a variable '…' that this agent does not declare`	An attached task will ask the model for it
`has no questions yet`	Empty attached FAQ
`needs reconnecting` / `is disabled`	Integration’s tools are left out

Versions

Publishing and rollback.

Errors

The error envelope and status codes.

Get started

Build

Guides

When checks run

The error envelope

Common refusals

Models

Voice, avatar, language

Prompt, greeting and variables

What the agent is assigned to

Tools, MCP servers, FAQs, tasks

Handoffs

Recording, analysis, memory, vision

Provider keys

Warnings

Next

Versions

Errors

​When checks run

​The error envelope

​Common refusals

​Models

​Voice, avatar, language

​Prompt, greeting and variables

​What the agent is assigned to

​Tools, MCP servers, FAQs, tasks

​Handoffs

​Recording, analysis, memory, vision

​Provider keys

​Warnings

​Next

Versions

Errors

When checks run

The error envelope

Common refusals

Models

Voice, avatar, language

Prompt, greeting and variables

What the agent is assigned to

Tools, MCP servers, FAQs, tasks

Handoffs

Recording, analysis, memory, vision

Provider keys

Warnings

Next