Agent SDK 的人机协同工具 | OpenRouter

OpenRouter 宣布其 Agent SDK 推出第四种工具类型——人机协同（Human-in-the-Loop, HITL）工具。该功能允许代理在运行过程中根据预设逻辑自动处理常规调用，同时在需要人工判断的场景下暂停执行，所有控制逻辑集中在一个钩子函数中。

安装 SDK 后，开发者可以定义 HITL 工具，并通过配套的示例教程快速实现。HITL 工具的核心机制在于 onToolCalled 钩子：当代理调用该工具时，钩子函数检查输入数据并做出决策。如果返回一个值，代理继续运行（类似常规工具）；如果返回 null，则循环暂停，状态变为 awaiting_hitl，应用程序可以获取待处理的调用并向用户展示。用户做出决策后，通过 callModel 传入包含人类决定的结果，代理循环恢复。

此外，SDK 还提供了可选的 onResponseReceived 钩子，用于在人类提交结果后、模型接收前对原始输入进行转换。开发者可以利用它添加元数据、标准化格式、验证业务规则或补充上下文。如果钩子抛出错误，错误信息会以 { error: ..., originalOutput: ... } 的形式传递给模型，确保不遗漏任何异常。

HITL 工具与现有的 requireApproval 功能有何不同？两者都会暂停等待人类输入，但决策逻辑不同。requireApproval 在所有调用执行前都需要明确的人工同意，适用于“删除数据库”或“发送邮件”等场景。而 HITL 工具仅在钩子返回 null 时暂停，且可以基于数据（如金额、风险评分、内容策略标记等）自动决定是否跳过人工审核。例如，支付金额低于 100 美元自动批准，高于则请求人工确认。

完整的生命周期如下：模型在代理循环中调用 HITL 工具 → onToolCalled 运行，返回值则继续，返回 null 则暂停 → 应用程序通过 getToolCalls() 获取待处理调用并呈现给用户 → 用户做出决定 → 通过 callModel 将决定作为 function_call_output 传入 → onResponseReceived（如果有）转换响应 → 模型接收结果，代理循环继续。SDK 负责状态跟踪、钩子分发和模式验证，开发者无需编写循环代码。

OpenRouter 提供了详细的示例教程、完整类型签名和 API 参考文档，帮助开发者快速上手。开发者可以获取 API 密钥，并在 Discord 社区分享他们的构建成果。