Tools
Tools let the assistant call into your application logic during a turn—for example to search data, run a workflow, or fetch the user’s current context—then feed the results back into the model.
At a high level:
- Server tools run on your backend. The assistant calls them through your inference pipeline, and you stream their results back into the conversation.
- Client tools run in the browser or host app. ChatKit surfaces the call as a streamed thread item. The tool’s output becomes input for a new agent run.
Server tools
Server tools are Python functions registered with an agent or inference pipeline. Your inference integration runs the function and returns its result to the model. With the Agents SDK, ChatKit can convert run events into updates for the conversation.
Use server tools to:
- Look up data in your own APIs or databases.
- Kick off long-running jobs while streaming progress updates.
- Update your own domain state (tickets, orders, files, etc.) in response to a turn.
From the model’s perspective, tools are structured, named capabilities it can invoke instead of guessing from free text.
Client tools
Some operations can only run on the client—for example:
- Reading the current selection in a canvas or document.
- Inspecting local application state that never leaves the browser.
- Calling into the host app (for example, a design tool or IDE) via its own APIs.
Client tools let the model request that kind of data mid-turn:
- On the server, you configure the Agents SDK to end the current run at the client tool with
StopAtTools. Turnspan accepts one browser invocation per run and preserves the outputs of server tools executed in the same response. - Your responder streams a
ClientToolCallItemand the server records its pending status. - The client calls
onClientToolwith the tool name and{item_id, input}. The callback echoes that ID in{item_id, output}. - The server claims the exact pending call in the authorized thread, saves the output, and calls
respondwith aClientToolTurn. Useclient_tool_continuation_inputand the call's saved continuation strategy to build the next model request.
A call can complete once. When a customer sends a new message or retries the turn, the store cancels the pending invocation. Any late callback for that invocation is rejected.
Use client tools when the model needs fresh, local context it cannot safely obtain from server-side state alone.