Documentation

Early access

Progress events

Tell the user what is happening while the model works: which tool is running, how it ended, and a Stop button that works.

A request with hosted tools can take several seconds. While it runs, ModelRiver sends progress to the same WebSocket channel the final response arrives on, so your frontend can show "Reading this week's sales…" instead of a spinner.

Progress events carry a tool's name, its progress label and how the call ended. They never carry results. The only arguments they carry are, for a call waiting for the end user's approval, the ones the developer chose to show.

With the Client SDK

Client SDK 1.9.0 and later keep the list for you:

TSX
1import { useModelRiver } from '@modelriver/client/react';
2 
3function Assistant() {
4 const { toolCalls, toolRound, response, error, hasPendingRequest, cancel } = useModelRiver();
5 
6 return (
7 <div>
8 {toolCalls.map((call) => (
9 <p key={call.id} className={call.status}>
10 {call.label ?? call.name}
11 {call.status === 'error' && call.user_message ? `: ${call.user_message}` : null}
12 </p>
13 ))}
14 
15 {hasPendingRequest && <button onClick={() => cancel()}>Stop</button>}
16 {response?.status === 'success' && <pre>{JSON.stringify(response.data, null, 2)}</pre>}
17 {error && <p className="error">{error}</p>}
18 </div>
19 );
20}
WhereTool callsCurrent roundStop
ModelRiverClientgetState().toolCalls, the tool_calls eventgetState().toolRoundcancel()
React useModelRivertoolCallstoolRoundcancel()
Vue useModelRivertoolCalls (ref)toolRound (ref)cancel()
Angular ModelRiverServicetoolCalls$toolRound$cancel()
Svelte createModelRivertoolCalls (store)toolRound (store)cancel()

From 1.10.0, pendingApprovals (pendingApprovals$ in Angular, getState().pendingApprovals and the tool_approvals event on ModelRiverClient) lists the calls waiting for the end user's approval. See Approvals.

Each entry of toolCalls:

FieldDescription
idThe call's id. Stable across retries and reconnects
nameThe tool's name
labelThe tool's Progress label from the console, or null
roundThe model round the call belongs to, starting at 1
statusrunning, then ok, error or timeout. ended when the request finished before the client saw the call finish. A call to a tool that changes something (1.10.0+) starts as awaiting_approval, then becomes approved (until it starts), rejected or expired, and can end as unknown
duration_msSet once the call has finished
user_messageA message your endpoint marked as safe to show, if it sent one

Calls are listed in the order they started. Calls of one round can run at the same time and finish in any order.

Earlier SDK versions ignore these events and still receive the final response.

The events

If you use Phoenix Channels directly, these arrive on ai_response:{project_id}:{channel_id}:

tool_round_started

A model round is starting.

JSON
1{ "round": 1, "max_rounds": 5 }

tool_call_started

ModelRiver is calling one of your tools.

JSON
1{ "id": "tc_3f2a9c1d5b7e4a6f8c0d1e2b", "name": "get_sales_summary", "label": "Reading this week's sales…", "round": 1 }

tool_call_completed

The call finished, whatever the outcome.

JSON
1{ "id": "tc_3f2a9c1d5b7e4a6f8c0d1e2b", "name": "get_sales_summary", "round": 1, "status": "ok", "duration_ms": 182, "user_message": null }

status is ok, error or timeout, or unknown for a call to a tool that changes something whose outcome is not known (it was sent, and is never sent again). A call to a tool that changes something that your endpoint answered with 2xx is ok even when its result could not be read. A call that failed does not fail the request: the model is told, and usually still answers.

tool_approval_required

A call to a tool that changes something waits for the end user's approval. The request pauses once the round's other calls have finished. One event per waiting call:

JSON
1{
2 "id": "tc_3f2a9c1d5b7e4a6f8c0d1e2b",
3 "name": "cancel_order",
4 "label": "Cancelling the order…",
5 "round": 1,
6 "prompt": "Cancel this order? This can't be undone.",
7 "arguments": { "order_id": "1041" },
8 "expires_at": "2026-11-14T10:20:00Z"
9}

arguments holds only the arguments ticked under Show to the user ({} when none). Show the prompt and the values as plain text, in full. See Approvals.

tool_approval_resolved

The call was decided, or its wait ran out:

JSON
1{ "id": "tc_3f2a9c1d5b7e4a6f8c0d1e2b", "name": "cancel_order", "round": 1, "decision": "approved" }

decision is approved, rejected or expired. A call stopped while it waited is rejected. Once every waiting call of the round is decided, approved calls run: tool_call_started and tool_call_completed follow for each one that is sent. A call that is approved but not sent (the request was stopped, or no time was left) gets neither event.

tool_state

Sent once when a client joins a request that is already under way, for example after a page reload: where things stand.

