文档

modelriver tools

把工作流的托管工具调用发送到你自己机器上的端点,签名方式与生产环境完全一致。

托管工具调用的是公网 HTTPS 端点,因此无法把 localhost 上的端点保存到工具上。modelriver tools 在你开发期间弥补了这一差距:它接收你的请求的工具调用,并转发到你的机器。

需要 @modelriver/cli 2.0 或更高版本(Node.js 22.12 或更高版本)。

用法

Bash
modelriver tools --forward-to http://localhost:3000

CLI 会与你的 API 密钥所属的项目建立一个会话,并打印其 id(cts_…)。保持它运行,然后任选其一:

  • 在 Playground(Async mode)中打开 Send tool calls to my CLI,或
  • 在你后端发出的 POST /v1/ai/async 请求中加入 "tool_route": {"cli_session": "cts_…"}。

每次调用都会被 POST 到你机器上与工具已保存端点相同的路径:保存为 https://api.example.com/tools/orders 的工具,会在 http://localhost:3000/tools/orders 被调用。

选项

选项说明
--forward-to <url>你的工具服务器运行的位置。必须在本机:localhost、127.0.0.1 或 ::1。http 和 https 均可
--print同时打印每次调用的参数和你的端点的结果。默认关闭
--new-session开启一个新会话,而不是重新加入本机保存的会话
-k, --api-key <key>使用该 API 密钥,而不是已保存的密钥
--api-url <url>使用该 ModelRiver API,而不是 https://api.modelriver.com
-v, --verbose显示连接详情

你的端点会收到什么

与线上调用发送的请求相同:相同的 JSON 请求体(逐字节一致)和相同的 x-modelriver-* 请求头,并用项目的工具签名密钥签名。请像在生产环境中那样验证它。请求体的 request 中带有 "via": "cli"。

你的端点照常应答(端点契约)。CLI 会把状态和响应体送回 ModelRiver,在那里按与任何调用相同的规则、大小限制和超时来读取应答。通过 CLI 的调用不会重试。

对会更改内容的工具的调用仍会先等待审批(在 Playground 中由你自己审批),然后通过 CLI 发送一次。如果那时会话已经结束,这次调用不会执行,模型会被告知该工具不可用。

重启 CLI

会话保存在你的机器上的 ~/.modelriver/tool-sessions.json 中,只有你可以读取。当你用相同的 API 密钥和 --forward-to 再次启动 modelriver tools 时(包括它被强制终止之后),它会重新加入该会话,而不是开启新会话:

  • 已经指定该会话的请求可以继续使用,等待审批的调用在获批后会到达重启后的 CLI。
  • 会话 id 只在会话开启时完整打印一次。重启后它以掩码形式显示(cts_…1234)。
  • 上一次运行已经发送到你的服务器的调用,绝不会再次发送给它。ModelRiver 也不会把同一个调用发送第二次:CLI 停止时正在进行的调用会超时,对于会更改内容的工具,其结果会被记录为未知。
  • 如果保存的会话已无法加入(已过期或已被移除),CLI 会说明这一点并开启一个新会话,使用新的 id。如果该组织未开启托管工具,CLI 会给出相应提示并停止,同时保留已保存的会话以便日后使用。
  • 用相同的 API 密钥和 --forward-to 启动的第二个 modelriver tools 会接管该会话,第一个随即停止。需要独立的会话时请传入 --new-session。

在终端中审批调用

对会更改内容的工具的调用会等待其终端用户。测试用你的 API 密钥发出的请求时,你可以在第二个终端中以该用户的身份作答,就像你的后端那样:

Bash
modelriver tools show tc_3f2a9c1d5b7e4a6f8c0d1e2b
modelriver tools approve tc_3f2a9c1d5b7e4a6f8c0d1e2b --end-user user_812
modelriver tools reject tc_3f2a9c1d5b7e4a6f8c0d1e2b --end-user user_812
  • show 会打印审批提示、终端用户看到的参数以及等待结束的时间(GET /v1/ai/tool-calls/:call_id)。
  • approve 和 reject 会发送决定(POST /v1/ai/tool-calls/:call_id/approve 或 /reject)。--end-user 必填,且必须是发出请求时使用的 end_user.id。
  • Playground 运行中的调用要在 Playground 中决定。对这些调用,上述命令会返回 tool_call_not_found。
  • 每条命令成功时以 0 退出,失败时以 1 退出。

要一次完成发送请求并跟进,请使用带 --end-user 和 --cli-session 的 modelriver websocket:它会打印每个等待中的调用以及用于决定它的命令。

安全

  • CLI 只会转发到你自己的机器。任何其他地址都会被拒绝,且不会跟随重定向。
  • 会话属于 API 密钥所在的项目以及该密钥的所有者,24 小时后过期。请求只能指定自己项目的会话,Playground 只会提供用你创建的 API 密钥开启的会话。
  • 每人每个项目最多可同时连接 5 个会话。开启新会话会占用已不再连接的会话的名额。
  • tools 不会使用当前文件夹中 .modelriverrc 里的 API 密钥:克隆的仓库可能植入另一个账户的密钥,该账户就能把调用发送到你的机器。请使用 MODELRIVER_API_KEY、-k 或 modelriver login。
  • 当 CLI 没有运行时,指定了它的会话的请求会被拒绝,如果它中途停止,后续的调用会立即失败。调用绝不会改为发送到保存的端点。
  • 你的生产端点应拒绝带有 "via": "cli" 的调用:会话会收到完整的签名调用。
  • 除非传入 --print,否则不会打印参数和结果。
  • 部署前请移除 tool_route:生产请求绝不应指定 CLI 会话。