Tools and approvals
How tool calls pause a turn, how the user approves them, and how you post results back.
Tools live in your app. The runtime never stores or runs them. It streams the model's tool calls to your client, waits for results, and carries on.
How a tool call flows
You send tool specs
Every turn request carries the full tools list. The runtime keeps no state between requests.
The model calls a tool
The stream emits tool.call with the validated input, then turn.awaiting_tools with the call ids and an expiresAt.
Your client decides
read tools run straight away. draft and write tools wait for the user to approve. Approval happens in your client, not on the server.
You post results
One request answers every pending call. The response is a stream that continues the same turn.
Approvals
| Kind | Behavior |
|---|---|
read | Runs without asking. |
draft | AI content a person signs. Waits for approval. |
write | Changes your data. Waits for approval. |
The runtime does not collect approvals. Your client shows an approval card, and your result tells the runtime what happened. A rejection is posted as a result, and the model sees The user declined: {reason}.
Post tool results
POST /v0/sessions/{sessionId}/tool-results returns 200 OK with text/event-stream that continues the same turn.
Browser request. See Authentication.
Prop
Type
Each result has a callId and exactly one outcome:
Prop
Type
curl -N -X POST "$BASEERA_URL/v0/sessions/ses_01JC9X4M2K8Q/tool-results" \
-H "Origin: https://app.example.com" \
-H "x-baseera-key: $BASEERA_PUBLISHABLE_KEY" \
-H "x-baseera-user-token: $USER_TOKEN" \
-H "content-type: application/json" \
-d '{
"turnId": "trn_7",
"results": [
{ "callId": "call_1", "approved": true, "output": { "ok": true, "status": "paid" } },
{ "callId": "call_2", "rejected": true, "reason": "Wrong invoice" },
{ "callId": "call_3", "error": "Network request failed" }
],
"tools": [],
"context": { "page": "invoices" }
}'The continuing stream
- It has no
turn.started. It reuses the turn'smessageId, and itsidnumbers carry on after the last event of the previous stream. - It ends like any other:
turn.awaiting_toolsagain if the model calls more tools, otherwiseturn.done. - If no result arrived within 5 minutes, the turn has already ended. The stream is a single
turn.donewithfinishReason: "tool_timeout", and the session stays usable. - A turn stops after 8 model steps. Tool calls requested on the 8th step are dropped and the turn ends with
finishReason: "max_steps_reached".
Errors
Returned as JSON before the stream starts.
| Code | Status | When |
|---|---|---|
session_not_found | 404 | Unknown session, or not this user's or agent's. |
turn_not_found | 404 | Unknown turn, or one that is not waiting for results. |
unknown_call_id | 409 | A call id that is not in the turn. |
call_already_answered | 409 | A call id that already has a result. This includes server calls. |
invalid_request | 400 | Bad shape or limits, a duplicate call id, or not every pending call answered. |
Undo
Undo is a feature of the SDK, not an endpoint. There is no undo request in the wire protocol.
When a tool you define has an undo function, @baseera/core marks a finished draft or write call as undoable and calls your undo(input, output) when the user asks. The data it needs stays in memory in the page, never in stored state, and is gone when the page closes. The model is not told about an undo.
If you build your own client, implement undo yourself: keep the call's input and output, run your reversal, and do not post anything to the runtime.
Immersive tools
While a record is in immersive mode and at least one field is on the screen, the SDK adds two tools to tools like any other:
| Tool | Kind | Input | Result |
|---|---|---|---|
ui.focusField | read | { "field": "taxId" } | { "ok": true }, or an error if the field is not on screen |
ui.prefillDraft | draft | { "field": "taxId", "value": "...", "reason": "..." } | approved: true with output, or rejected: true with a reason |
ui.prefillDraft is approved in the field itself, so its call stays pending until the user decides. The runtime treats both as ordinary tools.