コーディングエージェント(Claude Code や OpenAI Codex CLI など)は「タスク」単位で動作します。開発者が変更を依頼すると、エージェントはファイルを読み、コードを編集し、テストを実行して作業を完了します。1 つのタスクには数回のモデル呼び出しで済むこともあれば、数十回必要なこともあります。開発者が支払うのはタスク全体に対してであり、個々の呼び出しに対してではありません。
トークン単価だけではタスク全体のコストは分かりません。総コストは、モデルが何ターン必要とするか、各ターンでどれだけの履歴を再送するか、タスクがどれくらい再試行されるか、あるいは完了しない頻度に依存します。完了しなかったタスクの試行も含め、すべての試行に対して支払いが発生します。したがって、コーディングエージェントのリクエストをモデル間でルーティングする場合、評価軸は「解決済みタスクあたりのコスト」、つまり全実行の総コストをテストに合格した実行数で割った値にすべきです。
NVIDIA NeMo Switchyard は、AI エージェントが各リクエストをどのモデルで処理するかを選択するためのオープンソースライブラリです。使用可能なモデルと従う戦略を定義します。LiteLLM 連携では 2 つの戦略をサポートします。Stage ルーティングはリクエスト履歴にある直近のツール活動と結果を読み、2 つの候補モデルから 1 つを選びます。Random ルーティングは設定済みモデルからオプションの重み付きで選択し、トラフィック分割や A/B 比較に適しています。さらに LiteLLM は最近、ネイティブの Switchyard stage router を auto-router 戦略として搭載しており、こちらも検討に値します。
この記事では AWS Cloud Development Kit(AWS CDK)を使い、LiteLLM(大規模言語モデル向けのオープンソースゲートウェイ)と Switchyard ルーティングプラグインを AWS アカウントにデプロイします。LiteLLM が Amazon Bedrock 上のモデルを呼び出します。その後、サンプル付属のベンチマークランナーを用いて、ルーティングされたモデルグループと単一モデルのベースライングループについて「解決済みタスクあたりのコスト」を測定し、独自のワークロードでルーティングを評価できるようにします。
注意点として、このサンプルは crates.io から switchyard-server 0.3.0 をインストールし、公開されている LiteLLM v1.102.0 イメージを実行します。NVIDIA は switchyard-server 0.3.0 をデモおよび評価用コンポーネントと位置付けており、設定はリリース間で変わる可能性があります。本サンプルは実験的な Switchyard LiteLLM 連携を使用しており、その設定と API もリリース間で変更される可能性があります。これはサンプルコードであり、本番用途向けではありません。デプロイ前に、組織のセキュリティ、規制、コンプライアンス要件を満たすようセキュリティチームと法務チームと協力してください。非本番アカウントにデプロイし、信頼する前にテストしてください。
ソリューションの概要として、LiteLLM と Switchyard プラグインは 1 つのコンテナイメージとして、プライベートサブネット内の Amazon ECS on AWS Fargate で動作します。リクエストは次のように流れます。コーディングエージェントは、model フィールドを switchyard(Switchyard がルーティングする LiteLLM モデルグループ)に設定し、共有ゲートウェイキーを Authorization ヘッダーに含めた OpenAI 互換リクエストを送信します。エンドポイントは所有するホスト名で、HTTPS 経由でアクセスし、ロードバランサーには ACM 証明書を設定、許可した IPv4 CIDR 範囲のみ到達可能です。Amazon Route 53 にホストゾーンがあれば、Route 53 がホスト名をロードバランサーに解決します。AWS WAF は IP レピュテーション、既知の悪意ある入力、IP ごとのレート制限ルールでリクエストをフィルタリングします。Application Load Balancer は /v1/chat/completions、/v1/models、/health/liveliness のみをプライベートサブネット内の ECS タスクに転送し、それ以外のパスには 404 を返します。
タスクは 1 つのコンテナを実行します。Switchyard プラグインを内蔵した LiteLLM です。LiteLLM はゲートウェイキーを検証し、プラグインを呼び出してモデルを選択します。Stage は高性能モデルと低コストの高効率モデルの間で選択し、リクエスト履歴のツール活動と結果を読み取るため、エージェントは完全な会話履歴を送信する必要があります。Random は重み付きプールから選択します。どちらの戦略も判定モデルを呼び出しません。LiteLLM はタスクの IAM ロールの認証情報を用いて、Amazon Bedrock Converse または ConverseStream API 経由で選択されたモデルを呼び出します。呼び出しは Amazon VPC 内の Amazon Bedrock Runtime インターフェイスエンドポイントを経由するため、推論トラフィックは AWS ネットワーク内に留まります。応答またはトークンストリームは LiteLLM とロードバランサーを通って返ります。x-litellm-model-name レスポンスヘッダーが応答したモデルを示し、レスポンス本文の model フィールドは switchyard のままです。
LiteLLM はコンテナ内のポート 4000 で待ち受け、ロードバランサーのターゲットになります。タスクのセキュリティグループはロードバランサーからのみ許可します。パス許可リストにより、LiteLLM の管理 UI、API ドキュメント、キー管理ルートには到達できません。Amazon ECR がゲートウェイイメージを保持します。AWS Secrets Manager がゲートウェイキーの背後にあるシークレットを生成し、コンテナ起動時に sk- プレフィックスを追加します。タスク定義は LITELLM_CONFIG_TEXT と SWITCHYARD_CONFIG_TEXT でプロファイルファイルを渡し、起動スクリプトが LiteLLM 起動前に /tmp に書き込みます。ログは単一の CloudWatch ロググループ //litellm に送られ、30 日間保持されます。Container Insights がメトリクスを収集します。VPC は 2 つのアベイラビリティーゾーンにまたがり、1 つの NAT ゲートウェイがイメージ取得や他の AWS サービスへのアウトバウンドアクセスを提供します。
プラグインは Stage ルーティング(候補がちょうど 2 つ必要)と Random ルーティング(少なくとも 2 つの候補が必要で、A/B テスト用に重みでトラフィックを分割)をサポートします。分類器ベースの戦略(Task や Composite ルーティングなど)は中間モデル呼び出しを必要とし、この連携ではサポートされません。完全なカタログは Switchyard ルーティングの概要を参照してください。
前提条件は次のとおりです。Claude Opus 5.5 と NVIDIA Nemotron 3 Super 120B に Amazon Bedrock でアクセスできる非本番 AWS アカウント(この組み合わせは米国東部(バージニア北部)でテスト済み)。認証情報が設定され、AWS リージョンを明示した AWS CLI v2 で、AWS CDK のブートストラップ済みのアカウントとリージョン。Node.js 20 以降、npm、BuildKit 対応の Docker、Python 3.11 以降。所有するホスト名で、そのドメインのパブリック Route 53 ホストゾーン、またはデプロイリージョン内の ACM 証明書があること。簡単な HTTP テストのみならどちらも不要です。
手順として、まずサンプルリポジトリをクローンし、ディレクトリに移動します。ステップ 1 では LiteLLM でモデルグループを定義します。LiteLLM のモデルグループは 1 つの公開モデル名とその背後にある 1 つ以上のデプロイです。サンプルは profiles/ 配下のデプロイプロファイルに設定を保持し、各プロファイルは litellm.yaml(モデルとゲートウェイ設定を定義)と switchyard.toml(Switchyard のモデル選択方法を制御)を組み合わせます。stage プロファイルでは、ルーティンググループ switchyard、2 つの単一モデルベースライングループ claude-opus-5-5 と nemotron-super-3-120b、およびプラグイン登録を定義します。両候補は model_name: switchyard を共有するため、クライアントは "model": "switchyard" を送信し、Switchyard が候補を選びます。Stage は順序から役割を読み取るため、高性能モデルを先に、高効率モデルを後にリストします。claude-opus-5-5 と nemotron-super-3-120b のグループは単一モデルベースラインで、それぞれ常に自身のモデルで応答するため、同じデプロイ内でルーティンググループのコストと合格率を各モデル単独と比較できます。Stage プラグイン単体では候補が 2 つ未満のグループを拒否するため、イメージは小さなラッパー switchyard_gateway.configured.ROUTING_PLUGIN を登録します。これは 2 つ以上の一意な候補を持つグループに Switchyard を適用し、単一モデルグループはそのまま通します。設定ではこのラッパーを 2 回登録します。1 回はモデル選択用、もう 1 回は Switchyard が記録するリクエスト変更の適用用です。すべてのモデルが bedrock/converse/ を使用するため、すべての候補は Amazon Bedrock Converse API を経由し、検証は他のルートを拒否します。LiteLLM の request_timeout は 600 秒で、ロードバランサーの 10 分のアイドルタイムアウトと一致します。このファイルには認証情報を含めません。LiteLLM は環境変数からゲートウェイキーを読み取り、AWS 認証情報はタスクロールが提供します。litellm_params の下に aws_access_key_id、aws_secret_access_key、api_key などの認証情報を追加しないでください。スタックは litellm.yaml 全体をプレーンテキストでタスク定義と CloudFormation テンプレートにコピーするためです。スタックはこのファイルからタスクロールの Amazon Bedrock 権限を導出します。グローバルクロスリージョン推論プロファイルの場合、基盤モデルリソースは * リージョンと末尾の * を使用するため、同じプレフィックスを持つ他のモデル ID にも一致します。デプロイ前に導出されたポリシーを確認してください。global. プレフィックスはグローバルクロスリージョン推論プロファイルを示し、Amazon Bedrock はサポートされる商業リージョン内のどこでもリクエストを処理する可能性があります。処理場所が重要な場合は、地理的プロファイルまたはリージョン内モデル ID を使用してください。Nemotron 3 Super では、プロファイルはリージョン内モデル ID nvidia.nemotron-super-3-120b を使用しており、テスト用に任意のモデルに切り替えられます。
ステップ 2 では Stage ルーティングを設定します。Switchyard は switchyard.toml からアルゴリズムと設定を読み取ります。デフォルトの profiles/stage/switchyard.toml は Stage を次のように設定します。algorithm = "stage"、picker = "efficient_first"、confidence_threshold = 0.5、recent_window = 3、only_on_wrong_signal_escalation = true。これらの設定は次のように機能します。picker = "efficient_first" は履歴のシグナルが不確定な場合に高効率モデルを使用します。新しいリクエストにはまだツール結果がないため、Nemotron 3 Super に送られます。confidence_threshold は Stage がスコアリングする実行シグナルの信頼度しきい値で、0 から 1 の範囲です。recent_window = 3 は Stage が直近 3 つのツール結果を調べることを意味します。only_on_wrong_signal_escalation = true は Switchyard のデフォルトで、Stage がオプションのエスカレーションノートを追加するタイミングを制御しますが、このプロファイルではノートを設定していません。Stage はオプションのハンドオフノートと階層別システムプロンプト(escalation_note、deescalation_note、capable_system_prompt、efficient_system_prompt)も受け付けますが、サンプルプロファイルでは設定していません。A/B テストを行う場合、profiles/random/ の Random プロファイルは同じモデルで algorithm = "random" と weights = [0.5, 0.5] を使用し、重みは宣言順に各一意な候補に対応します。デプロイするには、ステップ 3 の cdk diff および cdk deploy コマンドに -c routingProfile=random を追加します。スタックは合成時に両ファイルを一緒に検証し、プリフライトスクリプトも同じチェックを実行します。