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 社區分享他們的構建成果。