托管工具就是你的一个 HTTPS 端点。每次工具调用,ModelRiver 都会向它发送一个 POST,并读取 JSON 回复。本页是这两个方向的参考。
请求
1POST /tools/sales-summary HTTP/1.12Host: api.yourapp.com3Content-Type: application/json4Accept: application/json5x-modelriver-timestamp: 17945906236x-modelriver-tool-call-id: tc_3f2a9c1d5b7e4a6f8c0d1e2b7x-modelriver-key-id: tk_9f2c41ab77d08x-modelriver-signature: v2=5ee0bc5f7ae14a7264dc8f03ccd69713902119d079910a7bee871034cf59f5281{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-signature | v2= 后接签名。密钥轮换期间为两个值,以逗号分隔 |
如何检查签名,参见安全。
请求体
| 字段 | 说明 |
|---|---|
version | 2。契约版本 |
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.attempt | 1,重试时为 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。会更改内容的工具:结果未知(见下文) |
工具调用失败不会导致请求失败。模型会被告知发生了什么,通常会向用户解释,或者尝试别的办法。
拒绝调用
拒绝调用时,你可以说明原因:
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 或 4xx | error | tool_endpoint_error:工具拒绝了调用 |
5xx | unknown | tool_outcome_unknown:它可能已经完成了一部分 |
| 响应体超过 32 KB | unknown | tool_outcome_unknown:应答在达到限制处被截断,因此无从得知你的端点做了什么 |
| 在超时时间内没有应答,或连接失败 | unknown | tool_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 KB | tool_arguments_invalid |
| 请求的工具调用限制已用完 | tool_call_limit |
| 端点的地址是私有地址或不被允许,或项目没有签名密钥 | tool_unavailable |
参数会按你注册的 JSON Schema 检查。添加 "additionalProperties": false,这样带有你未列出字段的调用会在这里被拒绝。
调用失败时模型会被告知什么
模型会收到一个简短的错误来代替结果:
1{ "error": { "code": "tool_timeout", "message": "The tool did not respond in time." } }| 代码 | 含义 |
|---|---|
tool_timeout | 在超时时间内没有应答 |
tool_endpoint_error | 4xx、重试后的 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 在每次调用时都会解析它,并连接到它检查过的地址,因此主机名无法在事后被指向私有网络。私有地址、环回地址和链路本地地址会被拒绝。