文档

抢先体验

端点契约

你的工具端点究竟会收到什么、可以返回什么,以及当它变慢、宕机或拒绝时会发生什么。

托管工具就是你的一个 HTTPS 端点。每次工具调用,ModelRiver 都会向它发送一个 POST,并读取 JSON 回复。本页是这两个方向的参考。

请求

HTTP
1POST /tools/sales-summary HTTP/1.1
2Host: api.yourapp.com
3Content-Type: application/json
4Accept: application/json
5x-modelriver-timestamp: 1794590623
6x-modelriver-tool-call-id: tc_3f2a9c1d5b7e4a6f8c0d1e2b
7x-modelriver-key-id: tk_9f2c41ab77d0
8x-modelriver-signature: v2=5ee0bc5f7ae14a7264dc8f03ccd69713902119d079910a7bee871034cf59f528
JSON
1{
2 "version": 2,
3 "type": "tool.call",
4 "id": "tc_3f2a9c1d5b7e4a6f8c0d1e2b",
5 "tool": "get_sales_summary",
6 "arguments": { "period": "this_week" },
7 "end_user": { "id": "user_812", "claims": { "store_id": "st_44" } },
8 "request": {
9 "id": "0b5c2a4e-7d1f-4c3a-9e2b-6f8a1d3c5e7b",
10 "channel_id": "0b5c2a4e-7d1f-4c3a-9e2b-6f8a1d3c5e7b",
11 "workflow": "sales_chat",
12 "revision_id": "8d0f6c1e-2a4b-4f7d-9c3e-5b1a7e2d4f60",
13 "round": 1,
14 "attempt": 1,
15 "mode": "live"
16 }
17}

请求头

请求头值
x-modelriver-timestamp调用签名时的 Unix 时间(秒)
x-modelriver-tool-call-id调用的 id,与请求体中的 id 相同。对读取数据的工具的调用重试时保持不变
x-modelriver-key-id使用了哪个签名密钥(tk_…)。密钥轮换期间为两个 id,以逗号分隔
x-modelriver-signaturev2= 后接签名。密钥轮换期间为两个值,以逗号分隔

如何检查签名,参见安全。

请求体

字段说明
version2。契约版本
type"tool.call"
id调用的 id。用它识别你已处理过的调用的重试
tool工具的名称,与注册时一致
arguments模型选择的内容,已按工具的 schema 检查过。是一个对象
end_user{id, claims},与你的后端随请求发送的完全一致
request.id、request.channel_id异步请求的 channel id
request.workflow工作流的名称
request.revision_id正在运行的已发布修订版本,或 null
request.round哪个模型轮次请求了这次调用,从 1 开始
request.attempt1,重试时为 2。会更改内容的工具始终为 1
request.mode"live",Playground 运行为 "playground",从控制台发出的测试调用则为 "test"
request.via仅在由开发者的 modelriver tools 会话转发到其机器的调用中出现,值为 "cli"。生产端点应拒绝它

请求体中可能会新增字段。请忽略你不认识的字段。


响应

请在工具的超时时间内以 JSON 作答。

你返回结果
2xx,带 JSON 对象或数组这就是结果。模型会读取它
4xx你拒绝了这次调用。不会重试。模型会被告知工具失败
5xx,或连接失败读取数据的工具:如果超时时间还剩至少一秒,重试一次,之后模型会被告知工具失败。会更改内容的工具:绝不重试,模型会被告知结果未知(见下文)
重定向(3xx)错误。绝不会跟随重定向
2xx,带其他任何内容(文本、数字、空响应体)错误:tool_result_invalid。会更改内容的工具:这次调用算作已完成(见下文)
响应体超过 32 KB错误:tool_result_too_large。会更改内容的工具:结果未知(见下文)

工具调用失败不会导致请求失败。模型会被告知发生了什么,通常会向用户解释,或者尝试别的办法。

拒绝调用

拒绝调用时,你可以说明原因:

JSON
1{
2 "error": {
3 "message": "No sales data for that period",
4 "user_message": "There are no sales for that period yet."
5 }
6}
字段谁能看到限制
error.message模型,标记为来自你的工具的文本500 个字符
error.user_message终端用户的浏览器,位于 tool_call_completed 事件中300 个字符

两者都是可选的。没有它们时,模型只会被告知工具失败。不要在这两个字段中包含内部细节(堆栈跟踪、表名)。

好的结果是什么样的

  • 小。 返回模型作答所需的字段,而不是整条记录。结果会占用模型的上下文,也会计入你的 token 账单。
  • 命名直白。 对模型来说,{"revenue": 48200, "currency": "USD", "orders": 912} 比按位置排列的数组更易读。
  • 完整,或明确说明是部分结果。 如果你返回的是 300 行中的前 20 行,请说明:{"rows": [...], "total": 300, "truncated": true}。

