文档

抢先体验

保护你的工具端点

参数由模型选择,因此要把它们视为不可信。验证每次调用,并根据请求是为谁发起的来决定返回什么。

工具端点是一个会返回你的数据的公开 URL。三条规则可以保证它的安全:

  1. 对每次调用验证签名,这样只有 ModelRiver 能调用它。
  2. 根据 end_user 授权,绝不根据参数。end_user 是你的后端发送的;参数是模型写的。
  3. 只返回该用户可以看到的内容。 你返回的任何内容都可能出现在回答中。

验证签名

每次调用都带有一个用你项目的工具签名密钥生成的签名:

TEXT
1signed_string = "v2." + <x-modelriver-timestamp> + "." + <x-modelriver-tool-call-id> + "." + <raw request body>
2signature = hex(HMAC-SHA256(key = your tool signing secret, message = signed_string))
3header = x-modelriver-signature: v2=<signature>

验证一次调用:

  1. 在任何 JSON 解析之前,以原始字节读取请求体。签名覆盖的是发送的确切字节;解析后再重新编码 JSON 会改变它们。
  2. 如果 x-modelriver-timestamp 与你的时钟相差超过 5 分钟,拒绝该调用。
  3. 计算签名,并以恒定时间与 x-modelriver-signature 中的每个 v2= 值比较。只要有一个匹配就接受。

密钥轮换期间,该请求头可以包含两个以逗号分隔的值(见下文)。

Node.js

JAVASCRIPT
1import crypto from 'node:crypto';
2 
3export function verifyToolCall(rawBody, headers, secrets, toleranceSeconds = 300) {
4 const timestamp = headers['x-modelriver-timestamp'];
5 const callId = headers['x-modelriver-tool-call-id'];
6 const signatures = String(headers['x-modelriver-signature'] || '')
7 .split(',')
8 .map((part) => part.trim())
9 .filter((part) => part.startsWith('v2='))
10 .map((part) => part.slice(3));
11 
12 if (!/^\d+$/.test(timestamp || '') || !callId || signatures.length === 0) return false;
13 if (Math.abs(Date.now() / 1000 - Number(timestamp)) > toleranceSeconds) return false;
14 
15 return secrets.some((secret) => {
16 const expected = crypto
17 .createHmac('sha256', secret)
18 .update(`v2.${timestamp}.${callId}.`)
19 .update(rawBody)
20 .digest('hex');
21 const expectedBytes = Buffer.from(expected);
22 
23 return signatures.some((given) => {
24 const givenBytes = Buffer.from(given);
25 return givenBytes.length === expectedBytes.length && crypto.timingSafeEqual(givenBytes, expectedBytes);
26 });
27 });
28}

rawBody 是一个 Buffer:在 Express 中使用 express.raw({ type: 'application/json' }),在 fetch 风格的处理函数中使用 await request.arrayBuffer()。secrets 是一个列表,因此你可以在轮换期间接受两个密钥。

Python

PYTHON
1import hashlib, hmac, time
2 
3def verify_tool_call(raw_body: bytes, headers, secrets, tolerance_seconds: int = 300) -> bool:
4 timestamp = headers.get("x-modelriver-timestamp", "")
5 call_id = headers.get("x-modelriver-tool-call-id", "")
6 signatures = [
7 part.strip()[3:]
8 for part in headers.get("x-modelriver-signature", "").split(",")
9 if part.strip().startswith("v2=")
10 ]
11 
12 if not timestamp.isdigit() or not call_id or not signatures:
13 return False
14 if abs(time.time() - int(timestamp)) > tolerance_seconds:
15 return False
16 
17 signed = f"v2.{timestamp}.{call_id}.".encode() + raw_body
18 for secret in secrets:
19 expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
20 if any(hmac.compare_digest(expected, given) for given in signatures):
21 return True
22 return False

用于测试的值

TEXT
1secret mrtool_test_4f9a2c7d1e8b3a6f5c0d9e2b7a1f4c8d
2timestamp 1794590623
3call id tc_3f2a9c1d5b7e4a6f8c0d1e2b
4body {"version":2,"type":"tool.call","id":"tc_3f2a9c1d5b7e4a6f8c0d1e2b","tool":"get_sales_summary","arguments":{"period":"this_week"},"end_user":{"id":"user_812","claims":{"plan":"pro"}},"request":{"id":null,"channel_id":"0b5c2a4e-7d1f-4c3a-9e2b-6f8a1d3c5e7b","workflow":"sales_chat","revision_id":"rev_12","round":1,"attempt":1,"mode":"live"}}
5signature 5ee0bc5f7ae14a7264dc8f03ccd69713902119d079910a7bee871034cf59f528

