Tools & Turn Lifecycle

Beta

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

1. 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 is gated.
2. Images. If image understanding is turned on for the agent's bot record, images the contact sent are read first (+2 AI credits).
3. Hand-off rules. Checked before any AI call: a hand-off keyword, max_turns, and max_consecutive_fallbacks. If one fires, the agent hands over immediately. See Hand-off & assignment.
4. Skills.
   • always_on skills are always loaded.
   • A flow_only skill is loaded when the Flow started the agent with it.
   • The skill of an active goal stays loaded.
   • model_selected skills: 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_selected skills itself with load_skill.
5. 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) and turn_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.
6. Link check. Links on your own domains are verified. See Link check.
7. Footers. The sources footer and the web search footer are added. See Source footers.
8. Send and bill. The reply is sent like any bot message, carries meta.agent_id and meta.provenance, and is billed in AI credits.
9. Audit. The turn is written to the turn log.

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 when it finds something, free otherwise
web_search	tools_config.web_search is on 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
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
submit_goal_fields, complete_goal	A skill goal is active	Submit answers for validation; finish the goal	free

Notes:

• A tool the agent calls but is not allowed to use counts against max_tool_calls and returns an error to the agent.
• Goal tools get 2 extra tool calls of headroom on top of max_tool_calls.
• handoff reasons: 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
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.
• handoff and complete_task are never removed, so a contact can always reach a human and a Flow task can always finish.
• Goal tools are never removed.
• load_skill stays 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.

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_domains of 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.

tip

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.
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. 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