Skip to Content
Baseera Docs

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

KindBehavior
readRuns without asking.
draftAI content a person signs. Waits for approval.
writeChanges 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's messageId, and its id numbers carry on after the last event of the previous stream.
  • It ends like any other: turn.awaiting_tools again if the model calls more tools, otherwise turn.done.
  • If no result arrived within 5 minutes, the turn has already ended. The stream is a single turn.done with finishReason: "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.

CodeStatusWhen
session_not_found404Unknown session, or not this user's or agent's.
turn_not_found404Unknown turn, or one that is not waiting for results.
unknown_call_id409A call id that is not in the turn.
call_already_answered409A call id that already has a result. This includes server calls.
invalid_request400Bad 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:

ToolKindInputResult
ui.focusFieldread{ "field": "taxId" }{ "ok": true }, or an error if the field is not on screen
ui.prefillDraftdraft{ "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.

Next steps

On this page