抢先体验: 托管工具按组织开启。请联系支持为你的组织启用。
每个托管工具都被标记为只读取数据或会更改内容。读取数据的工具在模型请求时立即运行。会更改内容的工具(取消订单、发送邮件、预订时段)只有在终端用户批准这次调用后才会运行。没有跳过询问的设置:每次调用都会询问。
一次调用如何获得批准
- 模型请求调用一个会更改内容的工具。ModelRiver 按工具的 schema 检查参数,与任何调用一样。
- 本轮的其他调用(读取数据的调用)照常运行。然后请求暂停。
- 你的应用通过请求的 WebSocket 频道(如果你配置了 webhook,也会通过 webhook)收到这次调用的审批提示,以及你选择展示的参数。
- 终端用户选择批准或拒绝。你的应用把选择发送给你的后端,由后端用你的 API 密钥转发给 ModelRiver。
- 当本轮的每次调用都已决定,或等待时间用完时,请求继续。已批准的调用会发送到你的端点,每次调用只发送一次。模型按它请求的顺序拿到本轮的每个结果,然后继续。
被拒绝的调用,或在时限内没有人回应的调用,都不会运行。模型会被告知,然后继续;请求不会因此失败。
浏览器本身永远不能批准任何调用。批准需要你的 API 密钥和终端用户的 id,所以它要经过你的后端,而你的后端本来就知道谁已登录。
设置会更改内容的工具
在工作流的 Tools 选项卡中打开工具,在 What does calling it do? 下选择 Changes something。Approval 下会多出两个字段:
| 字段 | 说明 |
|---|---|
| Approval prompt | 终端用户看到的问题,按原样显示:Cancel this order? This can't be undone. 最多 300 个字符。开启该工具时必填。它是纯文本:没有占位符,参数值永远不会被填进去 |
| Show to the user | 工具的参数,每个一个复选框。勾选的参数会显示在提示旁边。默认全部勾选;你取消勾选任何一个时,控制台都会提醒你,因为用户会在看不到该值的情况下批准。最多 16 个 |
只能展示顶层参数。模型没有发送的参数会被省略,而不是显示为空。
在 Limits per request 中选择 Edit。Approval wait (minutes) 设置一次调用等待回应的时长:默认 10 分钟,范围 1 到 60。工作流中有会更改内容的工具时才会显示。等待时间不计入请求的 Total time。
工具行会显示 Changes data · Asks first。
通过 API 设置时,对应每个工具上的 approval_prompt 和 approval_fields,以及工作流上的 tool_approval_timeout_ms(60000 到 3600000)。保存时没有 approval_fields 的工具会展示它所有的顶层参数(参数多于 16 个时,按名称排序取前 16 个);只有显式的 [] 才表示一个都不展示。
在你的应用中展示审批
Client SDK 1.10.0 及以上版本会把等待回应的调用保存在 pendingApprovals 中:
1import { Fragment } from 'react';2import { useModelRiver } from '@modelriver/client/react';3 4function Approvals() {5 // getToken lets the client rejoin after a reload: a wait can outlast the 5-minute resume token6 const { pendingApprovals } = useModelRiver({ getToken });7 8 // Your route; it knows who is signed in, so the browser sends no user id9 const decide = (id: string, decision: 'approve' | 'reject') =>10 fetch(`/api/tool-calls/${encodeURIComponent(id)}/${decision}`, { method: 'POST' });11 12 return pendingApprovals.map((approval) => (13 <div key={approval.id}>14 {/* Plain text: React escapes it. Never render these as HTML, Markdown or links. */}15 <p>{approval.prompt}</p>16 <dl>17 {Object.entries(approval.arguments).map(([name, value]) => (18 <Fragment key={name}>19 <dt>{name}</dt>20 {/* Show the whole value: a cut-off value can hide what is being approved */}21 <dd style={{ whiteSpace: 'pre-wrap', overflowWrap: 'anywhere' }}>22 {typeof value === 'string' ? value : JSON.stringify(value)}23 </dd>24 </Fragment>25 ))}26 </dl>27 <button onClick={() => decide(approval.id, 'approve')}>Approve</button>28 <button onClick={() => decide(approval.id, 'reject')}>Decline</button>29 </div>30 ));31}pendingApprovals 的每一项:
| 字段 | 说明 |
|---|---|
id | 调用的 id(tc_…)。把它发送给你的后端 |
name | 工具的名称 |
label | 工具的进度标签,或 null |
round | 这次调用所属的模型轮次 |
prompt | 工具的审批提示 |
arguments | 只包含在 Show to the user 下勾选的参数,按名称列出 |
expires_at | 等待结束的时间(ISO 8601) |
arguments 中的值是模型写的。请以纯文本完整显示提示和每个值,自动换行,绝不截断;不是文本的值以 JSON 显示。
同样的列表在 Vue composable 和 Svelte store 中是 pendingApprovals,在 Angular service 中是 pendingApprovals$,在 ModelRiverClient 上是 getState().pendingApprovals 加上 tool_approvals 事件。调用被决定或过期后,它会离开列表。重连时列表会保留,客户端重新加入时会根据 tool_state 重建,所以重新加载页面后问题会再次出现。
原始 WebSocket 事件是 tool_approval_required 和 tool_approval_resolved;参见进度事件。
从你的后端发送决定
你的路由先确认谁已登录,再调用 ModelRiver。end_user.id 必须是你随请求发送的那个:
1// Express. requireSignedIn is your own session check.2app.post('/api/tool-calls/:id/:decision', requireSignedIn, async (req, res) => {3 const { id, decision } = req.params;4 if (decision !== 'approve' && decision !== 'reject') return res.sendStatus(404);5 6 const response = await fetch(7 `https://api.modelriver.com/v1/ai/tool-calls/${encodeURIComponent(id)}/${decision}`,8 {9 method: 'POST',10 headers: {11 Authorization: `Bearer ${process.env.MODELRIVER_API_KEY}`,12 'Content-Type': 'application/json',13 },14 // From your session, never from the browser15 body: JSON.stringify({ end_user: { id: req.user.id } }),16 }17 );18 res.status(response.status).type(response.headers.get('content-type') ?? 'text/plain').send(await response.text());19});POST /v1/ai/tool-calls/:call_id/approve 和 /reject
curl -X POST https://api.modelriver.com/v1/ai/tool-calls/tc_3f2a9c1d5b7e4a6f8c0d1e2b/approve \ -H "Authorization: Bearer $MODELRIVER_API_KEY" \ -H "Content-Type: application/json" \ -d '{"end_user": {"id": "user_812"}}'1{2 "id": "tc_3f2a9c1d5b7e4a6f8c0d1e2b",3 "status": "approved",4 "decided_at": "2026-11-14T10:12:31Z",5 "channel_id": "0b5c2a4e-7d1f-4c3a-9e2b-6f8a1d3c5e7b"6}再次发送相同的决定会返回相同的 200,所以双击或重试都无害。错误使用原生错误格式:
| 状态 | error | 何时出现 |
|---|---|---|
| 400 | end_user_required | 没有 end_user.id,或它不是文本 |
| 400 | end_user_invalid | end_user 不是对象、包含 id 和 claims 以外的字段、id 超过 256 个字符,或 claims 不符合 end_user 规则 |
| 404 | tool_call_not_found | API 密钥所属项目中没有这个 id 的、需要审批的调用。其他项目的调用、Playground 的调用、以及不需要审批的调用,都返回同样的结果 |
| 409 | end_user_mismatch | 这次调用属于另一个 end_user.id |
| 409 | tool_call_already_decided | 这次调用已经被做出相反的决定,或请求在等待期间被停止。details.status 是最终生效的决定 |
| 410 | tool_approval_expired | 等待已结束;这次调用没有运行 |
| 429 | Rate limit exceeded | 你的 API 速率限制,按项目或按 IP 地址(limit_type)。请在 Retry-After 头给出的时间后重试。这个响应体没有 details,而是带有 retry_after、window 和 limit_type;参见速率限制 |
这些调用不计为套餐中的请求。
GET /v1/ai/tool-calls/:call_id
供自己展示问题的后端使用。使用同样的 API 密钥,404 规则也相同:
1{2 "id": "tc_3f2a9c1d5b7e4a6f8c0d1e2b",3 "status": "pending",4 "tool": "cancel_order",5 "prompt": "Cancel this order? This can't be undone.",6 "arguments": { "order_id": "1041" },7 "expires_at": "2026-11-14T10:20:00Z",8 "decided_at": null,9 "channel_id": "0b5c2a4e-7d1f-4c3a-9e2b-6f8a1d3c5e7b"10}status 是 pending、approved、rejected 或 expired。arguments 只包含在 Show to the user 下勾选的参数。
不使用 Client SDK:webhook 和 GET
较早的 SDK 版本会忽略审批事件,所以请求看起来只是花的时间更长。它们保存请求的时间也只有 5 分钟(使用 getToken 时为 60 分钟),因此在更长的等待期间重新加载页面就无法重新加入。要在这些版本中询问用户,或者通过其他渠道(如邮件或聊天)询问,请从你的后端使用 webhook 或上面的 GET,或者升级 SDK。
项目中每个已启用的 webhook 都会为每个等待中的调用收到 tool.approval_required,签名方式与其他投递相同:
1{2 "channel_id": "0b5c2a4e-7d1f-4c3a-9e2b-6f8a1d3c5e7b",3 "timestamp": 1794590623,4 "data": {5 "type": "tool.approval_required",6 "channel_id": "0b5c2a4e-7d1f-4c3a-9e2b-6f8a1d3c5e7b",7 "call_id": "tc_3f2a9c1d5b7e4a6f8c0d1e2b",8 "workflow": "support_desk",9 "tool": "cancel_order",10 "prompt": "Cancel this order? This can't be undone.",11 "arguments": { "order_id": "1041" },12 "end_user_id": "user_812",13 "expires_at": "2026-11-14T10:20:00Z"14 }15}- 通过
data.type把它和响应区分开。它没有callback_url:调用通过上面的端点决定,绝不通过回调。 - 同一次投递可能到达不止一次。用
data.call_id忽略重复。 - 它只包含提示和展示的参数,绝不包含其他参数或密钥。
- Playground 运行不会发送 webhook。
与任何 webhook 一样,请验证签名。
模型会被告知什么
模型读到的是 ModelRiver 自己的固定文本,用来代替结果:
| 结果 | error.code | 模型读到的内容 |
|---|---|---|
| 被拒绝 | tool_call_rejected | The user declined this action. Do not try it again unless the user asks. |
| 未及时回应 | tool_approval_expired | The user did not respond in time, so this action was not taken. |
| 结果未知 | tool_outcome_unknown | The tool may or may not have finished. Do not say it succeeded; ask the user to check. |
| 已执行,但结果无法读取 | 无:这不是错误 | The action was carried out, but its result could not be read. Do not run it again, and do not say it failed. |
已批准的调用如何运行
已批准的调用最多发送一次。会更改内容的调用永远不会重试,一旦调用可能已经到达你的端点,就绝不会再次发送。
| 你的端点 | 调用的状态 | 模型会被告知 |
|---|---|---|
2xx,带 JSON | ok | 结果 |
2xx,带其他任何内容,或结果使请求超出其 256 KB 的结果总量 | ok | 操作已执行,但其结果无法读取。调用的日志会保留 tool_result_invalid 或 tool_result_too_large |
| 响应体超过 32 KB | unknown | tool_outcome_unknown:应答在达到限制处被截断,因此无从得知你的端点做了什么 |
3xx 或 4xx | error | 工具拒绝了调用(tool_endpoint_error)。绝不会跟随重定向 |
5xx | unknown | tool_outcome_unknown:它可能已经完成了一部分 |
| 在超时时间内没有应答,或连接失败 | unknown | tool_outcome_unknown |
从未发送的调用是 error,尝试次数为 0,绝不会是 unknown。在日志中,它的 approval.status 仍为 approved。它的代码说明原因:
tool_timeout:调用被决定时请求已没有剩余时间。模型不会读到它:请求以tool_loop_timeout结束。cancelled:请求先被停止。tool_resume_failed:等待结束后请求无法继续,并以tool_resume_failed结束。tool_unavailable,在发送任何内容之前:等待期间托管工具被关闭,或工作流被删除,或其工具被关闭。请求以tool_unavailable结束(见下文)。当工作流的模型都已不能调用工具时,该调用也会标记为这个错误码,请求则以tool_model_unsupported结束。tool_unavailable,在发起调用时:项目没有签名密钥,或端点地址被拦截。模型会被告知,请求继续。
只有最后一种情况会发送 tool_call_started 和 tool_call_completed(status: "error");其他情况两个事件都不会收到。即便如此,仍请让你的端点可以安全地重复执行,并用调用的 id(x-modelriver-tool-call-id)识别已经处理过的调用。参见端点契约。
在你的应用中,unknown 的意思是:告诉用户这件事可能发生了也可能没有,请他们在重试前先确认。
等待、停止与限制
- 等待。 每次调用会等到它的
expires_at。届时仍未决定的调用会过期,请求继续。等待的时间不计入请求的总时间;计时从停下的地方继续。 - 重新加入。 在整个等待期间请求都可以访问:可以再次加入频道,
POST /v1/ai/reconnect会给出新的令牌,在任何服务器上、重启之后都可以。 - 停止。 调用等待期间的停止(SDK 的
cancel())会立即结束请求,error.type: "cancelled"。等待中的调用会被拒绝,之后也绝不会运行。如果停止发生在每次调用都已决定之后,处理方式与运行中的请求相同:尚未发送的已批准调用不会发送,已发送的会让它完成。 - 同时等待的请求。 一个项目最多可以有 50 个请求在等待审批。达到 50 个时,发往含有会更改内容的工具的工作流的新请求会被
429 tool_approvals_limited拒绝,并带有Retry-After: 30。等待中的请求不计入项目正在运行的托管工具请求数。 - 工具调用限制。 会更改内容的调用在模型请求它时就计入工作流的工具调用限制,无论终端用户如何决定,因此不断请求的模型会被拦下。
- 配置。 请求会使用它开始时的同一个已发布修订版本(或 Playground 草稿)继续,即使你在它等待期间发布了新版本。
等待中的请求无法继续时
最终的 response 带有 status: "error",以下每种情况的 error.message 都是 "This request could not be completed.":
error.type | 发生了什么 |
|---|---|
tool_pause_failed | 无法保存请求以等待审批 |
tool_unavailable | 等待期间托管工具被关闭,或工作流被删除(或无法加载),或其工具被关闭。没有发送任何已批准的调用 |
tool_resume_failed | 等待结束后请求无法继续 |
tool_model_unsupported | 工作流的模型都已不能调用工具(参见哪些模型可以运行工具)。没有发送任何已批准的调用,也没有调用任何模型 |
如果在请求等待期间达到了套餐的请求限制或项目的配额,请求会像运行中的请求一样以 request_limit_exceeded 结束,并且不会发送任何已批准的调用。
在等待期间结束的请求(被停止,或以上述某个错误结束)只会发送一次最终的 response。如果 ModelRiver 的某台服务器恰在此时发生故障,这个响应可能不会到达;请求的日志仍会显示它是如何结束的。因此,在最后一个 expires_at 之后,不要让你的应用无限期地等待。
计数方式
- 与往常一样,每个模型轮次计为套餐中的一次请求。暂停的那一轮在暂停时就计数,所以一个先等待、然后过期的请求只为它已运行的轮次付费,不会更多。
meta.tool_loop.tool_calls和用量 API 的tool_calls统计发送到你端点的调用。被拒绝和已过期的调用不计数。- 批准、拒绝和
GET都不算请求。
在请求日志中
请求等待期间,暂停的那一轮会单独显示在 Request Logs 中,每个等待中的调用都标注 Waiting for approval, until 及其过期时间。请求结束后,它会像往常一样移到请求自己的日志下面。
Timeline 会显示每次调用的决定及时间:Approved by the end user、Declined by the end user、No answer in time, so it was not run、Not run: the request was stopped,或 Playground 中的决定。在日志详情 API 中,每次调用都有一个 approval 对象:
1"approval": {2 "status": "approved",3 "decided_at": "2026-11-14T10:12:31Z",4 "expires_at": "2026-11-14T10:20:00Z",5 "decided_by": "end_user"6}status 是 pending、approved、rejected 或 expired;decided_by 是 end_user、playground、cancel 或 null。不需要审批的调用为 "approval": null。调用本身的 status 也可能是 awaiting_approval、approved、rejected、expired 或 unknown。
在 Playground 中
在 Playground 中,对会更改内容的工具的调用同样会等待。提示和展示的参数会出现在运行结果下方,带有 Approve 和 Decline 按钮;已批准的调用会得到模拟结果;如果这次运行把工具调用发送到你的 CLI,则会被发送到你的本地端点一次。参见测试。
审批功能推出前保存的工作流
- 会更改内容的工具只有在有审批提示后才能开启,每次保存和发布都会检查。没有提示的工具绝不会提供给模型。
- 导入一个工作流时,如果其中已开启的、会更改内容的工具没有提示,该工具会以关闭状态导入,导入响应会在
warnings中列出它,代码为write_tool_switched_off。把旧修订版本恢复为草稿时也是如此。请先添加提示,再开启该工具。 - Send test call 不会请求审批:它会真正调用你的端点一次,并且绝不重试。