文档

抢先体验

进度事件

在模型工作时告诉用户正在发生什么:哪个工具在运行、它如何结束,以及一个真正管用的停止按钮。

带有托管工具的请求可能需要几秒钟。请求运行期间,ModelRiver 会把进度发送到最终响应所到达的同一个 WebSocket 频道,这样你的前端就可以显示“Reading this week's sales…”,而不是一个加载动画。

进度事件带有工具的名称、进度标签以及调用如何结束。它们从不携带结果。它们唯一携带的参数,是等待终端用户审批的调用中开发者选择展示的那些参数。

使用 Client SDK

Client SDK 1.9.0 及更高版本会替你维护这个列表:

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}
位置工具调用当前轮次停止
ModelRiverClientgetState().toolCalls、tool_calls 事件getState().toolRoundcancel()
React useModelRivertoolCallstoolRoundcancel()
Vue useModelRivertoolCalls(ref)toolRound(ref)cancel()
Angular ModelRiverServicetoolCalls$toolRound$cancel()
Svelte createModelRivertoolCalls(store)toolRound(store)cancel()

从 1.10.0 起,pendingApprovals(Angular 中为 pendingApprovals$,ModelRiverClient 上为 getState().pendingApprovals 和 tool_approvals 事件)会列出等待终端用户审批的调用。参见审批。

toolCalls 中的每个条目:

字段说明
id调用的 id。在重试和重连期间保持不变
name工具的名称
label控制台中该工具的 Progress label,或 null
round调用所属的模型轮次,从 1 开始
status先是 running,然后是 ok、error 或 timeout。如果请求在客户端看到调用结束之前就已结束,则为 ended。对会更改内容的工具的调用(1.10.0+)先是 awaiting_approval,然后变为 approved(直到开始运行)、rejected 或 expired,最终也可能是 unknown
duration_ms调用结束后才会设置
user_message你的端点标记为可以安全展示的消息(如果它发送了的话)

调用按开始的顺序列出。同一轮次中的调用可以同时运行,并以任意顺序结束。

更早的 SDK 版本会忽略这些事件,仍然会收到最终响应。

事件

如果你直接使用 Phoenix Channels,这些事件会到达 ai_response:{project_id}:{channel_id}:

tool_round_started

一个模型轮次即将开始。

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

tool_call_started

ModelRiver 正在调用你的某个工具。

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

tool_call_completed

调用已结束,无论结果如何。

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

status 为 ok、error 或 timeout;对于会更改内容的工具,结果未知时为 unknown(它已发送,且绝不会再次发送)。对会更改内容的工具的调用,只要你的端点应答了 2xx,即使其结果无法读取,也为 ok。调用失败不会导致请求失败:模型会被告知,通常仍会作答。

tool_approval_required

对会更改内容的工具的一次调用正在等待终端用户审批。本轮的其他调用结束后,请求会暂停。每个等待中的调用对应一个事件:

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 只包含在 Show to the user 下勾选的参数(没有时为 {})。请以纯文本完整显示提示和值。参见审批。

tool_approval_resolved

调用已被决定,或它的等待时间已用完:

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

decision 为 approved、rejected 或 expired。等待期间被停止的调用为 rejected。本轮所有等待中的调用都决定后,已批准的调用开始运行:每个被发送的调用都会随后收到 tool_call_started 和 tool_call_completed。已批准但没有发送的调用(请求被停止,或已没有剩余时间)不会收到这两个事件。

tool_state

当客户端加入一个已在进行中的请求时(例如页面重新加载之后)发送一次:告知当前的进展。

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}

把它当作其中列出的调用的当前状态,并去掉你仍显示为运行中或等待中、但它没有列出的调用。保留你已经看到完成的调用:每次调用的进度只保留十分钟,因此较早的调用可能不在之后的快照里。客户端 SDK(1.10.0+)会替你这样做。tool_state 会在任何已缓冲的最终响应之前发送,因此界面绝不会从“已完成”退回到“处理中”。如果没有可用的快照,客户端就只会收到此后的事件。

请求等待审批期间,较早轮次的调用是根据请求的日志列出的。它们的 label 和 user_message 均为 null,因此当调用没有 label 时请显示工具的 name。对工作流中不存在的工具的调用会被省略,与实时事件中的做法一致。

请求等待审批期间,tool_state 在整个等待期间都会发送,在任何服务器上、重启之后都可以。等待中的调用带有 status: "awaiting_approval",以及与 tool_approval_required 相同的 prompt、arguments 和 expires_at。已决定的调用为 approved(尚未开始)、rejected 或 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}

如果模型请求的工具在工作流中不存在,则不会产生任何事件,因为它的名称只是模型随意写出的内容。

停止请求

要让用户停止请求,请在频道上推送 cancel(SDK 的 cancel() 就是这么做的):

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

会发生什么:

  • ModelRiver 不再开始新的模型轮次。已在进行中的工具调用会继续执行到结束。
  • 最终的 response 仍会到达,带有 status: "error" 和 error.type: "cancelled"。在它到达之前请保持连接。在等待审批期间被停止的请求只会发送一次该响应:如果 ModelRiver 的某台服务器恰在此时发生故障,它可能不会到达,而请求的日志仍会显示其结束。
  • 已经运行的轮次会被计数。在第一个轮次之前就被停止的请求不计数。
  • 在请求仍在等待开始时发送的停止会被记住,请求一开始就会结束。
  • 在调用等待审批期间发送的停止会立即结束请求。等待中的调用会被拒绝(tool_approval_resolved 为 rejected),并且绝不会运行。

当客户端没有加入任何请求时,cancel() 会解析为 false。

请求如何结束

最终的 response 事件与任何异步请求的相同。成功时,它带有回答和该请求的用量:

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}

当托管工具提前结束请求时,status 为 error,error.type 会说明原因:

error.type发生了什么error.message,为终端用户而写
tool_loop_limit达到轮次或工具调用限制时,模型仍在请求工具"This took too many steps to finish. Try asking a narrower question."
tool_loop_timeout请求用完了它的总时间"This took too long to finish. Please try again."
cancelled用户停止了请求"The request was cancelled."
request_limit_exceeded中途达到了套餐的请求限制或项目的配额"This request could not be completed."
tool_pause_failed无法保存请求以等待审批"This request could not be completed."
tool_unavailable请求等待审批期间,托管工具被关闭,或工作流被删除(或无法加载),或其工具被关闭。没有发送任何已批准的调用"This request could not be completed."
tool_resume_failed等待审批之后,请求无法继续"This request could not be completed."
tool_model_unsupported该请求可以使用的工作流模型都不能调用工具(参见哪些模型可以运行工具)。请求在调用任何模型之前就已结束,不计数。审批后恢复的请求也会以同样方式结束,且不会发送任何已批准的调用"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 可以原样安全展示。error.details 供你的日志使用,但并非总是存在:意外失败的请求只有 type 和 message。

如果某个供应商在后面的轮次中失败,且没有备用模型可以接手,请求会以常规的供应商错误结束。如果中途达到支出上限,下一轮不会开始,请求会以常规的预算错误结束。无论哪种情况,已运行的轮次都会被计数。

下一步

  • Client SDK:连接、重连和读取响应
  • 审批:展示审批并发送决定
  • 测试:在 Timeline 中逐轮查看请求