带有托管工具的请求可能需要几秒钟。请求运行期间,ModelRiver 会把进度发送到最终响应所到达的同一个 WebSocket 频道,这样你的前端就可以显示“Reading this week's sales…”,而不是一个加载动画。
进度事件带有工具的名称、进度标签以及调用如何结束。它们从不携带结果。它们唯一携带的参数,是等待终端用户审批的调用中开发者选择展示的那些参数。
使用 Client SDK
Client SDK 1.9.0 及更高版本会替你维护这个列表:
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}| 位置 | 工具调用 | 当前轮次 | 停止 |
|---|---|---|---|
ModelRiverClient | getState().toolCalls、tool_calls 事件 | getState().toolRound | cancel() |
React useModelRiver | toolCalls | toolRound | cancel() |
Vue useModelRiver | toolCalls(ref) | toolRound(ref) | cancel() |
Angular ModelRiverService | toolCalls$ | toolRound$ | cancel() |
Svelte createModelRiver | toolCalls(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
一个模型轮次即将开始。
1{ "round": 1, "max_rounds": 5 }tool_call_started
ModelRiver 正在调用你的某个工具。
1{ "id": "tc_3f2a9c1d5b7e4a6f8c0d1e2b", "name": "get_sales_summary", "label": "Reading this week's sales…", "round": 1 }tool_call_completed
调用已结束,无论结果如何。
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
对会更改内容的工具的一次调用正在等待终端用户审批。本轮的其他调用结束后,请求会暂停。每个等待中的调用对应一个事件:
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
调用已被决定,或它的等待时间已用完:
1{ "id": "tc_3f2a9c1d5b7e4a6f8c0d1e2b", "name": "cancel_order", "round": 1, "decision": "approved" }decision 为 approved、rejected 或 expired。等待期间被停止的调用为 rejected。本轮所有等待中的调用都决定后,已批准的调用开始运行:每个被发送的调用都会随后收到 tool_call_started 和 tool_call_completed。已批准但没有发送的调用(请求被停止,或已没有剩余时间)不会收到这两个事件。
tool_state
当客户端加入一个已在进行中的请求时(例如页面重新加载之后)发送一次:告知当前的进展。
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:
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() 就是这么做的):
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 事件与任何异步请求的相同。成功时,它带有回答和该请求的用量:
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." |
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 中逐轮查看请求