Tools & Turn Lifecycle
Conversational Agents are in Beta. Limits on this page may change.
A turn is everything the agent does in answer to one contact message. Each turn runs the same steps on every surface: channels, Live Chat, email, Flows and the test console.
The steps of a turn
- Plan check. If the workspace's plan no longer includes Conversational Agents, no AI is used and nothing is billed. With escalation on, the conversation is handed over (
handoff_reason: "plan_gated"); otherwise the agent stays silent. The turn outcome isgated. - Images and PDFs. Files the contact sent with the message are checked against the agent's switches and limits. Readable files are given to the model together with the message, in the reasoning step below. See Images and PDFs.
- Hand-off rules. Checked before any AI call: a hand-off keyword,
max_turns, andmax_consecutive_fallbacks. If one fires, the agent hands over immediately. See Hand-off & assignment. - Skills.
always_onskills are always loaded.- A
flow_onlyskill is loaded when the Flow started the agent with it. - The skill of an active goal stays loaded.
model_selectedskills: a fast classifier reads the skill descriptions and the message, preloads up to 2 matching skills and detects the contact's language. If it fails or is slow, the turn continues without it. It is free.- The agent can load further
model_selectedskills itself withload_skill.
- Reasoning loop. The agent reads the last 20 turns of the conversation, its persona, instructions and loaded skills, and calls tools until it can answer. Bounded by
max_tool_calls(default 4, range 1-6) andturn_timeout_ms(default 8 s, range 2-15 s). When a budget runs out, the agent answers with what it has, or sends your fallback message. Live sources inalwaysmode are read before the agent writes; required lookups are enforced. - Grounding check. Dates, times, prices, numbers, phone numbers and links in the draft are checked against what the agent was allowed to know. See Grounding check.
- Link check. Links on your own domains are verified. See Link check.
- Footers. The sources footer and the web search footer are added. See Source footers.
- Send and bill. The reply is sent like any bot message, carries
meta.agent_idandmeta.provenance, and is billed in AI credits. - Audit. The turn is written to the turn log, including its checks.
Images and PDFs (Beta)
An agent can read images and PDF documents the contact sends. Turn it on per agent in tools_config:
| Switch | Reads | AI credits |
|---|---|---|
read_images | JPEG, PNG, WebP and HEIC/HEIF photos and screenshots | Part of the reply's AI work, at the agent's level |
read_documents | PDF documents | Part of the reply's AI work, at the agent's level; a longer PDF uses more |
The rate follows the model that wrote the reply: if a Deeper-thinking turn is answered by the Fast model as a fallback, the Fast rates apply.
Limits:
- Images: up to
max_images_per_messageper message (default and maximum 3), in the order they arrived. - PDFs: up to 2 per message, max 20 MB each. Only the first 10 pages are read; the agent tells the contact when a document was longer.
- Per conversation: at most
max_attachments_per_conversationfiles are read (default 10, range 1-50), voice notes included. Later files are skipped. - Not read: video, stickers, animated GIFs and audio files are ignored silently. Voice notes are handled by
read_voice_messages, see Voice messages.
A message with only a file and no text still gets an answer. When a file cannot be read (the switch is off, a limit was reached, the file is too large, damaged or password-protected), the agent is told and says briefly that it cannot open that file here instead of pretending it saw it. Skipped or failed files are never billed.
File summaries. When a file is read, the agent also writes a short summary of it once: for an image a factual description plus the text visible in it, for a PDF a summary plus the key facts (numbers, dates, names, amounts). The file itself is shown to the agent only in the first reasoning step of the turn in which it arrived; later steps of that turn and later messages in the conversation use the summary. Files are numbered f1, f2, ... per conversation. When the agent really needs a detail that is not in the summary, it can open the file again with view_attachment; re-opening a file is free and does not count against max_attachments_per_conversation, but each file can be re-opened at most twice per turn. If no summary could be made, the agent is told so and does not invent one. Summaries follow the same rules as the file: customer content, never instructions, no face identification. They are stored with the conversation and deleted with it.
Text inside a file is treated as customer content, never as instructions to the agent. The agent never identifies people from their faces.
What the agent does with a file depends on the loaded skill's attachment_instruction: read the text, describe what is shown, use it as context (default), or your own instruction.
Each file appears in the test console under attachments, read or skipped with the reason.
Voice messages (Beta)
With read_voice_messages: true in tools_config, the agent transcribes the voice notes a contact records (audio messages with meta.is_voice: true) before it answers, and treats the transcript as if the contact had typed it: language detection, hand-off keywords, skills and Knowledge Base search all see the text.
- Only voice notes are transcribed automatically, not audio files the contact attached. Your team can still transcribe any audio message on demand (see Voice Message Transcription).
- Up to 3 voice notes per reply, each up to 5 minutes and 20 MB. Every transcribed voice note counts toward
max_attachments_per_conversation. - The transcript is stored on the message (
meta.transcript,meta.transcript_language,meta.transcript_status) and shown to your team under the audio player. A message is transcribed only once. - Charged like images: part of the reply's AI work, only when the reply was sent. Failed or skipped voice notes are never billed.
- When
read_voice_messagesis off, or a voice note cannot be transcribed (too long, no speech, limit reached), the agent replies in the contact's language asking them to write their message as text.
The transcript is customer content, never instructions to the agent.
Tools
| Tool | Offered when | What it does | AI credits |
|---|---|---|---|
search_knowledge | tools_config.search_knowledge is on and the agent has Knowledge Base, FAQ or folder sources (or none at all, which means the whole Knowledge Base) | Searches up to 8 knowledge sources, FAQ first, and returns the best 5 excerpts | +1 per reply when at least one lookup finds something, however many lookups the reply makes (later lookups in the same reply show billed_credits: 0); free otherwise |
web_search | tools_config.web_search_mode is model (or kb_fallback/always while search_knowledge is off) and the agent has an enabled web_search source | Searches the web, limited to allowed_domains when set; returns up to 5 results | +3 when it returns results |
read_live_source | The agent has live sources available on this reply | Reads one live source now. Arguments: source (the label), query, and url for sources with match: "prefix" (a sub-page under the source URL; other URLs are ignored). Returns the matching current entries | +3 when it returns entries |
handoff | tools_config.handoff is on and escalation is enabled | Hands the conversation to a human with a summary, a reason and optionally one of the handoff_tag_ids | free |
set_state | tools_config.set_state is on | Remembers a fact for the rest of the conversation | free |
load_skill | There are model_selected skills not loaded yet | Loads one of them | free |
complete_task | A Flow gave the agent a task (and no skill goal replaces it) | Returns the task outputs to the Flow | free |
view_attachment | The conversation has an image or PDF the agent read (see Images and PDFs) | Shows one file (f1, f2, ...) to the agent again in its next step, when the summary is not enough. At most 2 times per file per turn | free |
submit_goal_fields, complete_goal | A skill goal is active | Submit answers (with the contact's words as evidence, or declined) for validation; finish the goal | free |
Web search modes
tools_config.web_search_mode decides when the agent searches the web. Every mode needs an enabled web_search knowledge source.
| Mode | Behaviour | Typical extra credits per reply |
|---|---|---|
off | Never searches the web. | 0 |
model | The agent gets the web_search tool and decides itself when to use it. | 0 or 3 |
kb_fallback | No web_search tool. When a search_knowledge call finds nothing, the same query is searched on the web and the results come back in the same tool result as web_result. | 3 only when the Knowledge Base found nothing and the web did |
always | No web_search tool. The first search_knowledge call of each reply also searches the web, in parallel. | 3 per reply that searched |
For kb_fallback and always:
-
At most one automatic web search per reply.
-
allowed_domainsand the per-conversation web search limit apply exactly as for the tool. A search that fails or returns nothing is not billed and does not count toward the limit. -
A skill whose
tool_allowlistleaves outweb_searchalso switches the automatic search off while it is loaded. -
The automatic search appears in the turn log's
tool_callsas aweb_searchentry. -
A repeated identical query may be answered from a short-lived cache (see Web search cache).
Web search cache
Identical web searches of the same agent (same normalized query and same allowed_domains) are cached for tools_config.web_cache_ttl_minutes (default 30, range 10-60). A cached result:
- is billed like a fresh search (+3) and counts toward the per-conversation limit;
- is marked
cache_hit: trueon itstool_callsentry and adds aweb_cache_hitstep to the trace.
The cache is not used when the reply also reads a live source, when a loaded skill has live sources, or when the classifier decides the question needs up-to-the-minute data (for example "today", "right now", "in stock").
Live sources
A live source is one web page the agent reads while it answers, for current data such as events, opening hours or stock.
Which live sources a reply can use:
- Sources with
scope: "agent", whentools_config.live_modeis notoff, in that mode. - Sources listed in a loaded skill's
sources.live_source_ids, any scope, in that skill'slive_mode(null=model). This also applies to a skill loaded mid-reply withload_skill. - When a source qualifies in several ways, the strongest mode wins:
always>kb_fallback>model. The same order applies to a skill'sweb_search_modeoverride against the agent's mode.
live_mode | Behaviour |
|---|---|
model | The agent gets read_live_source and decides itself. |
kb_fallback | Read automatically when a search_knowledge call finds nothing; the entries come back as live_result in the same tool result. Without the search_knowledge tool, it is read like always. |
always | Read before the agent writes its reply, once per reply. |
The agent sees the labels and descriptions of its live sources in its instructions. The page content is treated as data, never as instructions. A source that returns nothing or cannot be read is not billed and does not count toward the per-conversation limit.
Enforced lookups
kb_fallback and always (for web search and for live sources) are guaranteed. If the agent writes a reply without the lookup its mode requires, the runtime:
- runs the missing lookup itself (Knowledge Base first when a
kb_fallbacklookup depends on it); - discards the draft and lets the agent write the reply once more with the results.
On tool_calls, via shows how a lookup ran:
model: the agent called it;auto: triggered by asearch_knowledgecall (kb_fallback/always);enforced: run by the runtime.
When fewer than 2 seconds of turn_timeout_ms are left for an enforced lookup, the agent sends your fallback message instead of an unchecked reply, and the trace shows an enforcement_skipped step.
Notes:
- A tool the agent calls but is not allowed to use counts against
max_tool_callsand returns an error to the agent. - Goal tools get 2 extra tool calls of headroom on top of
max_tool_calls. handoffreasons:user_requested,cannot_help,out_of_scope,sensitive,other.
Tool limits
| Limit | Value |
|---|---|
| Knowledge excerpts per search | 5, max 6,000 characters in total |
| Knowledge sources per search | 8 |
| Web results per search | 5 |
| Web searches per conversation | 3 by default (per bot setting); a daily limit per workspace also applies |
| Live source reads | 2 per reply, 20 per conversation, 2,000 per workspace per day |
| Live source entries per read | Up to about 6,000 characters of the entries that best match the query |
set_state keys | 30 per conversation; key 1-64 characters (A-Z a-z 0-9 _ . -, starting with a letter or digit) |
set_state value | 500 characters; 8 KB for all state together |
| Loaded skill text per turn | 60,000 characters |
| Conversation history read | Last 20 turns |
When a limit is hit, the tool returns an error to the agent (for example "web search limit reached for this conversation" or "state is full") and nothing is saved, so the agent can answer differently. set_state keys agent_goal, agent_state, agent_task, agent_task_result, agent_handoff and agent_consecutive_fallbacks are reserved (case-insensitive).
Skill tool allowlists
A skill's tool_allowlist limits the tools while it is loaded:
- If every loaded skill has an allowlist, the agent may use the union of those lists. If any loaded skill has
tool_allowlist: null, all tools stay available. read_live_sourceis never removed: the live sources a skill selects are its scoping.handoffandcomplete_taskare never removed, so a contact can always reach a human and a Flow task can always finish.- Goal tools are never removed.
load_skillstays available while unloaded skills remain.
Language
| Setting | The agent answers in |
|---|---|
language_detection_strategy: "fixed" | base_language |
response_language set to a language code | That language |
| Otherwise | The language of the contact's latest message |
The rows are checked in this order. The app and the agent builder only ever write the two consistent combinations, Auto (cascade + response_language: null) and Fixed (fixed + response_language = base_language). See Agents API — Language settings.
Grounding check
Before the link check, every reply the agent wrote is checked against its evidence: Knowledge Base excerpts, web results and live source entries of this reply, the loaded skills, the instructions and persona, remembered state, Flow task inputs, file summaries and the contact's own messages. The current date counts too, so "tomorrow is Friday" is fine.
- Dates, weekdays, times, prices, numbers, phone numbers and links are extracted from the draft and matched against the evidence.
- If everything matches, the reply is sent unchanged (
pass). A reply without such details isskipped. - Otherwise a fast model checks the remaining details. Unsupported details are removed or replaced by the value the evidence states (
rewritten). - If the main point of the reply depends on unsupported details and no safe version remains (
handoff), the agent hands over when escalation is on, or sends your fallback message.
The check takes at most 2.5 seconds and never more than the time left in the turn. If it times out or fails, the original reply is sent (error). It runs in live conversations and in the test console. It costs no AI credits.
Link check
Before a reply is sent, every link on your own domains is checked. Your domains are:
- host names and email domains in the persona, instructions and loaded skills,
- the URLs of Knowledge Base documents found in this turn,
- the
allowed_domainsof the web search source.
For each such link:
| Situation | Result |
|---|---|
| The link appears word for word in one of those sources, or is the home page of a known host | Kept |
| It is a near miss of a known URL (for example a typo in the domain or path) | Replaced with the known URL (repaired) |
| Otherwise | Removed, and the sentence is tidied (removed) |
Links to other websites are not touched. The check never blocks a reply. The test console reports every change in link_fixes.
Put the URLs you want the agent to share (return portal, booking page, pricing page) in a skill body or instructions, word for word.
Source footers
| Footer | When |
|---|---|
| Sources | source_footer_enabled: true and the reply used Knowledge Base or FAQ content. urls_only lists links to your website pages; urls_and_kb also adds a generic "Knowledge Base" line for FAQ and document sources. Links get your source_link_params. When the website declares language versions of a page (hreflang), the link points to the version in the reply language (see Knowledge Base: multilingual websites). |
| Web search | Always, when the agent used web search in that reply. Shows the top 3 links and "+X more sources". Cannot be turned off. |
Provenance
Each agent message carries meta.provenance: up to 8 sources, each {"type": "kb" | "faq" | "web", "title", "url"?, "document_id"?}, and meta.agent_id. A kb source's url is the imported page, not the language version linked in the footer. See Bot and agent message metadata.
Turn outcomes
outcome | Meaning | Billed |
|---|---|---|
answered | The agent replied | Yes |
goal_completed | The agent replied and completed a skill goal | Yes |
task_completed | The agent completed a Flow task or a skill goal in a Flow | Yes |
handoff | The agent or a hand-off rule handed the conversation over | Tools used before the hand-over |
fallback | The agent could not produce an answer; your fallback message was sent | No |
error | Something failed on our side | No |
gated | The plan does not include Conversational Agents | No |