Build your agent

Tools & rich messages

Tools are server-side functions the agent can invoke during a conversation. When a visitor sends a message, the LLM decides whether a tool is needed, the platform executes it, and the result is either fed back to the LLM or rendered as a structured block in the widget.

Overview

Every tool has a name, a JSON-schema description of its arguments, a required capability, and a server-side handler. The registry exposes the tool definitions to the LLM; the runtime is responsible for sandboxing, timeouts, and turning tool output into either text the model can read or rich blocks the widget can render.

Access control

Whether a tool is visible to the model depends on three factors:

The agent's vertical capabilities (from the site-type preset).
The tool's required capability.
The admin-configured allowlist via vertical_overrides.enabled_tools.

Available tools

Tool	Required capability	Auto-enabled on	Function
`escalate_to_human`	`ticket_escalation`	All verticals	Surfaces an escalation button for human handoff.
`lookup_order`	`order_status`	`ecommerce`	Retrieves WooCommerce order status, items, and tracking (5s timeout).
`open_ticket`	`ticketing`	`help_center`	Creates a durable support ticket with subject, body, and priority.
`send_kb_article`	`kb_article_card`	`help_center`	Displays a Knowledge Base article card with title and excerpt.

Hot-path resolution

For every visitor message the runtime walks this loop:

Build the tool array from the registry, filtered by capability + allowlist.
Call the LLM with tools enabled (non-streaming for this hop).
If the model returned tool calls: emit SSE events, execute each handler, append results to the conversation, and loop.
Stop when the model returns plain content or the 3-hop limit is reached.
Stream the final answer to the widget — TTFT is preserved relative to non-tool turns.

Any block payloads the tools produced (for example escalation_button or kb_article_card) are emitted as block SSE events alongside the text stream.

Provider support

OpenAI models have native tool calling. OpenRouter and Cloudflare Workers AI support tool calling on the models that advertise it; for models that don't, the runtime degrades gracefully — the tools simply aren't offered to that turn.

Performance

Tool calls add roughly 200–500 ms of latency per hop before streaming begins. The no-tool case is unchanged. Well-written tool descriptions (clear, narrowly scoped, with examples) minimize unnecessary invocations and keep TTFT low.

Adding a new tool

Authoring a new tool requires four things:

A class implementing the Tool contract — name, schema, capability, execute().
Registration in the tool registry.
A widget renderer if the tool returns rich blocks.
Tests covering both the happy path and the timeout / error branches.

Note. The live widget currently whitelists ticket_escalation blocks for rendering. Other block types are emitted on the wire and visible in the Playground, but only render in production once their renderer is on the allowlist.