超时与重试

  • 每个工具有 1 到 30 秒的超时时间(默认 10 秒)。它涵盖整个调用,包括重试。
  • 请求还有一个总时间(默认 120 秒)。开始得晚的工具调用只能使用剩余的时间。
  • 对读取数据的工具的调用,遇到 5xx 或连接失败,且至少还剩一秒时,会重试一次。重试带有相同的 id 和 "attempt": 2。对会更改内容的工具的调用绝不重试。
  • 同一轮次中最多有 4 次调用同时运行,因此调用可能乱序到达并相互重叠。

由于对读取数据的工具的同一次调用可能到达两次,请让你的端点可以安全地重复执行。对于只读取数据的工具,本来就是如此。


会更改内容的工具

标记为 Changes something 的工具只有在终端用户批准调用后才会运行(参见审批)。请求和签名与任何调用相同。不同的是发送方式:

  • 只发送一次。 已批准的调用最多发送一次,带有 "attempt": 1。它绝不会重试,一旦可能已经到达你的端点,就绝不会再次发送,即使 ModelRiver 中途重启也是如此。
  • 使用询问终端用户时保存的参数。 这些参数在模型请求调用时已按 schema 检查过。批准之后不会重新规划或更改任何内容。
  • 在请求的时间内。 等待审批的时间不计入总时间。如果调用被批准时已没有剩余时间,它不会被发送,请求以 tool_loop_timeout 结束。

对于会更改内容的调用,你的应答意味着:

你返回调用的状态模型会被告知
2xx,带 JSON 对象或数组ok结果
2xx,带其他任何内容,或结果使请求超出其 256 KB 的结果总量ok操作已执行,但其结果无法读取,并且不要再次运行它,也不要说它失败了。调用的日志会保留 tool_result_invalid 或 tool_result_too_large
3xx 或 4xxerrortool_endpoint_error:工具拒绝了调用
5xxunknowntool_outcome_unknown:它可能已经完成了一部分
响应体超过 32 KBunknowntool_outcome_unknown:应答在达到限制处被截断,因此无从得知你的端点做了什么
在超时时间内没有应答,或连接失败unknowntool_outcome_unknown

unknown 在请求日志中显示为 "Sent, but whether it finished is not known. It was not sent again." 如果有 HTTP 状态,它会保留在调用的日志中供你查看。

即便如此,也请用调用的 id 让操作可以安全重复:把它和你执行的操作一起保存,对已经处理过的调用 id 返回相同的结果。如果你在完成部分工作后返回 5xx,终端用户会被告知去确认,所以最好把工作做完或撤销,然后返回 2xx 或 4xx。


发送调用前的检查

在以下情况下,ModelRiver 会拒绝调用,且不会联系你的端点:

原因告知模型的代码
模型请求了工作流中没有的工具tool_not_found
参数与工具的 schema 不匹配,或无法检查tool_arguments_invalid
参数超过 16 KBtool_arguments_invalid
请求的工具调用限制已用完tool_call_limit
端点的地址是私有地址或不被允许,或项目没有签名密钥tool_unavailable

参数会按你注册的 JSON Schema 检查。添加 "additionalProperties": false,这样带有你未列出字段的调用会在这里被拒绝。


调用失败时模型会被告知什么

模型会收到一个简短的错误来代替结果:

JSON
1{ "error": { "code": "tool_timeout", "message": "The tool did not respond in time." } }
代码含义
tool_timeout在超时时间内没有应答
tool_endpoint_error4xx、重试后的 5xx、重定向或连接失败。对于会更改内容的工具,只有 3xx 或 4xx
tool_result_invalid响应不是 JSON 对象或数组。会更改内容且应答了 2xx 的工具不会被告知这一点:它的调用为 ok,日志中带有此错误码
tool_result_too_large响应超过大小限制。对于会更改内容的工具,见上表
tool_unavailable无法调用该端点
tool_not_found、tool_arguments_invalid、tool_call_limit见上表
tool_outcome_unknown会更改内容的工具已发送,但没有任何信息说明发生了什么:5xx、未及时应答、连接失败,或响应体超过 32 KB
tool_call_rejected终端用户拒绝了这次调用。它没有被发送
tool_approval_expired没有人及时回应。它没有被发送

这些代码也会出现在请求日志中的每次调用上,并附带只为你保留、绝不展示给模型的细节:HTTP 状态、尝试次数和耗时。


允许的地址

端点 URL 必须是 https://,并解析到公网地址。ModelRiver 在每次调用时都会解析它,并连接到它检查过的地址,因此主机名无法在事后被指向私有网络。私有地址、环回地址和链路本地地址会被拒绝。

下一步

  • 安全:验证签名,并决定该信任什么
  • 审批:终端用户如何批准会更改内容的调用
  • 测试:在端点上线前先试用