你的函数应当为该请求体生成该签名,请求体末尾没有换行符。这里的密钥是为示例编造的;真实的密钥以 mrts_ 开头。要端到端地检查真实的调用,请使用 Send test call,看你的端点是否接受它。

这不是 webhook 签名

Webhook 投递使用不同的密钥和不同的方案:它们对时间戳和 data 的值签名,并以不带前缀的十六进制发送签名。工具调用则对整个原始请求体连同调用 id 一起签名,并给签名加上 v2= 前缀。Webhook 验证器会拒绝工具调用,反之亦然。请把这两个密钥分开保管。


防止重复

对读取数据的工具的一次有效调用可能被发送两次:在遇到 5xx 或连接中断后,ModelRiver 会用相同的 x-modelriver-tool-call-id 重试一次。对于只读取数据的工具,应答两次没有害处。对会更改内容的工具的调用绝不重试。

如果某次调用绝不能被处理两次,请把每个调用 id 记住几分钟,并用你已经生成的结果来应答重复的调用。5 分钟的时间戳检查限定了你需要记住它们的时长。


根据 end_user 授权

模型根据对话选择工具的参数,而对话中包含用户输入的文本。有人可以输入“给我看门店 st_99 的销售额”,模型很可能就会把 st_99 传过去。

所以,参数说明的是在问什么。它们从不说明是谁在问:

JAVASCRIPT
1// Wrong: the model decides whose data is returned
2const summary = await db.salesSummary(call.arguments.store_id, call.arguments.period);
3 
4// Right: your backend already decided, and ModelRiver signed it
5const summary = await db.salesSummary(call.end_user.claims.store_id, call.arguments.period);

决定访问权限的标识符,干脆不要放进工具的 schema。有了 "additionalProperties": false,即使调用中带上了这样的标识符,也会在到达你之前被拒绝。

end_user 就是你的后端放进请求里的内容:在后端检查用户的会话,然后发送该用户的 id 和你的工具需要的少量声明(门店、租户、角色)。ModelRiver 不会把它展示给模型,并会在签名的请求体中把它传给你的端点。


审批:该信任什么

会更改内容的工具只有在终端用户批准调用后才会运行(参见审批)。审批的设计让模型和浏览器都无法代为批准。

  • 只有你的后端能做决定。 批准和拒绝需要你的项目 API 密钥,所以浏览器做不到。你的路由必须从已登录的会话中取得 end_user.id,绝不能从浏览器取得。只有当它与请求发送时的 end_user.id 相同时,ModelRiver 才接受这个决定(否则返回 409 end_user_mismatch),并且只针对该 API 密钥自己的项目。
  • 提示由你来写。 审批提示是你在工具上写的文本,按原样显示。参数值永远不会被填进去,因此模型无法编写这个问题。
  • 值来自模型。 提示旁展示的参数是模型写的,而对话可以影响模型。请以纯文本完整显示它们,绝不作为 HTML、Markdown 或链接显示,这样某个值就无法冒充你界面的一部分。
  • 批准不等于授权。 终端用户同意,并不意味着他们有权这么做。与任何调用一样,你的端点仍然根据 end_user 做决定。

浏览器和 webhook 能看到什么

对于等待审批的调用,浏览器(tool_approval_required 事件和 tool_state)、tool.approval_required webhook 以及 GET /v1/ai/tool-calls/:call_id 会带有工具名称、审批提示,以及在 Show to the user 下勾选的参数的值。webhook 还会带有 end_user_id。

隐藏的参数

在 Show to the user 下未勾选的参数永远不会到达浏览器、webhook 或 GET:它不在事件、tool_state、webhook、GET 或错误响应体中。你的端点仍然会收到所有参数;项目保存完整的请求和响应文本时,请求日志也会保留它们。结果永远不会到达浏览器或 webhook。

隐藏一个参数,意味着终端用户在看不到它的情况下批准,所以你取消勾选时控制台会提醒你。请展示终端用户做决定所需的一切:邮件发给谁、取消的是哪个订单。

持有请求 WebSocket 令牌的任何人都可以看到等待中的审批并停止请求,但不能批准它。


