@talqing/mcp 0.1.0

package/SKILL.md

@@ -0,0 +1,1270 @@
+---
+name: talqing
+description: >-
+  Build, publish and operate Talqing AI voice, video and text agents — agent
+  config and model stack, custom tools and their operation trees, MCP and
+  messaging integrations, knowledge bases, phone numbers, secrets and webhooks,
+  plus placing calls and reading back transcripts, cost and latency. Use
+  whenever working against a Talqing workspace through the talqing MCP server.
+---
+
+<!-- Generated by openapi/export.py from backend/services/copilot/skill.md. Edit that file, then re-run the export. -->
+
+# Building agents on Talqing
+
+Talqing is a no-code builder for AI voice, video and text agents. Everything you
+can build here you could otherwise have written as a LiveKit agent by hand: a
+model stack, a system prompt, callable tools, knowledge, and lifecycle hooks.
+The same machinery also runs **agent tasks** — an agent nobody talks to, which
+takes named inputs and returns a typed result.
+
+The same surface takes an agent all the way to production: give it a phone
+number, run it, and read back every call it handled.
+
+You reach the platform through one operation per API endpoint. Each operation's
+arguments mirror its HTTP call — path and query parameters at the top level, the
+request body under `body`. Every operation acts as the signed-in user, inside
+their workspace only, with their role's permissions. Managing who is in the
+workspace is the one thing that stays in the dashboard.
+
+## What an agent is
+
+An agent is a single object, `config`, plus what you attach to it:
+
+- **`name`** — unique in the workspace.
+- **`channel`** — `voice` (phone/web call), `video` (a voice agent wearing an
+  Anam avatar) or `text` (chat). The channel decides which model slots exist.
+- **`prompt`** — the system prompt. This is where the agent's behaviour lives.
+- **`greeting`** — the line spoken on connect. Voice and video only.
+
+  Both are personalized per session: `{{userdata.field}}` is substituted from
+  the session's userdata when the agent starts, so *"You are speaking with
+  {{userdata.name}}, a {{userdata.tier}} customer"* becomes a real sentence on
+  the call. A field that is not in userdata resolves to nothing, so write the
+  prompt so it still reads if one is absent. `{{args.…}}` and `{{secrets.…}}`
+  are rejected here — those belong to a tool call.
+
+  A token whose root is not one of ours is an **error**, not text: a bare
+  `{{name}}`, a `{{customer.number}}` pasted from another platform, or a typo
+  like `{{userdate.name}}` is refused when the agent is saved. Rewrite each one
+  onto a real root rather than leaving it in.
+
+  Two more roots are filled in from outside the session, and nothing inside one
+  can write either. They differ in who fills them.
+
+  **`{{system_vars.…}}` — ours.** Six keys, and any other is rejected at save;
+  `GET /v1/catalog` returns them as `system_vars`.
+
+  - `{{system_vars.human_phone_number}}` — the other party, the caller inbound
+    and the person you called outbound
+  - `{{system_vars.agent_phone_number}}` — your number on this call
+  - `{{system_vars.direction}}` — `inbound` or `outbound`
+  - `{{system_vars.now}}` — `2026-08-19T19:26:59+05:30`, the machine format;
+    send it to an API, never read it aloud
+  - `{{system_vars.date}}` — `Wednesday, 19 August 2026`
+  - `{{system_vars.time}}` — `7:26 PM`
+
+  The first three come from the call, so they are empty on web calls and on text
+  conversations — do not make one the only source of a fact the agent needs. One
+  agent can greet a caller and someone it called differently by branching on
+  `{{system_vars.direction}}`. The last three come from the agent's
+  **`timezone`** and work on every channel; using one without setting `timezone`
+  is a save error. In a prompt or greeting the clock is frozen at the moment the
+  agent started (re-resolving would throw away the model's prompt cache); inside
+  a tool it is the moment the tool ran.
+
+  **`{{vars.…}}` — the tenant's.** The agent's own **`vars`** declares them, and
+  the request that starts a session supplies values that override the declared
+  defaults. See **`vars`** below.
+- **`llm`, `stt`, `tts`** — `{provider, model}` from the provider catalog. Text
+  agents have only `llm`; voice and video need all three.
+- **`language`** — the one language the caller and the agent speak, shared by
+  every model. `null` is Auto. Voice and video only.
+- **`timezone`** — an IANA name such as `Asia/Kolkata`. What the three
+  `{{system_vars.…}}` clock variables resolve against, on every channel. `null`
+  until one of them is used, and then required. Set it whenever the agent has to
+  reason about opening hours, "today", or an appointment time.
+- **`vars`** — the variables this agent reads as `{{vars.name}}`, each
+  `{name, description, default, required}`. Names are `[A-Za-z_][A-Za-z0-9_]*`
+  and unique within the agent; `default` is a string or `null`.
+
+  Values arrive on the **request that starts the session** — `vars` on
+  `calls_token`, `create_outbound_call`, `create_call_batch` or
+  `create_text_conversation` — and override the defaults. One bag per session,
+  reaching *every* agent on it: the entry agent, every team member, and a handoff
+  target that was never in the plan, each merged over its own declared defaults.
+  Nothing inside the session can write it.
+
+  Four things to get right:
+
+  - **They are visible to the model.** Anything in `vars` may be read aloud or
+    repeated back. A credential belongs in a workspace secret, read as
+    `{{secrets.NAME}}` from a tool, where the model never sees it.
+  - **`required: true` refuses the session** that supplies no value for a
+    variable with no `default` — the call token, the dial, the batch and the text
+    conversation, before anything is compiled and before any provider is called.
+    An empty string counts as a value; a `default` satisfies it outright. Nothing
+    is enforced once a session is connected, so a handoff target that needs a
+    value nobody supplied reads it as empty rather than ending the call.
+  - **An inbound call or message has no request of ours**, so only the declared
+    defaults resolve — which makes the rule above a hard one for inbound voice: a
+    voice agent that requires a variable with no default cannot answer a phone
+    number at all, and assigning the number, publishing that config under one
+    already assigned, and rolling back to it are all refused. Anything an inbound
+    session needs has to have a default.
+  - **`agent_override.vars` means something different**: it changes an agent's
+    *declarations and defaults* for one call. The top-level `vars` on the same
+    request supplies *values*. Both can appear on one call and they do not
+    conflict — the override decides what is declared, the top-level bag what it
+    is worth.
+
+  Reading `{{vars.x}}` where `x` is not declared is a **warning**, not an error:
+  the key space is open, because an agent or a tool defined inline in the same
+  request may legitimately read one nothing declared beforehand.
+
+  Prefer `userdata` for facts about the *person* and `vars` for configuration of
+  the *session*. `userdata` is merged onto the caller's contact record, replayed
+  into their next conversation, and writable by any tool; `vars` is none of those.
+- **`avatar`** — video only: `{provider, model, avatar_id, name}`.
+- **`turn_handling`** — turn detection, endpointing, interruption and preemptive
+  generation. Voice and video only.
+- **`background_audio`** — ambient and thinking sounds mixed into the agent's
+  output. Any transfer stops the ambient bed while the caller waits and plays
+  hold music instead, so `ambient: hold_music` only sets how loud that is.
+- **`noise_cancellation`** — cleans up the caller's audio before the agent hears
+  it: `{enabled, provider, model, enhancement_level}`, `provider`/`model` from
+  the catalog. Off unless asked for, and it needs that provider's key under
+  BYOK. `enhancement_level` runs 0.0–1.0; 0.5 is conservative, 0.8 is the
+  default, 1.0 suppresses interfering speech hardest. Voice and video only.
+- **`tools`** — published tools the agent's LLM may call mid-conversation, each
+  `{"tool_id": "...", "tool_version": null}`. Write `tool_version` as null (or
+  leave it out): a draft tracks whatever is published now, and publishing fills
+  the version in.
+
+  An entry may instead carry `{"tool": {name, description, json_schema,
+  operations, …}}` — a whole tool written inline. On an agent that is a
+  *shorthand*, not a second kind of tool: `create_agent` and `update_agent`
+  create it, publish v1 and store `{"tool_id": "..."}` in its place, so the
+  agent and its tools can be built in one request. Use it for exactly that.
+  Attaching an existing tool is still `tool_id`.
+- **`kb_ids`** — ready knowledge bases for grounded answers.
+- **`mcps`** — external MCP servers whose tools the agent may call, each
+  `{"integration_id": "..."}` naming an active, MCP-capable integration. Which
+  of a server's tools may be called is the integration's own `allowed_tools`,
+  not this list. As with `tools`, an entry may instead carry `{"mcp": {name,
+  url, headers, allowed_tools}}`, which is created as a `custom_mcp` integration
+  and replaced by its id.
+- **`handoffs`** — where this agent may pass the conversation next, each
+  `{"name": "Billing", "agent_id": "...", "description": "...", "context":
+  "transcript" | "summary" | "none", "recent_turns": 2, "summary_prompt": "...",
+  "message": "..."}`. The compiler turns each entry into one tool the model can
+  call, `handoff_to_<name>`, and the model routes on `description` — so write
+  that as what belongs there ("invoices, refunds, payment questions"), not as an
+  instruction.
+
+  **This is how you build a multi-agent flow.** Do not create a one-node tool
+  per edge: three agents routing to each other is three agents with `handoffs`
+  on them, not three agents plus six published tools. The `handoff` *operation*
+  is still right for a CONDITIONAL handoff — look the account up, and *if* it is
+  enterprise, hand to the enterprise desk — because that decision belongs in an
+  operation tree rather than to the model.
+
+  `agent_id` names a stored agent, entered at its latest published version.
+  Leaving it out resolves `name` against the team defined on the call that runs
+  the agent, which publishes with a warning rather than an error.
+
+  **`context` is what the next agent starts from** — the same three words an
+  agent's own `conversation.context` uses for what a new *call* starts from.
+
+  - `transcript` (the default) hands over everything said so far. Nothing to
+    configure, and the target pays for all of it on every turn it then takes.
+  - `summary` asks THIS agent to write the summary itself, as an argument on the
+    `handoff_to_*` tool, in the same turn as the decision to hand over. There is
+    no second LLM call, so a realtime agent can use it too. It costs a pause
+    before the handoff — the agent writes 60–100 tokens before the tool returns
+    — and buys a short, focused context that the source agent chose, instead of
+    forty turns the target has to re-read every turn.
+  - `none` starts the target with only its own instructions.
+
+  **`recent_turns`** (1–10) is how many recent turns cross *verbatim* alongside
+  the summary, so the target knows what is being asked right now. A turn starts
+  at a user message and runs until the next one, so a turn that took a tool call
+  and two replies crosses whole. Tool calls themselves never cross — their
+  results are knowledge, and knowledge belongs in the summary.
+
+  Leave it out and each policy answers for itself: `summary` carries two turns,
+  and `none` carries none. Under `summary` the tail can be sized down to one turn
+  but **not** switched off — a summary with no tail leaves the target knowing the
+  history and not the question. Under `none` it is opt-in, and `{"context":
+  "none", "recent_turns": 3}` is a real and useful combination: the last three
+  turns and nothing else. Past ten turns the honest answer is `transcript`.
+
+  **`summary_prompt`** replaces the platform's default line with your own. It is
+  the *description of the tool argument*, so it is literally what the agent is
+  asked to write. It takes `{{userdata.…}}`, `{{system_vars.…}}` and
+  `{{vars.…}}` like the description and the message do. The default is one line
+  naming three buckets — what the caller wants, what has been done, what is still
+  open — and a longer one buys a longer pause before the handoff.
+
+  `recent_turns` and `summary_prompt` are **rejected** where they do not apply,
+  rather than ignored: no `recent_turns` under `transcript`, which already
+  carries every turn, and no `summary_prompt` outside `summary`.
+
+  **`summary` is not a privacy boundary, and must not be described as one.** It
+  narrows what the target model is shown; it guarantees nothing. The tail always
+  crosses. `userdata` crosses regardless — it is session state every agent on the
+  call shares. The full transcript is still recorded and still displayed. A later
+  `transcript` hop shows that agent the whole call, including the part `summary`
+  scoped away. And the summary is written by an LLM the caller has been talking
+  to, so it is exactly as trustworthy as anything else the model says. The one
+  thing that does hold is that the source agent's raw tool results do not cross.
+- **`conversation`** — what a new call knows about earlier ones with the same
+  person: `context` is `none` (the default — every call starts clean, though
+  earlier conversations are still saved against that caller), `summary` (the
+  agent is told, as background, what happened on recent ones) or `transcript`
+  (one long conversation across every call). `summary_limit` bounds how many
+  recent calls `summary` describes — leave it out for all of them — and
+  `initialize_userdata` decides whether the call also starts from what the agent
+  learned about this person before.
+
+  This is the answer whenever someone wants an agent to remember, or to forget,
+  earlier calls. **Never write that instruction into the prompt** — a model told
+  to ignore what is in its context is being asked to do the impossible, and a
+  model told to remember cannot see what was never loaded. Set the field.
+  `summary` needs call analysis with its summary switched on, and publish
+  refuses it otherwise. A text agent is always `transcript` and cannot be
+  changed: a chat thread has no boundary anyone would recognise.
+- **`on_enter`, `on_exit`, `on_user_turn_completed`** — one such tool reference
+  each, run as lifecycle hooks.
+
+## Draft and published
+
+Every write lands on the **draft**. Live traffic runs the last **published**
+version, which is an immutable snapshot. Nothing you change reaches a real
+caller until the agent is published.
+
+The order that matters:
+
+1. Create or update the tool, including its operation tree.
+2. `validate_tool`, then `publish_tool`. Attaching an unpublished tool is
+   rejected.
+3. Attach it through the agent's `tools` or a hook.
+4. `validate_agent`, then `publish_agent`.
+
+Publishing an agent pins each attached tool to the tool version that is live *at
+that moment*. Republishing a tool therefore does not change live behaviour until
+the agent is published again — say so rather than leaving the user to discover
+it.
+
+## Writing config
+
+`update_agent` and `create_agent` take the **whole** config, not a patch.
+Anything you leave out reverts to its default — omitting `tools` detaches
+every tool. Always read the current config first, apply your change to it, and
+send the result back.
+
+The config is validated on every write. Unknown models, a model that does not
+support the channel, a language the model does not offer, a speed outside the
+model's range, an unpublished tool, a knowledge base that is not ready — all are
+refused with an explanation. Read the error and correct it; that is faster than
+guessing.
+
+Some fields are normalized for you. Switching to `text` clears `stt`, `tts`,
+`greeting`, `turn_handling` and `avatar`. Switching to `video` fills in an
+`avatar`, and always has `resume_false_interruption` off — the avatar cannot
+resume a sentence it has already stopped rendering.
+
+### Choosing models
+
+`get_catalog` is the only source of valid `provider`/`model` pairs, and it also
+states what each entry supports: which channels, its language codes and default
+language, whether it accepts a speed and within what range, and its default
+voice. Read it before choosing; do not assume a model exists.
+
+### Images
+
+People can attach a photo to a web chat, a web voice call or a web video call,
+and the agent sees it. **There is no setting for this** — whether an agent can
+read images is decided by the model it runs, and `vision` on that model's catalog
+entry is where it says so. Every LLM entry today reads images; the two
+`grok-voice-*` realtime entries do not, and an agent on one of them cannot be
+sent a photo at all. If a user wants image input, check `vision` before picking
+the model rather than changing anything on the agent.
+
+A phone call carries no files, so this is web only.
+
+### Vision input (screen share)
+
+`vision_input` is what the agent *watches* during a call, as opposed to the
+images people send it. Do not confuse it with `vision` on a catalog entry: that
+is what the model *can* do, measured and not configurable, and it is the
+precondition for this.
+
+`vision_input.screenshare.enabled` lets the agent see the caller's screen while
+they share it. On each of their turns the agent is handed the single newest
+frame and only that one, so a long call does not grow slower or more expensive —
+and when nobody is sharing, the agent is told so and asks rather than inventing a
+screen. Set `vision_input.screenshare.record` as well to keep what was shared as a
+1 fps video beside the call recording, deleted under the same retention policy.
+
+Four rules decide whether it can be turned on at all:
+
+- **Web voice and video calls only.** A phone call has no screen to share, and
+  the same agent config over a phone number simply never offers it — no setting
+  changes, and the agent is never told it can see.
+- **Cascade only.** Turning it on with `realtime` set is refused when the agent
+  is saved: a speech-to-speech model detects turns inside the provider's socket,
+  so there is no moment at which it could be handed a frame.
+- **The model must read images.** Publish fails, naming the model, if the LLM or
+  its fallback has `vision: false`. Check `get_catalog` before choosing.
+- **The caller's client has to publish a track.** Our dashboard's test call and
+  the TypeScript SDK's `useTalqingScreenShare` both do; a customer's own surface
+  has to call `getDisplayMedia` from a click, which is a browser rule nothing on
+  our side can work around. So the agent asking out loud is what starts sharing.
+
+It also forces `turn_handling.preemptive_generation` off, because the frame
+changes the context the speculative reply was generated against.
+
+### How long the model may think
+
+**On a voice or video agent, give the model the least thinking it will accept.**
+Every second of reasoning is a second of silence on a live call, and a caller who
+hears nothing assumes the line has dropped. Take the **first** value in that
+model's catalog `reasoning_efforts` list, or leave `reasoning_effort` unset —
+the list is ordered fastest first, and unset already means that first value.
+Raise it only when the user asks for it and accepts the pause, and tell them what
+it costs them in silence.
+
+Do not reason about the effort names, because they do not order the same way at
+every vendor. `minimal` sounds like the floor and is not: on xAI's grok-4.3 it
+burned *more* thinking than `low`, so `none` is the only setting there that
+truly stops it. OpenAI rejects `minimal` outright and starts at `none`. The
+catalog's order is measured; the names are marketing.
+
+A text agent has no such pressure — nobody is listening to silence — so spend
+thinking there freely when the task benefits from it.
+
+Language is set **once**, on the agent: `config.language`. There is no language
+field on `stt`, `tts` or `realtime`. Each model translates the agent's language
+into its own spelling, so Hindi reaches Deepgram as `hi` and Sarvam as `hi-IN`
+without you doing anything. Rules worth knowing before you hit them:
+
+- Use a code that appears in some model's catalog languages; `null` means Auto.
+- A model that publishes languages must be able to speak the one you chose, or
+  the write is refused. Prefer picking the language first, then models that
+  cover it.
+- **A model with `language_required: true` refuses Auto**, because its API has no
+  detection to fall back on — Soniox TTS is like this, and an agent on it will not
+  publish until `config.language` is set. Every other model takes a null
+  `language`. On Soniox TTS the setting is not cosmetic: the code chosen is the
+  phonetic system the text is read through, so English sent as `es` comes out as
+  noise rather than accented English.
+- **Auto is not detection on Raya.** None of its three entries detect anything;
+  they send their `default_language` (`en`) when the agent is on Auto. For a Raya
+  agent taking Indic calls, set `config.language` — Hindi audio transcribed as
+  English does not come back transliterated, it comes back with words missing, and
+  the agent never learns it misheard.
+- **Auto does not mean "detects" everywhere.** A model with a `default_language`
+  runs on that code when the agent is on Auto, and the ones spelled `unknown`,
+  `multi` or `auto` are the providers' own words for detection. The rest are
+  real languages, and English is what a model that cannot detect falls back to:
+  `deepgram/nova-3` and both xAI speech-to-text models transcribe as English on
+  Auto and will mistranscribe a caller who speaks anything else. For an agent
+  taking non-English calls on Auto, pick `deepgram/nova-3-general` (`multi`),
+  `deepgram/flux-general-multi`, `sarvam/saaras:v3` (`unknown`), ElevenLabs
+  Scribe or OpenAI — all of which detect for real.
+- Models that publish no languages (OpenAI TTS is multilingual, Deepgram encodes
+  the language in the voice) simply ignore the setting.
+
+A catalog entry may carry a `note` — a caveat the *prompt* has to answer, not a
+description of the model. Read it before writing the prompt and tell the user what
+you did about it. No entry carries one today.
+
+An STT entry with `streaming: false` transcribes each utterance in one request
+instead of over a socket. That buys a lower price, and costs the round-trip:
+the agent replies about half a second later than it would on a streaming model,
+and word-count interruption stops working because there are no interim
+transcripts. Prefer a streaming model unless price is the point.
+
+`stt`, `llm` and `tts` each take an optional `fallback` — a second
+provider/model the agent switches to mid-call if the primary starts failing.
+Leave it unset unless the user asks for redundancy; it is not free to set up:
+the fallback provider needs its own BYOK key before the agent will publish, and
+a session that fails over is billed to both providers for the parts each one
+served. The fallback must be a different provider/model from the primary, and it
+cannot have a fallback of its own. A speech-to-text fallback must also match the
+primary's `streaming` flag —
+streaming backs streaming, batch backs batch — so end-of-turn timing stays the
+same before and after a failover.
+
+`llm.builtin_tools` — and `llm.fallback.builtin_tools`, separately — switches on the tools the model provider runs itself during
+the reply — web search, X search, a code sandbox, a provider-side document
+store. Each is `{type, config}`, and the *only* valid types and config keys are
+the ones the chosen model's catalog entry lists under `builtin_tools`, so read
+`catalog` before setting them. They are not Talqing tools: there is nothing to
+create, publish or attach, and nothing runs on our side. Two things to tell the
+user before switching one on — the provider bills per call, which our cost
+estimate does not include; and the search or code run happens *before* the agent
+speaks, which on a voice call is a few seconds of silence, so the prompt should
+have the agent say it is looking something up. The failover model carries its
+own list, set against its own catalog entry: the same tool name is a different
+object at each vendor, so one model's settings are never copied to the other. A
+failover with fewer tools (or none) is fine — it keeps the call and loses the
+search, which is the right way round.
+
+`catalog_voices` browses the voices for a provider — use it before picking a
+voice by style, accent or gender. `catalog_avatars` is the face gallery for
+video agents; an avatar's `id` becomes `avatar.avatar_id`, while `avatar.model`
+comes from the provider catalog.
+
+**Setting an ElevenLabs voice takes one more step.** After choosing the voice —
+and, for a shared-library voice, after `add_elevenlabs_voice` has saved it — call
+`elevenlabs_voice_settings` with the id you are going to use and copy the
+`stability` and `similarity_boost` it returns onto the same `tts` object as the
+voice. ElevenLabs applies a voice's own tuning only to a request that carries no
+overrides at all, and Talqing always sends a speed, so a voice set without these
+speaks in ElevenLabs' generic default instead of the voice its author shipped —
+audibly, and with nothing to show why. They belong to that voice: replace them
+whenever you change it, and clear them if you move to a model whose catalog entry
+does not set `supports_voice_settings` (only ElevenLabs does), which agent
+validation refuses outright.
+
+### Expressive delivery
+
+`tts.expressive` lets the agent write delivery tags — a laugh, a whisper, a
+pause before the key detail — into the words it speaks. Only for a model whose
+catalog entry carries an `expressive` block; that block's `prompt` is what gets
+appended to the agent's system prompt, and the tag vocabulary is inside it. Read
+it before writing a tag anywhere yourself: the dialects differ per model, and a
+tag from the wrong one is silently dropped rather than spoken.
+
+It costs a little on both sides of a turn — the added prompt, and every tag the
+model emits as billed output. Say so before switching it on.
+
+Two rules the API enforces, both at publish:
+
+- A fallback voice must match the primary's `expressive` setting. The dialect is
+  taught once, from the primary, and a failover happens mid-turn — so the
+  fallback has to be a voice that speaks tags too. In practice that means the
+  two dialect models back each other, or there is no fallback.
+- Every handoff target of an expressive agent must use the **same** provider,
+  model and `expressive` setting. The target inherits a transcript full of tags
+  and starts writing its own; a voice that cannot speak them reads them out.
+  Handing off *into* an expressive agent is fine.
+
+**Nothing validates a tag you write by hand** into a greeting, a `say` line or a
+handoff message. On a voice with no dialect it reaches the caller as the word
+itself, so do not put one there unless the agent's own voice speaks it.
+
+### Turn detection
+
+**There is no setting for this.** What ends the caller's turn follows from the
+speech-to-text model and `config.language`, so do not go looking for a knob and
+do not promise the user one — change the models or the language instead:
+
+- **Streaming speech-to-text** → its own end-of-speech detector ends the turn. It
+  can keep listening when it hears the caller is not finished, so
+  `endpointing.min_silence_duration` is the window it gets rather than the whole
+  wait, and its transcription round-trip lands on top. Deepgram Flux and Sarvam
+  Saaras endpoint on their own schedule and ignore that window entirely, so on
+  those two the setting is a floor.
+- **Batch speech-to-text** (`streaming: false` — xAI `xai-stt-batch`, ElevenLabs
+  `scribe_v2`, OpenAI `gpt-4o-transcribe`) → it has no endpointer at all, so
+  LiveKit's audio end-of-turn model takes over when `config.language` is one of
+  the fourteen it was trained on: Arabic, Chinese, Dutch, English, French,
+  German, Hindi, Indonesian, Italian, Japanese, Korean, Portuguese, Spanish,
+  Turkish. It judges whether the *sentence* sounds finished, so it waits through
+  a caller who pauses mid-thought ("I need to think about that for… a moment").
+  Any other language, or Auto, falls back to plain silence.
+
+So if the user complains the agent cuts people off mid-sentence, the lever is a
+batch model plus one of those fourteen languages — that is the only pipeline that
+hears meaning rather than silence. Otherwise raise
+`endpointing.min_silence_duration` (minimum 0.25s).
+
+`endpointing.max_silence_duration` is how long the agent waits when the end-of-turn
+model says the caller is mid-thought, so it only does anything on that same
+batch-plus-supported-language pipeline.
+
+### Video
+
+`channel: "video"` is a voice agent wearing an Anam avatar. The avatar joins the
+call as a second participant and lip-syncs to the agent's own audio, whichever
+model produced it — so video runs on either pipeline, the STT-LLM-TTS cascade or
+a realtime speech-to-speech model, and everything true of that pipeline on
+`voice` stays true here.
+
+A video agent needs both an avatar model and an `avatar_id` before it will
+publish; `get_catalog` lists the avatar models and `catalog_avatars` the faces.
+Avatar time bills per wall-clock minute for the whole call, idle included, on top
+of whatever the models cost.
+
+## Tools
+
+A tool is one capability the agent's LLM can call mid-conversation. It has:
+
+- **`name`** — the function name the LLM sees. A valid identifier, snake_case,
+  describing the capability. `knowledge_fetch` is reserved.
+- **`description`** — tells the LLM *when* to call it. This matters as much as
+  the implementation.
+- **`json_schema`** — the arguments the LLM supplies. Declare only values the
+  agent can know or ask the caller for. **Give every property a `description`**:
+  it is the only instruction the agent's model gets on what to put there and how
+  to get it out of the conversation, and a bare `{"type": "string"}` is how a
+  tool ends up called with the wrong value. Mark the ones the tool cannot run
+  without as `required`, and use an `enum` wherever the set of values is closed.
+- **`long_running_task`** — voice and video agents keep talking while it runs;
+  text agents wait for the result either way.
+- **`silent`** — no immediate reply after it runs. You rarely need to set it: a
+  tool in which no operation can return a response (see below) is silent
+  automatically, and so is any run that reaches `end_call`.
+- **`disable_interruptions`** — the caller cannot barge in while it works.
+- **`operations`** — the tree that runs when it is called.
+
+Prefer one meaningful business capability per tool over many thin ones.
+
+### The operation tree
+
+`operations` is an ordered list. Sending it replaces the tree entirely, so
+include every node you want to keep.
+
+Each node is `{kind, config, on_error?}`, and `kind` decides the rest: an
+operation is a union of eleven shapes, one per kind, each carrying only the
+fields that kind has. `on_error` is `abort` (default) or `continue`.
+
+`silent`, `publish_fields` and `background_execution` exist on `http`, `code` and
+`frontend_rpc` and on nothing else, because those three are the only kinds that
+produce a result — there is nothing for the other eight to hide, to publish out
+of, or to stop waiting for. `then` and `else` belong to an `if` in the same way.
+Sending one of them on a kind that does not have it is rejected, not ignored.
+
+`silent: true` still runs the operation but hides its response from the agent's
+LLM — use it for noisy intermediate steps.
+
+**Silence is derived, not defaulted.** If no operation in the tree can return a
+response, the tool is silent whatever `silent` says — including operations inside
+`if` branches. So a tool that is just `say "Your appointment is confirmed"` says
+that once, rather than saying it and then improvising a second sentence on top.
+If the agent should add a closing line, add a `generate_reply` operation that
+states what to add; do not try to turn the derived silence off.
+
+**Templates.** `{{args.field}}` reads the tool's arguments, `{{tooldata.field}}`
+this tool run's own state, `{{userdata.field}}` the session's state,
+`{{system_vars.field}}` what the platform knows about this session,
+`{{vars.field}}` what the tenant supplied for it, and `{{secrets.NAME}}` a
+workspace secret. A string that is exactly one template token keeps the resolved
+value's type. Every one of these works in a URL, in the query, in the body **and
+in headers**. A token whose root is not one of those six is an error at save,
+not text.
+
+`system_vars` is read-only, and its six keys are the same ones the agent's prompt
+reads: `human_phone_number`, `agent_phone_number`, `direction`, `now`, `date`,
+`time`. So a tool can POST the caller's number to a CRM, stamp a record with
+`{{system_vars.now}}`, or branch an `if` on the direction without the agent
+having to ask. The phone-call keys are empty on web calls, on text conversations
+and in a dashboard test run; the clock keys resolve wherever the agent has a
+`timezone`, and read the time the **tool ran** rather than the time the call
+started.
+
+`vars` is read-only too: whatever the calling agent declares, with whatever the
+request that started the session supplied merged over it — so
+`https://{{vars.api_domain}}/book` is one tool serving every reseller, without a
+copy of it per customer. A tool is workspace-level and does not know which agent
+will call it, so a `{{vars.…}}` it reads is only checked against declarations
+when an agent that attaches it is published.
+
+Do not compare `{{system_vars.time}}` or `{{system_vars.date}}` in an `if`: `gt`
+and `lt` need two numbers, so `"7:26 PM"` against `"09:00"` fails the operation
+rather than quietly taking `else`. Business-hours logic belongs in a `code`
+operation over `new Date(input.system_vars.now)`.
+
+**The two stores.** `tooldata` is created empty every time the tool runs and is
+gone when it returns — only later operations in the same tree can read it.
+`userdata` belongs to the session: other tools, later turns and the agent's
+prompt read it, and it is persisted with the call. Prefer `tooldata` for the
+plumbing between two operations, and `userdata` only for what the conversation
+should still know afterwards.
+
+**Dataflow.** An operation's result is *not* automatically visible to the next
+one. `http`, `code` and `frontend_rpc` may declare `publish_fields`, each
+`{path, key?, store}`: `path` picks a value out of the response, `key` names it
+(the last path segment when omitted), and `store` is `tooldata` or `userdata`.
+`store` is required — it is the difference between a value that dies with the
+tool and one the whole session carries.
+
+`set_variable` writes one templated value directly, with the same required
+`store`.
+
+Reading `{{tooldata.X}}` when nothing earlier in the tool publishes `X` is an
+**error** — tooldata starts empty, so that read can only resolve to nothing.
+Reading `{{userdata.X}}` that the tool does not publish is only a **warning**:
+X has to already be in session userdata, which means something else — the API
+caller, an earlier tool — must put it there first. Say that in the agent's prompt.
+
+**Kinds:**
+
+Each kind's fields, their bounds and their defaults are in the schema; what
+follows is what the schema cannot tell you. Every `timeout` is in **seconds**,
+never milliseconds: the caller is on the line while an operation runs, so a long
+timeout is a hung call rather than a patient one — reach for `long_running_task`
+instead.
+
+- **`http`** — calls a REST API. Expects JSON; a non-2xx status or a non-JSON
+  response fails the operation. Every root templates into headers as well as the
+  URL, query and body — but an `Authorization` built out of `{{args.…}}` is a
+  credential the *model* chose, so put credentials in `{{secrets.…}}`.
+- **`code`** — TypeScript for transformations and shaping. `source_ts` must
+  `export default async function handler(input)`, where `input` is
+  `{args, tooldata, userdata, system_vars, vars, secrets}`, and return an object.
+  The sandbox has `console` and a guarded `fetch` for public http(s) URLs — no
+  Node APIs, no imports.
+
+  That input object is the whole interface: a code operation has **no template
+  syntax**. Write `input.system_vars.now`, never `{{system_vars.now}}` — braces
+  in the TypeScript are neither substituted nor flagged, so a `{{args.id}}`
+  inside a string literal ships to the tenant's API as literal braces. (This is
+  also the only place braces are allowed to survive, so a script that needs to
+  build a mustache template for something downstream can.)
+- **`if`** — compares `left` with `right` and runs its `then` or its `else`.
+  Because an `if` is terminal in its chain, `on_error: "continue"` on one means
+  *neither branch runs and the tree ends there* — a real outcome to reach for,
+  and the only thing `continue` can mean on an operation nothing follows.
+- **`set_variable`** — writes one templated value into `tooldata` or `userdata`.
+- **`say`** — spoken verbatim.
+- **`generate_reply`** — the LLM writes the reply.
+- **`add_message`** — adds a system message without triggering a reply.
+- **`end_call`** — put a `say` immediately before it if there should be a
+  goodbye, and word that goodbye as what actually happens: the call ends here.
+  Never say "let me transfer you", "please hold" or "someone will call you
+  back" before an `end_call` — the caller hears a promise and then silence. The
+  goodbye always finishes playing before the call drops, and the agent never
+  says anything after it, so `wait_for_playback` on that `say` is unnecessary.
+- **`handoff`** — moves the call to another agent. `context` is `transcript`,
+  `summary` or `none` — the same three words as an agent's own
+  `conversation.context`, because it is the same question about the next agent
+  rather than the next call. A named
+  `target_agent_id` must already be published; `agent_name` resolves against the
+  team defined on the call. Handoff moves the call between **agents on this
+  platform**. To reach a *person*, use `transfer`.
+
+  `context: "summary"` **requires** a `summary`, and it is a value rather than a
+  request: this tree runs after the model's tool call, so there is no argument
+  being written at that moment to take one from. Point it at where the text comes
+  from — `{{args.summary}}` (a property on this tool's own `json_schema` that the
+  model filled), `{{tooldata.brief}}` (something an earlier `http` or `code` op
+  published), or fixed prose. There is no second LLM call either way. A `summary`
+  under any other context is an error.
+
+  `recent_turns` works exactly as it does on `handoffs[]`: the tail that
+  crosses verbatim, defaulting to two turns under `summary` and to none under
+  `none`, and rejected under `transcript`.
+
+  Reach for this operation only when the decision is the TREE's — after an
+  `http` lookup, inside an `if`. When the model should decide which desk the
+  caller wants, put the destinations on the agent's own `handoffs` field
+  instead: that is one line per edge rather than a tool with a lifecycle.
+- **`transfer`** — hands the caller to a human being on `destination`, a literal
+  phone number in full international format (`+14155550101`). **Phone calls
+  only** — on a web or text session the operation fails.
+
+  The number is fixed at publish and is never templated or chosen by the model:
+  `{{args.number}}` is not accepted, and neither is a number the caller reads
+  out. If a user asks for either, say so plainly — it is a toll-fraud rule, not
+  an oversight.
+
+  How the caller is reached is the platform's business, not the builder's: we
+  dial the person into the call and step out. Do not offer a choice, and do not
+  mention SIP. One consequence is worth stating if a user asks about it: the
+  person answering sees the workspace's own number, not the caller's, because
+  the leg is dialled from the workspace's trunk.
+
+  `mode` decides what the *caller* experiences, and it is the only choice the
+  builder gets about how a transfer runs:
+
+  - **`cold`** (the default) — the agent finishes its line, then the caller
+    hears hold music for as long as the other phone takes to ring, and a person
+    answers. There is no introduction and no "let me hand you over to Sarah".
+  - **`warm`** — the caller goes on hold with hold music while the agent rings
+    the person on a separate line, tells them who is calling and what they want,
+    answers their questions, and only then puts the two together. The caller
+    hears none of the briefing. It costs a second AI conversation, which is
+    billed to the workspace like any other, and it takes as long as the briefing
+    takes — so it suits escalation to a colleague, not a busy queue.
+
+  Pick `warm` when the person answering needs context to be useful, or when the
+  user says "brief them first" / "don't just dump the caller on them". Pick
+  `cold` for a straight "put me through to sales". If the user has not said,
+  ask — the difference is a minute of hold music, and it is theirs to choose.
+
+  With `warm` the person answering can also **decline**, and then the caller
+  comes back to the agent and the call carries on. The agent is told why in
+  general terms; it never hears or repeats that person's own words.
+
+  `ringing_timeout` bounds the *ringing*, not a warm briefing. `on_failure` is
+  `continue` (the default: the agent is told
+  plainly why and keeps talking to the caller) or `end_call`. What the agent is
+  told is always plain English about the person being called — "the line was
+  busy", "nobody answered", "they aren't able to take the call right now", "the
+  call went through to their voicemail" — never a technical reason.
+
+  Put a `say` immediately **before** it if the caller should hear a line, and
+  don't bother with `wait_for_playback` — the transfer already waits for it to
+  finish. Unlike `end_call`, "let me transfer you" is a promise the platform can
+  keep, so say it here and never before an `end_call`. Word it for the mode:
+  before a `warm` transfer, "let me speak to them first and bring you in" is
+  true; before a `cold` one it is a lie.
+
+  Once the transfer succeeds this call is over as far as the platform is
+  concerned — the agent says nothing more, and the call's duration and recording
+  cover only the part the agent was on. On `warm`, the briefing itself is not
+  recorded either; it is kept on the call's timeline as a `transfer.briefing`
+  event so a workspace can review what was said about a caller.
+
+  **Multiple destinations: one tool per destination, not one tool that
+  branches.** `transfer_to_billing`, `transfer_to_sales`, `transfer_to_support`
+  — each argument-free, each one `say` and one `transfer`. The model then picks
+  a *tool*, which is the thing it chooses most reliably, every destination gets
+  its own name and description, and the tool list reads like the org chart.
+  Nesting five `if`s inside one tool is worse in every one of those respects.
+
+  **The tool's `description` is the escalation policy.** For every other kind a
+  weak description costs a mis-timed API call; here it decides whether a
+  frustrated caller reaches a person. "Transfer to a human" invites the model to
+  escalate at the first sign of difficulty. "Use only after you have tried to
+  answer the question and the caller has asked for a person, or is clearly
+  distressed" is a policy. Ask the user *when* escalation should happen rather
+  than assuming, and write the second kind.
+
+  Tick tool-level `disable_interruptions` on a transfer tool, so the caller
+  cannot talk over "connecting you now" and turn a waited line into an
+  interrupted one. Two shapes it cannot have: the tool may not be
+  `long_running_task`, and it may not be a lifecycle hook — both are refused at
+  publish, because the handover has to happen inside the turn that asked for it.
+- **`frontend_rpc`** — awaits a handler on the connected web client and can
+  publish from its response.
+
+`background_execution: true` on `http`, `code` or `frontend_rpc` fires and
+forgets — no response, so no `publish_fields`.
+
+**`wait_for_playback`** (on `say` and `generate_reply`) holds the
+tree until that line has finished playing. Leave it off — the usual `say` is a
+filler that exists to *cover* the next operation's latency ("let me pull that up
+for you" → `http` → "your balance is …"), and waiting there lengthens every call
+for nothing. Tick it only when the caller must have heard the line before the
+next operation runs: a disclosure before a recording starts, or a promise before
+a side effect they might still retract. Two things to know before relying on it:
+the wait also covers whatever the agent was already saying in the same turn (so
+on a filler it can stall the call for several seconds), and an interrupted line
+counts as finished — it is not proof the caller heard it. Pair it with tool-level
+`disable_interruptions` when that matters.
+
+**The branching rule.** `if`, `handoff`, `end_call` and `transfer` are terminal
+in their chain, and a chain is the top-level list or any `then`/`else` list.
+Nothing may follow them there, and branches do not rejoin. If work must happen after a branch,
+duplicate it into both branches or move the branch later. For an early-exit guard,
+put the rest of the flow inside the guard's `else`. Anything the tool has to do
+before hanging up — logging the outcome, posting a lead — goes **before** the
+`end_call`, not after it: the session is already closing by then.
+
+## Lifecycle hooks
+
+Each hook points at a **published tool id**, or null.
+
+- **`on_enter`** — a session opens. On voice and video it runs alongside the
+  greeting on first entry; on text, when the conversation window opens. Handoffs
+  skip the greeting.
+- **`on_exit`** — the session closes: call end or handoff on voice and video;
+  on text, `end_call`, a closed window, or about a minute idle.
+- **`on_user_turn_completed`** — after every user turn, before the LLM replies.
+  Each spoken turn on voice and video, each inbound message on text. The user's
+  words arrive as `{{args.user_message}}`. On an agent with
+  `vision_input.screenshare` on, the newest frame of the shared screen is already
+  in the context this hook runs against, so anything the tool adds lands after
+  it.
+
+## Agent tasks
+
+An **agent task** is an agent nobody talks to. Same prompt, same model, same
+tools, same MCP servers — minus every conversational organ (speech, greeting,
+turn-taking, handoffs, knowledge bases), plus the one thing a conversation
+cannot have: a **typed structured output**. It takes named inputs, does some
+work, and returns a value. `POST /v1/tasks/{task_id}/runs` runs one and waits.
+
+It is its own noun with its own operations (`list_tasks`, `create_task`,
+`get_task`, `update_task`, `delete_task`, `run_task`, `list_task_runs`) — not a
+fourth agent channel. Use one wherever the work has an input and an answer
+rather than a conversation: research a company from a domain, classify a
+message, draft an opening line, pull a field out of a document.
+
+`config` is:
+
+- **`name`** — unique in the workspace.
+- **`prompt`** — the system prompt, and the whole of the task's behaviour. It
+  reads `{{vars.name}}` for the values the run was given, and
+  `{{system_vars.now}}` / `.date` / `.time` when `timezone` is set. It does
+  **not** read `{{system_vars.human_phone_number}}` / `.agent_phone_number` /
+  `.direction` — there is no call.
+- **`llm`** — one model, with the same `fallback`, `reasoning_effort`,
+  `priority` and `builtin_tools` an agent's LLM has. There is no `stt`, `tts`,
+  `realtime`, `greeting`, `turn_handling`, `avatar`, `handoffs`, `recording`,
+  `analysis`, `kb_ids` or lifecycle hook — a task has nobody to hear, nobody to
+  greet, nothing to hand over and one turn to hook.
+- **`tools`** / **`mcps`** — exactly an agent's, attached by id or defined
+  inline. **A task never pins a tool version**: republishing a tool changes
+  every task that uses it, immediately, with no step in between. That is
+  defensible for a bounded job and would not be for a live call, which is why
+  agents pin and tasks do not.
+- **`vars`** — the task's **inputs**, declared exactly as an agent's variables
+  are: a `name`, a `description`, an optional `default` and `required`. A run
+  supplies values by name; one it omits falls back to the `default`, and a
+  `required` variable with neither is refused *before* anything is compiled, so
+  that failure costs nothing. A value for a name the task does not declare is
+  refused too, rather than silently dropped — which is the one difference from an
+  agent, whose key space is open.
+- **`output`** — a flat list of the fields the model must produce, each with a
+  `name`, a `type` (`string`, `boolean`, `integer` or `number`) and a
+  `description`. At least one, at most 25. No arrays and no nested objects: a
+  task that wants to return five talking points returns one string containing
+  them.
+- **`max_steps`** (default 25, max 50) — how many LLM → tools → LLM **rounds**
+  the run may take. A round, not a tool call: four tools in one reply cost one
+  step. This is the runaway-loop guard.
+- **`timeout_seconds`** (default 120, max 600) — the real time budget.
+
+A name may not appear in both `vars` and `output`: a run's inputs and its output
+are read side by side, so a collision would make one of the two unreachable.
+
+**There is no draft and no publish step.** One config, strict at save: an
+invalid one is refused with a 400 listing every problem and nothing is stored,
+so a task that exists can always run. An edit takes effect on the next run with
+nothing in between — there are no versions, so there is no earlier wording to go
+back to and nothing records which definition produced an earlier run.
+`create_task` and `update_task` also return **`warnings`**: the problems that
+are real but not fatal, such as a prompt reading a variable nothing declares.
+There is no publish screen to show them on, so read them where they are.
+
+### The output tool
+
+The model does not "return" the output. At compile time the task gains one
+generated tool, **`submit_result`**, whose arguments are exactly the `output`
+fields, and one generated paragraph telling it that calling that tool is how the
+run finishes. Both are written for you: never declare a tool named
+`submit_result`, and never write that paragraph into the prompt yourself.
+
+Every output field is **required and nullable** in that tool. The model must say
+something about every field, including "I could not find it" — an optional field
+lets it silently omit the address it failed to find, and "omitted" and "not
+generated yet" then look identical to whoever reads the row. Say so in each
+field's `description`: that description is the only instruction the model gets
+about what belongs there.
+
+### Reading a run
+
+`run_task` **executes for real**: the tools call the tenant's endpoints with
+their secrets, the MCP servers spend their credits, and the model spends their
+tokens. A task that books, charges or sends will do so.
+
+The response is the whole run — `output`, a `trace` of every tool call and
+everything the model wrote (secrets redacted, long fields truncated and marked),
+`steps_used` against `max_steps`, the tokens each model spent and
+`provider_cost`.
+
+**`attempts` is worth reading.** A run that ends without calling `submit_result`
+is re-prompted rather than failed, and **each re-prompt starts the step budget
+over** — so `attempts: 3` means the run hit `max_steps` twice and recovered on
+the third go, having used up to three times the rounds `steps_used` shows.
+`steps_used` is the busiest attempt's count, because that is the number the cap
+governs; `timeout_seconds`, not `max_steps`, is what actually bounds a run.
+
+A failure carries `error.type`, and it is a closed vocabulary that says whose
+problem it is:
+
+- `missing_vars` — a required input had no value and no default. Caught before
+  anything ran, so it cost nothing.
+- `no_output` — the model finished without calling `submit_result`, twice; the
+  framework already re-prompted it once. **Fix the prompt**: say what the task
+  is for and that finishing means calling the tool.
+- `step_limit` — every round of an attempt was used and no result came back.
+  **Fix `max_steps`**, or narrow what the task does. Reported apart from
+  `no_output` precisely so nobody rewrites a prompt that was never the problem.
+- `timeout` — `timeout_seconds` elapsed.
+- `provider_error` — the model or an MCP server failed. Not yours to fix.
+- `configuration` — yours to tell them: a missing BYOK key, a deleted or
+  unpublished tool, an integration whose credential no longer resolves.
+- `platform` — ours.
+
+Task runs are **not** in the Observability charts, which are built on calls and
+conversations. `list_task_runs` is where a task's own history lives.
+
+## Integrations
+
+Integrations are external services, and they come in two shapes.
+
+**MCP integrations** give an agent tools from an external server. Attach them
+in the agent's own config, as `mcps` — the same place as `tools` and
+`kb_ids`, written by `create_agent` or `update_agent`, and frozen at publish
+like the rest of it. So attaching one **takes a publish** before a call sees it.
+`list_integration_mcp_tools` connects to the server and lists everything it
+offers, which also proves the connection works.
+
+Which of those tools an agent may actually call is the integration's
+`allowed_tools`, approved once on the integration and shared by every agent
+attached to it. Null means all of them. Patch the list to narrow it — worth
+doing on a large server, since every approved tool is described to the model on
+every turn, and a voice agent picking from ninety of them is slower and less
+accurate than one picking from six. Unlike the attachment, that approval is
+live: narrowing it reaches every already-published agent on its next turn.
+
+**Channel integrations** (Telegram) deploy an agent to a messaging
+channel through *triggers*, not MCP attachment. A trigger binds an inbound event
+to a published text agent and decides what happens with the reply.
+
+`integration_catalog` is the authoritative list of providers and, in
+`setup_fields`, exactly what each one needs — read it instead of guessing.
+Providers whose `auth_type` is `oauth` must be connected from the dashboard's
+Integrations page; you cannot create them through the API. Manual providers take
+their credentials on create: pass the plaintext token or key and the platform
+stores it as a workspace secret and wires the reference, or pass an existing
+`{{secrets.NAME}}`.
+
+## Phone numbers
+
+A voice or video agent answers the phone once a number is pointed at it. Three
+things have to line up, in order:
+
+1. **A carrier account** — the credential for a phone network.
+   `list_telephony_providers` states exactly which fields each carrier needs;
+   `create_telephony_account` records them, and `provision_telephony_account`
+   builds the SIP trunk. Credentials may be passed as plaintext (stored as a
+   workspace secret) or as an existing `{{secrets.NAME}}`.
+2. **A number on it** — `list_remote_numbers` shows what the account owns at
+   the carrier, and `import_phone_numbers` brings the chosen ones in and
+   provisions them. Numbers are bought at the carrier, never here. Import
+   reports per number: read every `ok` rather than trusting the 200.
+3. **An agent on the number** — `assign_phone_number` puts a **published**
+   voice or video agent on it. Republishing the agent updates live calls
+   automatically; the assignment is not redone.
+
+`readiness` on a number is the honest answer to "does this work": `live`,
+`needs_agent`, `needs_carrier_setup`, `setting_up`, `error` or `disabled`.
+
+Some carrier work happens in the carrier's own console and no API can confirm
+it — that is what an account's `setup_steps` are for. A step marked
+`user_confirmable` is done by the user, who then confirms it with
+`patch_telephony_account`'s `console_setup_confirmed`. Do not claim inbound
+calling works while such a step is outstanding.
+
+## Batch outbound calling
+
+To call a *list* of people rather than one, create a **batch**: an agent, one of
+its outbound-capable numbers, a list of recipients, and a schedule.
+`create_call_batch` is the only way to schedule a call for later — a single
+scheduled call is a one-row batch — and it is the most expensive operation on
+this platform, because one call to it can place thousands of billable dials.
+
+**A batch is policy plus a recipient list.** The policy — schedule, business
+hours, concurrency, agent, retry rule — can be changed at any time with
+`patch_call_batch`, and the next dial picks it up. The recipient list is the
+work: who has been called and how it went, one row each, read back through
+`list_call_batch_recipients`.
+
+**Personalization is `userdata`.** Each recipient carries `to` plus a string map
+that becomes that call's session state, so `{{userdata.first_name}}` in the
+agent's prompt or greeting is that person's name. There are no per-recipient
+overrides of anything else — one batch is one agent, one number, one clock.
+
+**Scheduling.** `timezone` is the batch's clock. `start_at` says when it begins
+(omit it to start immediately) and `calling_window` says which hours and
+weekdays it may dial in, so a list uploaded at 23:00 can start at 11:00
+tomorrow, stop at 18:00 and resume at 10:00 on the next weekday untouched. A
+window may cross midnight; the days then name the evening it starts on.
+`next_dial_at` on the batch says when it will dial next, which is how you tell
+"waiting for Monday" apart from "stuck".
+
+**Say these two things before creating one**, because a user who discovers
+either from an invoice will not forgive us:
+
+- **Answering machines are not detected.** A call that reaches voicemail is
+  answered, billed, and reported as completed.
+- **Every call runs the agent's current published version**, so republishing
+  mid-batch changes every call placed after that moment.
+
+**Steering it.** `pause_call_batch` stops new calls and lets live ones finish;
+`resume_call_batch` carries on. `cancel_call_batch` is final and there is no
+delete — a batch is the record of money spent. `add_call_batch_recipients`
+appends to a running batch and silently skips numbers it already holds, so
+re-uploading an exported list never calls anyone twice.
+
+**Watching it.** `get_call_batch` has live counts and `failure_reason`; a batch
+that stops itself did so after ten consecutive setup failures (an unpublished
+agent, an expired carrier credential, a trunk refusing everything).
+`list_calls` with `batch_id` gives the calls themselves — transcripts,
+recordings and cost.
+
+## Email outbound
+
+To email a *list* rather than one person, create an **email batch**: a CSV, an
+agent task that drafts each row, a connected Resend account, and a mapping that
+says which column carries the address, the subject and the body.
+
+**Four things to say before creating one.** A user who discovers any of them
+afterwards will not forgive us:
+
+- **Resend's terms prohibit unsolicited email, cold outreach, purchased lists
+  and scraped contact data**, and require that every recipient has explicitly
+  opted in. This runs on *their* Resend account under *their* agreement.
+- **Nothing is sent that they have not reviewed and selected.** Creating a batch
+  only drafts.
+- **Every row runs the task as it stands right now.** Editing it while a batch
+  is drafting changes every row generated after that moment, and there is no way
+  to get the old wording back.
+- **Bounces and spam complaints are only visible if they point a Resend webhook
+  at this workspace.** The URL is on the integration's page.
+
+### The column space
+
+A row has **one flat column space, filled from two directions**: the CSV
+supplies some columns, the task's `output` supplies the rest, and a person's
+edits sit on top. `field_map` points `to`, `subject` and `body` at names in that
+merged space, and each may name **either** a CSV header or a field the task
+produces. That is what makes "the CSV already has addresses" and "the CSV has
+phone numbers and the task looks the address up" the same feature.
+
+A row is sendable when all three resolve to a non-empty string and `to` parses
+as an address. Every other field the task produces is kept on the row verbatim
+as context and read by nobody.
+
+Refused at create, all at once: a mapped name that is neither a column nor an
+output field; a mapped output field that is not a `string`; a CSV header that
+collides with an output field name (one of the two would be unreachable); a
+`required` variable the task declares that has no column and no default; a
+`from_email` whose domain is not verified on that Resend account right now.
+
+**A header that exists but is blank on some rows still passes create** and fails
+those rows at draft time with `missing_vars` — one row, not the batch, and with
+no tokens spent. Flag blank cells in a required column before creating.
+
+### Two jobs, and a human between them
+
+**Drafting** starts on `start_at` (or immediately), honours `calling_window` on
+the batch's `timezone`, runs `max_concurrency` rows at a time, and stops when
+the last row lands. Its `status` is about drafting and nothing else —
+`scheduled`, `drafting`, `paused`, `drafted`, `canceled`, `failed`. A `drafted`
+batch means *"the drafts are ready to review"*, never "finished": it says
+nothing about what has been sent.
+
+**Sending** is separate and only ever happens when a person asks.
+`send_email_batch_recipients` takes **at most 50 rows, named one by one**. There
+is no `selection` shorthand on it, no bulk endpoint, and there must not be one:
+a 5 000-row batch cannot leave the building without a hundred deliberate calls,
+each of which should follow reading the fifty drafts it covers. That friction is
+the only structural safeguard this feature has — **do not offer to work around
+it.** `skip`, `restore` and `retry` *do* take `selection: "all_eligible"`,
+because they are reversible and mailing strangers is not.
+
+Each send may override `from_email` / `from_name` / `reply_to` for that call
+alone; the batch's own default is unchanged. The Resend account itself is not
+overridable — a different account is a different batch.
+
+### Fixing rows
+
+`list_email_batch_recipients` returns each row's `columns` (the merged space),
+its three halves separately, and `not_ready_reason` — why it cannot be sent yet,
+null when it can. `patch_email_batch_recipient` edits cells: the edit is stored
+apart from what the model wrote, merged last, and an empty value clears it. That
+is the answer to a row whose task returned `null` for the address — type one in.
+
+`retry_email_batch_recipients` re-drafts rows whose drafting failed, and is the
+one action that revives a batch that already finished drafting.
+
+**One address is mailed at most once per batch**, enforced when the row is
+claimed for sending: the second row settles `skipped` with
+`duplicate_recipient`. There is no cross-batch dedup and no suppression list of
+ours — Resend keeps one and auto-suppresses hard bounces and complaints.
+
+### Watching it
+
+`get_email_batch` carries live counts, `failure_reason`, `next_draft_at` (which
+is how "waiting for Monday" is told apart from "stuck") and the drafting cost so
+far. A batch that stops itself did so after ten consecutive drafting failures,
+or on the first `configuration` failure (a deleted task, a field map an edit
+broke) or the first account-level send failure (a revoked key, an unverified
+domain) — because those will fail identically for every remaining row.
+
+`delivery_status` on a row is Resend's verdict, separate from ours: `sent` is
+what we did, `delivered` / `bounced` / `complained` is what happened next.
+
+## Knowledge bases
+
+A knowledge base gives an agent grounded answers over crawled content. Attach
+ready ones through the agent's `kb_ids`; only `ready` ones can be attached.
+
+Building one runs in three stages and takes minutes, not seconds:
+
+1. `create_kb` with the site URLs starts the crawl. It returns immediately at
+   `discovering` — poll `get_kb` until `status` is `review`.
+2. At `review`, `discovered` holds every URL the crawl found. Choose the ones
+   worth indexing and pass them to `build_kb`. This choice decides the quality
+   of the whole knowledge base: prefer pages that answer real questions over
+   everything the crawl happened to reach.
+3. The KB moves through `transcribing` and `generating` to `ready`. Keep
+   polling `get_kb`; `progress` says what stage it is in and `error` says if it
+   stopped.
+
+Once ready, `get_kb_prompt` is the table of contents exactly as the agent
+receives it — read it to judge what the agent will actually be able to find,
+since a vague entry is one it will never fetch. `list_pages` shows which URLs
+failed to transcribe, `patch_node` corrects an entry by hand, and
+`regenerate_toc` rebuilds the structure without crawling again.
+
+Tell the user a build is running rather than waiting silently through it, and
+never poll a build in a tight loop.
+
+## Secrets, keys and webhooks
+
+**Secrets** are workspace values referenced as `{{secrets.NAME}}` from tool
+operations and integration config. They are write-only: once stored, only the
+runtime resolves them.
+
+**BYOK.** Talqing runs agents on the workspace's own provider API keys and has
+none of its own. `list_provider_keys` says which providers are configured, and
+every key it lists was accepted by that provider when it was saved —
+`set_provider_key` calls the provider first and stores nothing it rejects.
+Prefer models from configured providers; if the user wants one that is not
+there, tell them the key has to be added before the agent can publish.
+
+**Webhooks** are workspace-wide and fire for every agent. `event_types` lists
+what can be subscribed to, and `webhook_deliveries` is where to look when one
+seems silent.
+
+## Running an agent, and reading what happened
+
+Published agents can be run from here, and every run leaves a record.
+
+**Starting something.** `create_outbound_call` dials a real phone number from
+one of the workspace's numbers and puts a published voice agent on the call.
+`create_text_conversation` plus `create_text_message` talks to a published text
+agent — the fastest way to try one. `calls_token` mints the token a *browser*
+needs to join a web call; it starts nothing by itself.
+
+All three take `userdata`, which seeds the session's state and is readable as
+`{{userdata.field}}` from the agent's prompt, greeting and tools. That is how
+you pass in who is being reached and why — one published agent, personalized
+per call. Keys beginning with `_talqing` are reserved.
+
+All three — and `create_call_batch` — also take `vars`, a flat `{name: value}`
+map of strings read as `{{vars.name}}`. It overrides the declared defaults on
+every agent the session runs and is gone when the session ends. Use `userdata`
+for facts about the person and `vars` for configuration of the session; unlike
+`userdata`, `vars` is never written onto the caller's contact record and no tool
+can change it mid-session. An empty string is a deliberate blank, not a request
+for the default. The model can see the values, so credentials stay in workspace
+secrets. On a batch it is one bag for the whole campaign, copied onto every call
+it places — per-person data is what a recipient's `userdata` is for. On a text
+conversation it is fixed for the life of the thread.
+
+**Per-call configuration.** All three — and `create_call_batch` — also take four
+fields that change what runs on that one call:
+
+- `agent_version` — pin a version, or `"draft"` to run the unpublished working
+  copy. That is how you try an edit without publishing over what live callers
+  are hearing.
+- `agent_override` — an `AgentConfig` with only the fields this call changes.
+  Absent keys keep the published value, an explicit `null` clears a field,
+  objects deep-merge and lists replace wholesale. So `{"tts": {"voice":
+  "aditi"}}` changes the voice and leaves the provider and model alone. Note
+  that `agent_override.vars` is a list of *declarations* and replaces them
+  wholesale, while the top-level `vars` above supplies *values*.
+- `agent` — a whole agent definition, run for this call and stored nowhere.
+- `agent_team` — `{"members": [{name, …the same four fields…}]}`, a cast of
+  agents for one call. **`members[0]` answers**, and members reach each other
+  through `handoffs` entries that name them.
+
+`agent_id`/`agent`/`agent_version`/`agent_override` and `agent_team` are
+mutually exclusive: one agent, or a team of them.
+
+**Prefer `agent_id` and `userdata`.** Reach for `agent_override` when one call
+genuinely differs from the published agent, and for `agent` or `agent_team` only
+when the definition is generated per request and would never be reused. An agent
+that exists in the workspace has an editor, a version history, a diff and reuse
+across calls; an inline one has none of those and disappears with the call.
+Composing an inline team by habit ends with a workspace that has no agents in it.
+
+The merged result is validated by the same rules that guard publishing, so a
+bad override is a 400 at create — naming the problem — rather than a call that
+connects and then fails.
+
+`create_text_message` returns as soon as the message is accepted — the agent
+replies asynchronously, so poll `list_conversation_items` (with `order: desc`)
+for the reply. Give it a few seconds, and expect several items when the agent
+calls tools.
+
+It can also carry `images`: up to four `{data_url, filename}` entries beside
+`message`, each a base64 `data:image/...` URL of a JPEG, PNG or WebP under 10 MB.
+The caption and the photo arrive as one turn and one item, so send them together
+rather than as two messages. The agent's model must have `vision` (see *Images*
+above) or the call is refused naming the model.
+
+**Reading it back.** A *conversation* is the thread with a person, on any
+surface; a *call* is one voice or video session. `list_conversations` and
+`list_conversation_items` are the transcript; `list_conversation_sessions` says
+which agent version handled each turn of it. `list_calls` and `get_call` cover
+phone and web calls — `get_call` gives the transcript with every tool call and
+its output, plus usage, cost and a per-stage latency breakdown, which is where
+you find out why an agent did something odd or answered slowly.
+`get_observability` is the workspace view: sessions, spend and latency per day.
+
+What a run costs is the provider spend on the workspace's own keys plus
+Talqing's per-minute platform fee, which `get_catalog` gives per channel. **Text
+agents carry no platform fee at all** — a text conversation costs the workspace
+only what its own LLM key was charged.
+
+When an agent misbehaves, read the actual run before theorizing. The transcript
+and the final `userdata` usually name the cause.
+
+## Rules
+
+- **Never publish an agent unless asked.** Propose it when the draft is ready
+  and wait for the user to say publish, deploy or go live. Publishing a *tool*
+  needs no confirmation — it is a prerequisite for attaching it.
+- **Never reach a real person unless asked for that specific contact.** An
+  outbound call rings someone's phone and costs money; a text message to a
+  connected channel is a message they receive. Both are irreversible. Test
+  against a number or thread the user has named, never one you picked.
+- **Delete only on an explicit request naming the target.** Agents, tools,
+  knowledge bases, carrier accounts, integrations, triggers, secrets, webhooks
+  and tokens are all permanent. Taking a phone number out of service stops real
+  callers from reaching anyone — treat it the same way.
+- **Never echo a secret back.** Personal access tokens, webhook signing secrets
+  and provider keys are shown once; repeating one puts it in the conversation
+  transcript.
+- **Validate before you claim something is ready.** `validate_tool` after tool
+  changes, `validate_agent` after config, hook or handoff changes. Treat errors
+  as work to do and summarize warnings plainly. Validation runs on the server
+  against rules you cannot check by reading a draft, so **never report a
+  validation result you did not get back from the operation**, and never answer
+  a request to validate by reasoning about the config instead of calling it.
+- **Do not invent fields.** Author tools and configs through the exact schemas
+  the operations declare. A field the schema does not have is rejected. An
+  argument whose description ends in `describe_schema('X')` carries a
+  placeholder instead of its shape — fetch it before writing one, never
+  reconstruct it from memory.
+- **Say what the platform does not do.** Decline capabilities that do not exist
+  yet rather than approximating them.
+
+## Writing agent prompts
+
+The agent prompt is the deliverable that decides whether the agent is any good.
+Give it a role, a goal, the rules it must follow, when to use which tool, and
+the language and tone to use.
+
+For voice and video, write for speech, not for a document:
+
+- Natural, brief and warm. Easy to interrupt.
+- Never dump long information — give the next useful chunk and ask whether to go
+  on.
+- No markdown, emoji, raw JSON or list formatting in what the agent says.
+- Text-to-speech mangles abbreviations, symbols and numbers; spell out the forms
+  that matter, or give pronunciation rules.
+- Make tool use explicit: when to call each tool, what to collect first, and
+  what to say while waiting.