Using Tools
How tools work in the Companion API and how to attach them to a session
Tools let your agent do things beyond conversation — trigger workflows, look up data, generate content, or interact with external systems during a session.
Execution flows
Every tool runs in one of two execution flows. The flow determines where the tool call is delivered when the agent invokes it. You choose the flow when you create the tool, and you can mix both types in the same session.
Implicit
The tool call is delivered to the connected client. For WebRTC sessions, this means the Web SDK running in the user's browser; for WebSocket sessions, your WebSocket client. Your client receives the tool call, executes the logic, and returns the result.
Explicit
The tool call is forwarded to a URL you specify when creating the tool — either an HTTP endpoint or a WebSocket endpoint on your server. Use this when the tool needs to reach your backend systems — for example, querying a database, calling an internal API, or triggering an action in a third-party system.
The execution flow is set per tool. You can mix implicit and explicit tools in the same session.
Attaching tools to a session
Tools are attached when you create a connection via POST /public/connections or POST /public/ws-connections. Pass an array of tool IDs in the functions field of the request body:
{
"companionId": "companion_abc",
"providerConfig": { ... },
"functions": ["fn_abc123", "fn_def456"]
}You can attach as many tools as you need to a single session.
Responding to tool calls
When an implicit tool is invoked during a session, the Companion API sends an event to your connected client with the tool call details. Your client handles the logic and sends the result back. This works over both WebRTC (via the Web SDK) and WebSocket connections.
Receiving a tool call
When the agent invokes an implicit tool, the server delivers a function_implicitly_called event to your client:
{
"type": "function_implicitly_called",
"data": {
"item_id": "item_001",
"call_id": "call_abc123",
"name": "get_order_status",
"arguments": {
"order_id": "ORD-7890"
}
}
}| Field | Description |
|---|---|
item_id | The ID of the conversation item that triggered the tool call |
call_id | A unique identifier for this specific tool call — use this when sending the response |
name | The name of the tool being invoked |
arguments | The parameters the agent populated for the tool call |
Sending the tool output
Once you've processed the tool call, send the result back with a send_function_output event:
{
"type": "send_function_output",
"data": {
"call_id": "call_abc123",
"output": {
"status": "shipped",
"tracking_number": "1Z999AA10123456784"
},
"delay": false
}
}| Field | Description |
|---|---|
call_id | The call_id from the function_implicitly_called event |
output | The result of the tool call — this is passed back to the agent |
delay | When true, the response is held until the agent finishes speaking before being processed |
Timeout
Tool calls have a default timeout of 10 seconds. If no response is received within that window, the Companion API sends "Failed to fetch information" to the model as the tool result and delivers a function_call_timeout event to your client.