文档

抢先体验

托管工具

把你自己的 HTTPS 端点注册为工具。模型选择调用哪个,ModelRiver 发出调用,数据始终由你的后端掌控。

抢先体验: 托管工具按组织开启。请联系支持为你的组织启用。在此之前,工作流 General 选项卡上的 Let the AI call my endpoints 无法选择,工作流上的工具也会被忽略。

什么是托管工具

使用函数调用时,模型请求调用某个函数,由你的代码执行它、把结果发回,如此反复,直到模型给出回答。这个循环运行在你的后端里。

使用托管工具时,这个循环由 ModelRiver 来运行。你在工作流上注册 HTTPS 端点,每个端点都有名称、描述和参数的 schema。请求到来时:

  1. ModelRiver 把用户的消息发送给模型,并附上你的工具供其选用。
  2. 如果模型请求调用某个工具,ModelRiver 会按该工具的 schema 检查参数,然后用签名的 POST 调用你的端点。对于会更改内容的工具,它会先请终端用户批准这次调用。
  3. 你的端点返回 JSON。ModelRiver 把它交给模型。
  4. 重复第 2、3 步,直到模型给出回答,或达到某项限制。
  5. 回答的交付方式与任何异步请求相同:通过 WebSocket,并发送到你的 webhooks。

等待期间,你的前端可以显示当前进展(“Reading this week's sales…”),用户也可以停止请求。参见进度事件。


一个示例

某家门店的管理页面里有一个助手。工作流 sales_chat 有两个工具:get_sales_summary 和 get_top_products。你的后端发送:

Bash
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 字段

发往带有托管工具的工作流的请求,必须说明它是为谁发起的:

JSON
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 选项卡。

限制默认值范围限制的内容
轮次52 到 10一次请求中的模型调用次数。最后一个允许的轮次会在关闭工具的情况下运行,因此模型必须作答:5 个轮次意味着工具最多可以在 4 个轮次中运行
工具调用161 到 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 中的运行也都不计数。

最终响应会说明该请求的用量:

JSON
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)。

工具已关闭的工作流与以前完全一样地工作,包括由客户端运行的函数调用。


下一步