How Chao Uses Tools
Chao can use authorized Chainabit and connector capabilities while answering a message. Clients integrate with the observable contract: progress arrives through the session SSE stream, writes follow the session's approval mode, and every action remains scoped to the authenticated account and workspace.
Observable lifecycle
A tool-assisted turn may emit these public events:
| Event | Meaning |
|---|---|
tool.started | A tool call began. |
tool.progress | Optional progress suitable for a transient status message. |
tool.approval_required | The run is waiting for a user decision. |
tool.approval_response | The approval decision was recorded. |
tool.completed | The tool call finished successfully. |
tool.failed | The tool call failed. The payload contains a public error, not an internal exception. |
tool.degraded | The capability completed with a documented limitation. |
message.delta | Incremental assistant text. |
message.completed | The assistant message is complete. |
run.settlement.completed | The run's usage settlement is complete. |
Treat events as an open set. Ignore unknown event types, deduplicate by event ID, and reconnect with Last-Event-ID. See SSE Streaming for the full transport contract.
tool.started
tool.completed
message.delta
message.completed
run.settlement.completedSession modes and writes
The session mode controls how proposed writes are handled:
| Mode | Write behavior |
|---|---|
auto | Permitted writes may execute without an approval pause. Policy can still require approval or block a tool. |
approval | Approval-gated writes pause and emit tool.approval_required. |
plan | Proposed writes are collected as plan steps instead of being executed. |
Update the mode through PATCH /ai/sessions/:sessionId. A mode never grants a capability: authentication, entitlement, workspace membership, and tool policy are still enforced.
Connector recovery
A connector call can pause with a structured requirement:
| Requirement | Client action |
|---|---|
needs_connection | Ask the user to connect the requested service. |
needs_reconnect | Ask the user to repair the selected connection. |
needs_connector_selection | Ask the user to choose an authorized connection. |
needs_agent_attachment | Ask an authorized user to attach the connection to the agent. |
Use the identifiers and actions returned by the API. Do not construct internal tool names, choose a different connection silently, or infer that a write succeeded. After the requirement is resolved, use the continuation contract returned with the run; repeated continuation requests are idempotent.
Approval decisions
Approve or reject a pending tool call with the run and tool-call identifiers from the event stream:
POST /api/v1/ai/runs/{runId}/tools/{toolCallId}/approve
POST /api/v1/ai/runs/{runId}/tools/{toolCallId}/reject
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/jsonApproval applies only to that pending call. A successful approval response means the decision was recorded; continue reading the stream for the execution result.
Failure handling
- A blocked tool is a policy outcome, not a signal to bypass the policy with another endpoint.
- A failed tool does not necessarily fail the whole assistant run. Wait for the terminal run or message event.
- A disconnected SSE client does not cancel the server-side run. Reconnect to observe it, or call the explicit cancel endpoint.
- Do not display raw tool input or output unless the event contract marks it as public display data.