OpenRouter、TypeScript SDKを用いた「ツール呼び出しエージェントループ」の構築手順を公開

要点

• OpenRouterは2026年9月17日、公式TypeScript SDKを用いてツール呼び出しを行うエージェントの制御ループを実装する技術解説を公開した。

• 特別なフレームワークに頼らず、反復回数の上限設定や同一呼び出しの繰り返し検知によって安全にループを制御する設計が示された。

• 優先順位付きのモデル指定による自動フォールバックや、プロバイダーを自動最適化する「Auto Exacto」機能の仕様が紹介された。

• 関数の実行エラーを例外終了させずにモデルへ送り返し、モデル自身に引数修正や別ツールの選択を促すエラー処理の手法が解説された。

• AIモデルのルーティングプラットフォームを提供するOpenRouterは2026年9月17日、公式ブログにおいてTypeScript SDKを用いたツール呼び出し（Tool Calling：AIモデルが外部関数を呼び出す仕組み）エージェントループの構築ガイドを公開した。外部のエージェント開発フレームワークを使用せず、アプリケーション側の制御コードのみで信頼性の高いループ処理を構築するための具体的な実装手順や停止条件の設計が示されている。

エージェントループの基本構造と停止条件

公開されたエージェントループは、会話履歴と利用可能なツールの定義をモデルへ送信し、モデルから要求されたツールを実行してその結果を会話履歴に追加した上で、モデルに次の動作を問い合わせる処理を繰り返す仕組みとなっている。どのツールを呼び出すかはモデルが判断する一方、引数の検証や関数の実行、ループ全体の停止判断はアプリケーション側が担当すると説明されている。

このループ処理は、以下の手順で進行する。
まず、全会話履歴とツール定義を添えてモデルを呼び出す。モデルからの応答にツール呼び出し要求が含まれていない場合は、生成されたテキストメッセージを返してループを終了する。許容される最大反復回数（iteration cap）に達した場合は、結果をモデルに送り返せないためツールを実行せずに停止する。さらに、同一のツール呼び出しが上限回数を超えて繰り返された場合にも停止処理を行う。それ以外の場合は要求されたすべてのツールを実行し、アシスタントのメッセージと各呼び出しIDに対応する実行結果を会話履歴に追加して次のターンへ進む。

モデルが失敗した呼び出しを繰り返したり探索を続けたりする挙動を防ぐため、ハードリミットとしての反復上限設定が不可欠であると強調されている。

SDKの導入とフォールバックを含むモデル・ツールの定義

実装手順では、TypeScript環境において公式パッケージ「@openrouter/sdk」および実行環境の「tsx」を導入する構成が提示されている。APIキーを設定してクライアントを初期化した後、利用するモデル一覧とローカルツールの定義を行う。

モデルの指定では、modelsパラメータに複数のモデル名を優先順位順の配列として設定できる。公開されたコード例では「google/gemini-3-flash-preview」と「nvidia/nemotron-3.5-lightning」が指定されており、上位モデルが利用できない場合の順次フォールバックに対応する。また、OpenRouterの機能である「Auto Exacto」により、ツール呼び出しリクエスト時には最適なプロバイダーへの並び替えが既定で自動実行されるという。

ツール定義では、関数の名前や詳細な説明文、JSONスキーマ形式の引数プロパティを記述する。例示ではナイジェリアのラゴス（Lagos）および英国のロンドン（London）のローカル天気データを取得する「get_weather」関数が定義されており、受け付ける都市名を明示して制限を設けることで、モデルが有効な引数を生成しやすくなる手法が紹介されている。

API通信とツール選択パラメータの制御

モデルへのリクエスト送信を行う関数では、openRouter.chat.sendメソッドが使用される。SDKの仕様として、JavaScript側で指定されたキャメルケース（camelCase）のプロパティ名（toolChoiceやmaxCompletionTokens、toolCallsなど）は、APIの通信形式であるスネークケース（snake_case）へ自動的に変換される。

また、ツールの定義情報は、実行結果をモデルに送り返すフォローアップリクエストを含め、すべての通信で継続して送信し続ける必要があるとされている。これにより返却された呼び出し要求の検証が行えるほか、モデルが後続の処理で別のツールを使用すべきかを判断可能になるためだという。

ツール選択の挙動を制御するtoolChoiceパラメータについて、例示コードの初回ターンでは確実にツール呼び出しを経由させる目的でtoolChoice: "required"が指定され、2回目以降のターンでは"auto"に切り替える実装が取られている。毎回ツール実行を強制するとモデルがテキストによる最終回答を出せなくなるためであり、APIの既定値自体はツール定義が存在する場合は"auto"であると説明されている。

安全なツール実行とエラーハンドリング

モデルから要求されたツールを実行する処理では、1つのツール呼び出しに対して1つの結果メッセージを作成して返送する。モデルから渡される引数はJSON形式の文字列であるため、アプリケーション側での解析処理（JSON.parse）はtry-catchブロックの内部で実行することが推奨されている。

引数の形式不正や未対応の関数名の指定、データが存在しないといった実行時エラーが発生した場合、アプリケーション全体を例外で停止させるのではなく、エラー内容をJSON文字列にして役割（role）がtoolのメッセージとしてモデルへ送り返す設計が示されている。エラー結果を受け取ることで、モデル側が引数を修正して再実行したり、別のツールを選択したり、ユーザーに対して失敗の理由を説明したりといった対応が可能になるという。

各結果メッセージには要求元の呼び出しを識別するためのtoolCallIdが付与され、モデルがどの呼び出しに対する結果であるかを正確に対応付けられるように構成されている。