JSON
1{
2 "round": 2,
3 "max_rounds": 5,
4 "calls": [
5 { "id": "tc_3f2a…", "name": "get_sales_summary", "label": "Reading this week's sales…", "round": 1, "status": "ok", "duration_ms": 182, "user_message": null },
6 { "id": "tc_9c1d…", "name": "get_top_products", "label": null, "round": 2, "status": "running" }
7 ]
8}

Take it as where the calls it lists stand now, and drop any call you still show as running or waiting that it doesn't list. Keep calls you already saw finish: each call's progress is kept for ten minutes, so an earlier one can be missing from a later snapshot. The Client SDK (1.10.0+) does this for you. tool_state is sent before any buffered final response, so the screen never goes from "done" back to "working". If no snapshot is available, the client simply gets the events from then on.

While a request waits for approval, calls from earlier rounds are listed from the request's log. Those have label: null and user_message: null, so show the tool's name when a call has no label. A call to a tool the workflow doesn't have is left out, as it is from the live events.

While a request waits for approval, tool_state is sent for the whole wait, from any server and after a restart. A waiting call has status: "awaiting_approval" and also prompt, arguments and expires_at, as in tool_approval_required. A decided call has approved (not started yet), rejected or expired:

JSON
1{
2 "round": 1,
3 "max_rounds": 5,
4 "calls": [
5 { "id": "tc_3f2a…", "name": "get_order", "label": null, "round": 1, "status": "ok", "duration_ms": 140, "user_message": null },
6 { "id": "tc_9c1d…", "name": "cancel_order", "label": "Cancelling the order…", "round": 1, "status": "awaiting_approval", "prompt": "Cancel this order? This can't be undone.", "arguments": { "order_id": "1041" }, "expires_at": "2026-11-14T10:20:00Z" }
7 ]
8}

A model's request for a tool the workflow doesn't have produces no events, because its name is whatever the model wrote.

Stopping a request

To let the user stop a request, push cancel on the channel (the SDK's cancel() does this):

JAVASCRIPT
1const stopped = await client.cancel(); // true when ModelRiver took the request to stop

What happens:

  • ModelRiver starts no further model round. A tool call already under way is left to finish.
  • The final response still arrives, with status: "error" and error.type: "cancelled". Keep the connection open until it does. A request stopped while it waited for approval sends that response once: if a ModelRiver server fails at that moment it may not arrive, and the request's log still shows the end.
  • Rounds that already ran are counted. A request stopped before its first round counts nothing.
  • A stop sent while the request is still waiting to start is remembered, and the request ends as soon as it starts.
  • A stop sent while calls wait for approval ends the request straight away. The waiting calls are declined (tool_approval_resolved with rejected) and never run.

cancel() resolves false when the client isn't joined to a request.

How a request ends

The final response event is the same as for any async request. On success it carries the answer and what the request used:

JSON
1{
2 "status": "success",
3 "data": { "...": "the model's answer, as for any request to this workflow" },
4 "meta": { "workflow": "sales_chat", "duration_ms": 2140, "tool_loop": { "rounds": 2, "tool_calls": 2 } }
5}

When hosted tools end a request early, status is error and error.type says why:

error.typeWhat happenederror.message, written for the end user
tool_loop_limitThe model was still asking for tools at the round or tool-call limit"This took too many steps to finish. Try asking a narrower question."
tool_loop_timeoutThe request ran out of its total time"This took too long to finish. Please try again."
cancelledThe user stopped it"The request was cancelled."
request_limit_exceededYour plan's request limit or the project's quota was reached part-way"This request could not be completed."
tool_pause_failedThe request couldn't be saved to wait for approval"This request could not be completed."
tool_unavailableHosted tools were turned off, or the workflow was deleted (or couldn't be loaded) or its tools switched off, while the request waited for approval. Nothing approved was sent"This request could not be completed."
tool_resume_failedThe request could not carry on after waiting for approval"This request could not be completed."
tool_model_unsupportedNone of the workflow's models that the request may use can call tools (see Which models can run tools). It ended before any model was called and counts nothing. A request resuming after approval ends the same way, and nothing approved is sent"This request could not be completed."
JSON
1{
2 "status": "error",
3 "message": "This took too many steps to finish. Try asking a narrower question.",
4 "error": {
5 "type": "tool_loop_limit",
6 "message": "This took too many steps to finish. Try asking a narrower question.",
7 "details": "The request reached its round limit before the model answered."
8 },
9 "meta": { "status": "error", "tool_loop": { "rounds": 5, "tool_calls": 9 } }
10}

error.message is safe to show as it is. error.details is for your logs, and isn't always there: a request that failed unexpectedly has only type and message.

If a provider fails in a later round and no backup model can take over, the request ends with the usual provider error. If a spending limit is reached part-way, the next round is not started and the request ends with the usual budget error. In every case, the rounds that ran are counted.

Next steps

  • Client SDK: connect, reconnect and read the response
  • Approvals: show the approval and send the decision
  • Testing: watch a request round by round in the Timeline