抢先体验: 托管工具按组织开启。请联系支持为你的组织启用。在此之前,工作流 General 选项卡上的 Let the AI call my endpoints 无法选择,工作流上的工具也会被忽略。
什么是托管工具
使用函数调用时,模型请求调用某个函数,由你的代码执行它、把结果发回,如此反复,直到模型给出回答。这个循环运行在你的后端里。
使用托管工具时,这个循环由 ModelRiver 来运行。你在工作流上注册 HTTPS 端点,每个端点都有名称、描述和参数的 schema。请求到来时:
- ModelRiver 把用户的消息发送给模型,并附上你的工具供其选用。
- 如果模型请求调用某个工具,ModelRiver 会按该工具的 schema 检查参数,然后用签名的
POST调用你的端点。对于会更改内容的工具,它会先请终端用户批准这次调用。 - 你的端点返回 JSON。ModelRiver 把它交给模型。
- 重复第 2、3 步,直到模型给出回答,或达到某项限制。
- 回答的交付方式与任何异步请求相同:通过 WebSocket,并发送到你的 webhooks。
等待期间,你的前端可以显示当前进展(“Reading this week's sales…”),用户也可以停止请求。参见进度事件。
一个示例
某家门店的管理页面里有一个助手。工作流 sales_chat 有两个工具:get_sales_summary 和 get_top_products。你的后端发送:
curl -X POST https://api.modelriver.com/v1/ai/async \ -H "Authorization: Bearer $MODELRIVER_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "workflow": "sales_chat", "messages": [ {"role": "user", "content": "How did we do this week, and what sold best?"} ], "end_user": { "id": "user_812", "claims": {"store_id": "st_44", "role": "manager"} } }'模型请求调用这两个工具。ModelRiver 调用两个端点,每次调用都带上模型选择的参数和你发送的 end_user。模型读取两个结果后写道:“本周销售额为 48,200 美元,比上周增长 12%。卖得最好的是台灯,售出 310 件。”
这次请求用了两个模型轮次和两次工具调用。
团队用这种方式构建的其他功能:读取员工假期余额的 HR 助手、能回答“是什么阻碍了发布?”的项目页面、解释客户最近三张发票的财务视图。在每种情况下,都由模型决定向你的后端问哪个问题,由你的后端决定该用户可以知道什么。
各自的职责
| ModelRiver | 你的后端 |
|---|---|
| 在每个供应商上把你的工具提供给模型,且只提供给能调用工具的模型 | 把每个工具实现为一个 HTTPS 端点 |
| 在任何调用之前,按工具的 schema 检查模型给出的参数 | 检查每次调用的签名 |
为每次调用签名,并传递你发送的 end_user | 根据 end_user 决定返回什么,绝不根据参数 |
| 并行执行调用,对失败的读取重试一次,强制执行超时 | 快速返回 JSON |
| 每次调用会更改内容的工具之前,等待终端用户批准,并且已批准的调用只发送一次 | 在你的应用中展示审批,并用你的 API 密钥转发终端用户的决定 |
| 达到你设置的限制时停止 | 在控制台中设置这些限制 |
| 在请求日志中显示每个轮次和每次调用 |
模型永远看不到 end_user、你的签名密钥和你的端点 URL。
哪些模型可以运行工具
工具轮次只在能调用工具的模型上运行:即控制台模型选择器中带有 Tools 标签的模型。目录中的所有对话模型都可以,以下除外:
- OpenAI 和 Azure OpenAI 上的 GPT-6 Astra、GPT-6.1 Sol 和 GPT-6.1 Terra(它们的工具调用需要 Responses API,而 ModelRiver 使用 Chat Completions)
- Amazon Bedrock 上的 GPT-6.1 Sol 和 GPT-6.1 Terra,原因相同
- Cohere Command A Vision
嵌入模型不能调用工具;自定义端点永远不会被拒绝:ModelRiver 会把工具原样传过去,请确认你的服务器支持工具。
使用不能调用工具的模型时会发生什么:
| 时机 | 结果 |
|---|---|
| 保存或发布 | 只要工具已开启且至少有一个工具处于开启状态,就会被拒绝,并指明是哪个位置:"claude-x (backup 1) can't call tools. Pick a model that can, or turn tools off." 编辑器会在保存前提醒,模型选择器也会把这类模型标为 No tools |
| 请求运行时 | 故障转移会跳过该位置,就像跳过超出预算的位置一样,然后尝试下一个。时间线会把这次跳过显示为 Skipped,并附上原因。它不计数 |
| 没有任何位置能调用工具 | 请求在调用任何模型之前以 tool_model_unsupported 结束,不计数。固定到某一个位置的 Playground 运行只检查该位置。参见请求如何结束 |
在此检查上线之前已发布(Live)的工作流会继续运行:请求只使用其中能调用工具的模型。编辑器会显示警告,在修正模型或关闭工具之前,该工作流无法再次发布。
end_user 字段
发往带有托管工具的工作流的请求,必须说明它是为谁发起的:
1"end_user": { "id": "user_812", "claims": { "store_id": "st_44" } }| 字段 | 规则 |
|---|---|
id | 必填。文本,最多 256 个字符。即你应用中已登录的用户 |
claims | 可选。一个扁平对象,最多 16 个条目。值为文本、数字或 true/false。最大 2 KB |
ModelRiver 会在签名的请求体中把 end_user 传给每次工具调用,因此你的端点可以像信任自己的后端一样信任它。它不会发送给模型,也不会加入提示词。
使用会话记忆时,某个会话上第一次使用的 end_user.id 即为该会话的所有者。对同一 session_id 使用不同 id 的请求会被拒绝,并返回 409 end_user_mismatch。对话会记住用户的问题和最终回答;工具调用及其结果不会在之后的轮次中重放。
限制
每个带有托管工具的请求都在限制内运行,因此不断请求工具的模型不会无休止地运行下去。前三项由你按工作流设置,位于工作流的 Tools 选项卡。
| 限制 | 默认值 | 范围 | 限制的内容 |
|---|---|---|---|
| 轮次 | 5 | 2 到 10 | 一次请求中的模型调用次数。最后一个允许的轮次会在关闭工具的情况下运行,因此模型必须作答:5 个轮次意味着工具最多可以在 4 个轮次中运行 |
| 工具调用 | 16 | 1 到 64 | 一次请求中对你的端点的调用次数 |
| 总时间 | 120 秒 | 10 到 240 秒 | 整个请求:模型轮次、故障转移和工具调用 |
| 单个工具超时 | 10 秒 | 1 到 30 秒 | 对一个端点的一次调用,包括其重试。在每个工具上设置 |
| 每个工作流的工具数 | 16 | ||
| 同时进行的调用 | 4 | 同一轮次中同时运行的工具调用 | |
| 结果大小 | 32 KB | 单个工具的响应体 | |
| 每次请求的结果总量 | 256 KB | 一次请求中所有结果的总和 | |
| 参数大小 | 16 KB | 单次调用的参数 | |
| 审批等待 | 10 分钟 | 1 到 60 分钟 | 对会更改内容的工具的一次调用等待终端用户回应的时长。在 Tools 选项卡中设置。不计入总时间 |
| 等待审批的请求 | 50 | 每个项目。参见审批 |
你的套餐可能对轮次和工具调用设置更低的上限,也可能限制一个项目可同时运行的托管工具请求数量。以较低的限制为准。
当请求达到轮次或工具调用限制时,模型会获得最后一个关闭工具的轮次。如果它作答,请求成功。否则,请求以错误 tool_loop_limit 结束。参见请求结束时的情形。
什么算作一次请求
每个模型轮次计为套餐中的一次请求。工具调用免费。
一个需要三个轮次的问题会用掉三次请求。无论请求如何结束都是如此:被某项限制、被用户或因供应商故障而停止的请求,仍会计入已运行的轮次。在开始前就被拒绝的请求(400、409 或 429)不计数;以 tool_model_unsupported 结束的请求、因不能调用工具而被跳过的模型位置,以及在 Playground 中的运行也都不计数。
最终响应会说明该请求的用量:
1"meta": { "tool_loop": { "rounds": 2, "tool_calls": 2 } }tool_calls 统计发送到你端点的调用。被终端用户拒绝的调用,或等待超时的调用,都不计数。用量 API 按天和按月报告 tool_rounds 和 tool_calls。
托管工具目前还不支持的功能
- 仅支持异步。 请把请求发送到
POST /v1/ai/async。同步端点和"stream": true会返回400 tools_require_async;OpenAI 兼容端点会以 OpenAI 错误格式返回400,错误码为model_not_supported。 - 回答一次性完整到达。 工具进度是实时的,但最终回答不会逐 token 流式返回。
- 未经询问不会更改内容。 每个工具都被标记为只读取数据或会更改内容。读取数据的工具在模型请求时立即运行。会更改内容的工具只有在终端用户批准这次调用后才会运行,并且没有跳过询问的设置。参见审批。
- 聊天工作流。 一个工作流不能同时拥有托管工具和后端管道或结构化输出。参见管道还是工具?。
- 请求不能自带工具。 发往带有托管工具的工作流的请求不能发送自己的
tools或response_format(400 tools_conflict)。
工具已关闭的工作流与以前完全一样地工作,包括由客户端运行的函数调用。