Tools
How the assistant calls your APIs, what the built-in tools do, and the guard rails around every call.
A tool is something the model may call during a turn. Kletso has two kinds.
HTTP tools (yours)
Defined in the dashboard under Tools. Each has:
- a name and description the model sees (write the description as an instruction: “Call it immediately for any product request; pass the user’s words as query”),
- a parameters JSON schema for the arguments,
- a method and a URL template with
{{ input.<arg> }}placeholders, optional header templates and a body template, - auth: none, bearer token, API-key header or basic, with the credential referenced from project secrets by name,
- act as user: forward the signed-in user’s identity so your API applies its own permissions,
- require confirmation: pause and ask the user before calling.
The runtime validates arguments against the schema, renders the templates, applies the SSRF guard (http or https only, no credentials in the URL, no private, loopback, link-local or metadata hosts, redirects are not followed), calls your endpoint with a timeout of up to 15 seconds and up to 3 retries on network errors or 5xx, caps the response at 1 MB, and returns the JSON (or an error) to the model, truncated to 12,000 characters of context. Each call is logged as tool.started and tool.completed or tool.failed with latency, so you can see it in the conversation inspector and the Events tail.
Test a tool from the dashboard with sample arguments before you give it to an agent.
Built-in tools (Kletso’s)
| Tool | Effect |
|---|---|
render_ui | Renders a kletso.ui/v1 surface in the chat. Validated against the agent’s component allowlist. |
notify_app | Sends an app.notify notification to the user: banner, toast, alert, system or silent, optionally opening the chat or carrying an action. |
app_command | Asks the app to run a registered local action (navigate, open checkout). Requires allowServerCommands in the SDK config. |
handoff | Marks the conversation as handoff, emits handoff.started and stops the assistant from answering. Only available when the agent’s handoff destination is not “Never”. |
What the model cannot do
- Call a tool that is not attached to the published agent version.
- Reach hosts the SSRF guard blocks, follow a redirect, or exceed the per-call timeout.
- Skip a confirmation.
- Render a component type outside the allowlist.
- Continue past
maxToolRoundsin one turn.
Design notes
- Return small, structured JSON from tools. The model reads it verbatim; large payloads cost tokens and get truncated.
- Prefer one tool per intent over one generic tool with a mode argument. Models pick tools by description.
- Put the user’s identity on the server side of your API, not in prompt text. With act as user the runtime signs the request so your API can trust it.