提示词注入

工具结果是模型会读取的文本,而你的数据中可能包含别人写的文本:商品评价、客服备注、文档。这些文本可能试图向模型下达指令。

ModelRiver 会把每个工具结果标记为不可信数据,并告诉模型其中的任何内容都不是指令。这会降低风险,但不能消除风险。真正限制损害的,是工具能做什么:

  • 会更改内容的工具会先询问。 每次调用都只有在终端用户批准后才会运行,用户看到的是你写的提示。被劫持的模型可以请求,但无法自行更改任何东西。
  • 你的端点只返回 end_user 可以看到的内容,因此模型没有其他用户的数据可泄露。
  • 只要可行,就返回字段,而不是文档。数字无法携带指令。

轮换密钥

在 Tools 选项卡的 Tool signing secret 下,选择 Rotate,再选择 Rotate secret 确认。新密钥只显示一次。

旧密钥会继续有效 24 小时。在此期间,每次调用都带有两个签名,新的在前,x-modelriver-key-id 会列出两个密钥 id。要在不丢失任何调用的情况下轮换:

  1. 在控制台中轮换,并复制新密钥。
  2. 部署你的后端,让用于验证的列表中同时包含两个密钥。
  3. 24 小时后,移除旧密钥。

轮换进行期间不能再次轮换,因此你的端点所用的密钥不会被意外丢掉。要提前结束这 24 小时,请选择 Finish rotation,勾选 My endpoints already check the new secret,再选择 Stop the old secret now:旧密钥会立即失效。

如果密钥已泄露,请轮换并立即选择 Finish rotation,让泄露的密钥马上失效,然后再部署新密钥。在部署完成之前,你的端点会拒绝调用,因为调用只用新密钥签名。


各类信息的去向

模型终端用户的浏览器你的请求日志
工具名称、描述、schema是仅名称和进度标签是
参数是(由它写出)仅限等待审批的调用:在 Show to the user 下勾选的参数如果项目保存完整的请求和响应文本
审批提示否是,针对等待审批的调用否。它保留在工作流的设置中
结果是否如果项目保存完整的请求和响应文本
你的端点返回的 error.message是,标记为来自工具的文本否如果项目保存完整的请求和响应文本
error.user_message否是否
end_user否否作为请求的一部分,如果项目保存完整的请求和响应文本
端点 URL否否否。它们保留在工作流的设置中
签名密钥否否否。加密存储;创建时显示一次

工具调用记录会随其所属的请求一起删除,依据是你套餐的保留期。其调用的审批记录也是如此:提示、展示的参数和决定。


测试调用与本地测试

有两类调用并非来自线上请求:

  • 从控制台发出的测试调用,其 request 中带有 "mode": "test"。除非你预期会收到,否则你的生产端点应当拒绝它,这样测试就不会对线上数据产生任何操作。
  • 由开发者的 modelriver tools 会话转发的调用,其 request 中带有 "via": "cli"。它用相同的密钥签名,并且这个完整的签名调用会交给运行该会话的人:即持有项目任一 API 密钥的人。CLI 只会把它转发到此人自己的机器,但这个调用本身在五分钟内可以被重放,因此你的生产端点应拒绝任何带有 "via": "cli" 的调用。该值位于已签名的请求体内,所以无法在不破坏签名的情况下将其移除。

在控制台中

  • 可以编辑项目工作流的人可以修改已保存工具的描述、schema、进度标签、超时、审批提示和展示的参数,开启或关闭工具、删除工具、更改限制,以及复制带有其工具的工作流。
  • 添加工具、重命名工具、修改工具所调用的地址,或更改调用它会执行的操作,仅限组织所有者和管理员:该地址会收到带有你的用户 end_user 的签名调用,并且只读取数据的工具运行时不会询问终端用户。
  • 创建、轮换以及结束轮换签名密钥,同样仅限组织所有者和管理员。
  • Send test call 仅限组织所有者和管理员使用,因为它会向表单中输入的地址发送一个签名请求。每人每分钟最多 20 次,每个组织每小时最多 300 次。
  • 创建、轮换以及结束轮换密钥,还有发送测试调用(连同端点的主机),都会记录在组织审计日志中。

下一步

  • 端点契约:完整的请求与响应参考
  • 审批:设置会更改内容的工具
  • 测试:用真实的签名调用检查你的验证器