Agent SDK のヒューマン・イン・ザ・ループツール | OpenRouter

OpenRouter は、Agent SDK に第4のツールタイプとしてヒューマン・イン・ザ・ループ（HITL）ツールを導入したことを発表しました。この機能により、エージェントはルーティンコールを自動的に処理し、重要度の高い場面では人間の介入を待つことができ、すべての制御ロジックを単一のフックに集約できます。

SDK をインストールし、HITL ツールを定義すれば、クックブックレシピに従って実装をすぐに開始できます。HITL ツールの核心は onToolCalled フックです。エージェントがツールを呼び出すと、フックが入力を検査し、値を返せばエージェントは続行（通常のツールと同様）、null を返せばループが一時停止し、ステータスが awaiting_hitl になります。アプリケーションは getToolCalls() で保留中の呼び出しを取得し、ユーザーに提示します。ユーザーが決定を下したら、その結果を function_call_output として callModel に渡すことで、エージェントループが再開します。

さらに、オプションの onResponseReceived フックを使用すると、人間が応答を提供した後、モデルが受け取る前に変換を行うことができます。メタデータのスタンプ、フォーマットの正規化、ビジネスルールの検証、または人間が手動で入力する必要のないコンテキストの補完などに利用できます。フックがエラーをスローした場合、エラーは { error: ..., originalOutput: ... } としてモデルに伝達され、何も黙って飲み込まれることはありません。

HITL ツールと既存の requireApproval 機能の違いは何でしょうか？両方とも人間の入力を待ちますが、決定ロジックが異なります。requireApproval は、すべての呼び出しの実行前に明示的な人間の同意を必要とし、「データベースを削除」や「メールを送信」などのシナリオに適しています。一方、HITL ツールはフックが null を返した場合のみ一時停止し、金額、リスクスコア、コンテンツポリシーフラグなどのデータに基づいて自動的に人間のレビューをスキップするかどうかを決定できます。たとえば、100ドル未満の支払いは自動承認、それ以上は人間の確認を要求する、といった使い方が可能です。

完全なライフサイクルは以下の通りです：モデルがエージェントループ中に HITL ツールを呼び出す → onToolCalled が実行され、値を返せば続行、null を返せば一時停止 → アプリケーションが getToolCalls() で保留中の呼び出しを取得し、ユーザーに提示 → ユーザーが決定 → その決定を function_call_output として callModel を呼び出す → onResponseReceived（定義されていれば）が応答を変換 → モデルが結果を受け取り、エージェントループが再開。SDK が状態追跡、フックのディスパッチ、スキーマ検証をすべて処理するため、開発者はループコードを一切記述する必要がありません。

OpenRouter は、完全な実装例を示すクックブックレシピ、完全な型シグネチャと API リファレンスを提供しています。API キーを取得して、Discord で何を構築しているかをぜひ共有してください。