文档

抢先体验

审批

取消订单或发送邮件的工具,只有在终端用户同意后才会运行,每次调用都要单独同意。

抢先体验: 托管工具按组织开启。请联系支持为你的组织启用。

每个托管工具都被标记为只读取数据或会更改内容。读取数据的工具在模型请求时立即运行。会更改内容的工具(取消订单、发送邮件、预订时段)只有在终端用户批准这次调用后才会运行。没有跳过询问的设置:每次调用都会询问。

一次调用如何获得批准

  1. 模型请求调用一个会更改内容的工具。ModelRiver 按工具的 schema 检查参数,与任何调用一样。
  2. 本轮的其他调用(读取数据的调用)照常运行。然后请求暂停。
  3. 你的应用通过请求的 WebSocket 频道(如果你配置了 webhook,也会通过 webhook)收到这次调用的审批提示,以及你选择展示的参数。
  4. 终端用户选择批准或拒绝。你的应用把选择发送给你的后端,由后端用你的 API 密钥转发给 ModelRiver。
  5. 当本轮的每次调用都已决定,或等待时间用完时,请求继续。已批准的调用会发送到你的端点,每次调用只发送一次。模型按它请求的顺序拿到本轮的每个结果,然后继续。

被拒绝的调用,或在时限内没有人回应的调用,都不会运行。模型会被告知,然后继续;请求不会因此失败。

浏览器本身永远不能批准任何调用。批准需要你的 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 中:

TSX
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 token
6 const { pendingApprovals } = useModelRiver({ getToken });
7 
8 // Your route; it knows who is signed in, so the browser sends no user id
9 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 必须是你随请求发送的那个:

JAVASCRIPT
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 browser
15 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

Bash
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"}}'
JSON
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何时出现
400end_user_required没有 end_user.id,或它不是文本
400end_user_invalidend_user 不是对象、包含 id 和 claims 以外的字段、id 超过 256 个字符,或 claims 不符合 end_user 规则
404tool_call_not_foundAPI 密钥所属项目中没有这个 id 的、需要审批的调用。其他项目的调用、Playground 的调用、以及不需要审批的调用,都返回同样的结果
409end_user_mismatch这次调用属于另一个 end_user.id
409tool_call_already_decided这次调用已经被做出相反的决定,或请求在等待期间被停止。details.status 是最终生效的决定
410tool_approval_expired等待已结束;这次调用没有运行
429Rate limit exceeded你的 API 速率限制,按项目或按 IP 地址(limit_type)。请在 Retry-After 头给出的时间后重试。这个响应体没有 details,而是带有 retry_after、window 和 limit_type;参见速率限制

这些调用不计为套餐中的请求。

GET /v1/ai/tool-calls/:call_id

供自己展示问题的后端使用。使用同样的 API 密钥,404 规则也相同:

JSON
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,签名方式与其他投递相同:

JSON
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_rejectedThe user declined this action. Do not try it again unless the user asks.
未及时回应tool_approval_expiredThe user did not respond in time, so this action was not taken.
结果未知tool_outcome_unknownThe 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,带 JSONok结果
2xx,带其他任何内容,或结果使请求超出其 256 KB 的结果总量ok操作已执行,但其结果无法读取。调用的日志会保留 tool_result_invalid 或 tool_result_too_large
响应体超过 32 KBunknowntool_outcome_unknown:应答在达到限制处被截断,因此无从得知你的端点做了什么
3xx 或 4xxerror工具拒绝了调用(tool_endpoint_error)。绝不会跟随重定向
5xxunknowntool_outcome_unknown:它可能已经完成了一部分
在超时时间内没有应答,或连接失败unknowntool_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 对象:

JSON
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 不会请求审批:它会真正调用你的端点一次,并且绝不重试。

下一步

  • 端点契约:你的端点收到什么,以及会更改内容的调用如何发送
  • 安全:该信任什么,以及浏览器能看到什么
  • 进度事件:所有事件和状态
  • 测试:在 Playground 中批准和拒绝