OmniRoute Auto Comboの予算設定とAgentルーティング

公式のAuto Combo文書では、予算超過時の厳格なフォールバックを指定すると、候補が残らない場合にHTTP 402で処理を停止できます。Auto Combo公式文書

したがって、予算を重視する本番のAI Agentは、最初に候補モデルをホワイトリスト化し、その後でリクエスト予算とstrict方針を設定してください。既定のcheapest回退だけに任せると、最安候補であっても設定した上限を超えて処理が続く場合があります。

この手順は、OmniRoute Auto Comboで単発リクエストの費用を管理したい開発者向けです。複数のAIコーディングツールを共通ルールで運用するプラットフォーム担当者や、ローカルゲートウェイを常時稼働環境へ移行する遠隔チームにも適しています。

予算を3つの管理層に分けてから設定します

最初に区別すべきなのは、単発リクエストの予算、APIキーのToken上限、チーム全体の期間予算です。OmniRouteのAPI Referenceでは、米ドル単位の予算とToken上限が別の機能として扱われています。API Referenceの予算とToken上限

ここを混同すると、「1回は安いが月間で使い過ぎる」「月間枠は残っているが、長いコード修正依頼だけ高額になる」といった状態を見逃します。まず本番Agentごとに、超過時の動作を次の3種類から決めます。

• 阻断：処理を止め、Agent側で人間の承認を求めます。
• 降格：許可された安価な候補へ切り替えます。
• 通知：処理は続けますが、ログとアラートを残します。

費用上限を契約条件として扱う場合は阻断、開発中の補助Agentなら降格、調査用の低リスク処理なら通知という分け方が現実的です。

第一段階：候補モデルを最小構成に絞ります

Auto Comboは接続済みのプロバイダーを動的に評価し、資格情報が有効な接続を候補として扱います。Auto Comboの候補生成と自動ルーティング

ただし、接続されていることと、本番Agentに適していることは同じではありません。最初の構成では、次の条件を満たした候補だけを登録します。

1. APIキーまたはOAuth資格情報の検証が完了している。
2. 通常のチャット要求を送信し、応答を確認している。
3. ストリーミング出力に対応している。
4. ツール呼び出しや長い入力を必要とするAgent処理で問題がない。
5. 利用不能時に切り替える代替候補が決まっている。

設定値は実際のアカウント情報を埋め込まず、次のような構造で管理します。

{
  "strategy": "auto",
  "config": {
    "candidatePool": [
      { "model": "<PRIMARY_MODEL>", "purpose": "高難度のコード修正", "fallback": "<BACKUP_MODEL>" },
      { "model": "<LOW_COST_MODEL>", "purpose": "軽量な要約と確認", "fallback": "<SECONDARY_MODEL>" }
    ],
    "budgetCap": "<REQUEST_BUDGET_USD>",
    "budgetFallback": "strict"
  }
}

候補を増やすほど必ず良くなるわけではありません。モデルごとの能力差、利用制限、資格情報の有効期限、ツール呼び出しの互換性まで確認できない段階では、少数の候補のほうがルーティング理由を追跡しやすくなります。

選択条件を先に固定します

• 高精度なコード変更が必要で、上限内の候補がある場合は、品質重視の候補を選びます。
• 上限内に軽量候補しかない場合は、処理を降格できるAgentだけ切り替えを許可します。
• すべての候補が上限を超える場合は、費用を優先する本番Agentならstrictで停止します。
• 資格情報が無効、供給停止、またはレート制限中の場合は、同じ条件を満たす代替候補へ回退します。
• 代替候補が高額になる場合は、回退せず人間の確認へ戻します。

第二段階：予算上限とstrictをリクエスト単位で検証します

公式文書で確認できるリクエスト制御は、モード指定、予算上限、予算超過時のフォールバックを示す3つのヘッダーです。特にX-OmniRoute-Budgetは、推定費用が上限を超える候補を選択前に除外します。リクエスト単位の制御項目

再現用の要求は、値を固定せず環境変数や秘密管理機能から渡します。

curl -sS <OMNIROUTE_BASE_URL>/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <OMNIROUTE_API_KEY>" \
  -H "X-OmniRoute-Mode: <MODE>" \
  -H "X-OmniRoute-Budget: <REQUEST_BUDGET_USD>" \
  -H "X-OmniRoute-Budget-Fallback: strict" \
  -d '{
    "model": "auto",
    "messages": [
      { "role": "user", "content": "<PROMPT>" }
    ]
  }'

期待結果は、上限内の候補がある場合はその候補で完了し、全候補が上限を超える場合はHTTP 402で即時終了することです。HTTP 402にならず処理が続くなら、ヘッダー名、Auto Comboとしてのモデル指定、保存済み設定の優先順位を確認してください。未知の値は無視される可能性があるため、綴り違いを成功扱いにしてはいけません。

なお、保存済み設定を使う場合は、config.budgetFallbackの値が基準になります。リクエストヘッダーはその要求だけを上書きするため、開発用Agentの一時的な検証と本番の恒久ルールを分けて管理できます。

第三段階：4種類の失敗を意図的に発生させます

設定ファイルを保存しただけでは、予算ルーティングが正しく機能したとは判断できません。少なくとも次の順で、要求、期待結果、失敗処理を記録します。

1. 全候補が予算超過
   strictならHTTP 402で停止することを確認します。Agentが自動再試行する場合は、同じ要求を繰り返さず、人間の承認または別の予算プロファイルへ遷移させます。

2. 第一候補の供給障害
   代替候補へ切り替わり、最終モデルがログに残ることを確認します。高価な候補への無制限回退は許可しません。

3. 資格情報の失効
   無効な接続を候補から除外し、認証エラーをルーティング成功として記録しないことを確認します。

4. レート制限
   HTTP 429などの応答時に回退するか、処理を停止するかをAgentごとに決めます。Token上限も到達時にはHTTP 429になるため、単発予算の402と区別して監視します。Token上限の仕様

ルーティング説明、エラー応答、最終モデル、回退回数、リクエストIDを同じ記録単位で保存すると、後から「安いモデルを選ばなかった理由」まで追跡できます。

第四段階：非本番のAgentを1つだけ接続します

最初から複数のクライアントへ共有すると、予算設定の問題とクライアント側の再試行を分離できません。まずClaude Code、Cursor、または自作のAI Agentから1つを選び、非本番のプロジェクト名と専用キーで接続します。

確認項目は4つです。

• モデル欄がautoまたは保存済みコンボへ正しく変換される。
• ストリーミング応答が途中で切れず、失敗時のエラーがクライアントに返る。
• ツール呼び出し後の再要求にも予算ヘッダーが付く。
• クライアント自身のリトライが、strictの拒否を回避して別経路へ送らない。

特に長時間のコード修正では、1回の要求ではなく、計画、検索、編集、検証が複数回発生します。単発予算だけを見て安全と判断せず、Agentセッション全体のToken使用量とAPIキーの期間上限も併せて確認してください。

第一週は灰度展開と監査を優先します

テストが通った後も、いきなり全メンバーへ配布するのではなく、1クライアント、少数メンバー、限定プロジェクトの順に広げます。監視対象は、実際のタスク費用、失敗率、選択されたモデルの分布、回退回数、strict拒否件数です。

設定変更には、変更者、変更時刻、変更前後の候補、予算方針、承認者を残します。予算超過時に誰が一時解除できるか、解除時間をどう制限するかも決めておくと、障害対応中の無制限な設定緩和を防げます。

Auto Comboは、既定のauto/cheapのような費用重視バリアントも備えていますが、安さだけで候補の健全性やAgent適性まで保証されるわけではありません。Auto Comboのバリアントと選択方式

価格と候補の状態は定期的に再確認します

上流モデルの価格、接続状態、クォータ、資格情報の有効性は変化します。過去に最も安かった候補が、現在も費用面で有利とは限らないため、価格表だけでなく実際のルーティング結果を再検証する必要があります。

運用では、次のタイミングで4種類の失敗試験を再実行します。

• モデルやプロバイダーを追加したとき。
• OmniRouteを更新したとき。
• APIキーやOAuth資格情報を更新したとき。
• Agentのプロンプト、ツール、最大出力長を変更したとき。

公式リリース文書では、Auto Comboの仕様やリクエスト制御が更新されています。実運用では固定したリリース版のSchemaとAPI Referenceを照合し、予算ヘッダー、既定の回退、認証ルールに変更があれば、4種類の受け入れ試験をすべてやり直してください。リリース版のAuto Combo仕様

失敗しにくい構成の判断分岐

• 単発費用を絶対に超えたくない場合は、候補を限定し、strictを選びます。候補不足時はHTTP 402を受けて人間へ戻します。
• 開発中で処理継続を優先する場合は、cheapest回退を使えます。ただし、上限超過を許容する運用だと明記します。
• Agentごとに費用特性が異なる場合は、APIキーまたは保存済みコンボを分離します。1つの共有設定で全員を管理しません。
• 障害時も処理を止められない場合は、価格上限内の代替候補を2つ以上用意し、供給障害と資格情報失効を別々に試験します。
• ログの説明が不足している場合は、全社展開を止め、ルーティング理由と最終モデルを追跡できる状態へ戻します。

FAQ

OmniRoute Auto Comboで予算を超えた場合、リクエストはどうなりますか？

既定のcheapest系フォールバックでは、上限を超える候補しか残らない場合に、全体で最も安い候補へ切り替えて処理を続ける動作が採用されます。ただし、その候補も上限を超える可能性があります。費用を絶対に超えたくない本番Agentでは、strictまたはblock相当の設定を選び、拒否をクライアント側で扱えるようにします。

OmniRouteで予算超過時にリクエストを直接止めるにはどう設定しますか？

リクエスト単位ではX-OmniRoute-Budgetに上限を指定し、X-OmniRoute-Budget-Fallbackへstrictを渡します。保存済みのAuto Comboを使う場合は、設定側のbudgetFallbackをstrictにします。候補がすべて上限を超えた場合はHTTP 402で失敗するため、Agentの再試行設定が同じ要求を繰り返さないかも確認が必要です。

OmniRouteでAgentごとに異なる予算を割り当てる方法はありますか？

Agentごとに別のAPIキー、保存済みコンボ、またはリクエストヘッダーを割り当てる構成が扱いやすい方法です。たとえば開発用Agentには緩やかな上限、コード変更を伴う本番Agentには厳格な上限とstrictを組み合わせます。APIキーのToken上限は、単発の米ドル上限とは別の管理層として分けて記録します。

自動回退で、予算を超える高価なモデルへ切り替わらないようにするには？

まずAuto Comboへ入れる候補をホワイトリスト化し、価格上限を超える候補を最初から除外します。そのうえでbudgetFallbackをstrictにすれば、残った候補がすべて高すぎる場合に処理を止められます。cheapestは費用上限を保証する設定ではなく、安価な候補を探しても上限超過を許す互換動作として扱うべきです。

リクエストがなぜそのモデルへルーティングされたか確認できますか？

ルーティングログと説明情報を保存すれば、候補として評価されたモデル、除外理由、最終的なモデル、回退の有無を追跡できます。確認時は、選択されたモデル名だけで判断せず、予算、資格情報、供給状態、レート制限、ヘルススコアのどれが決定に影響したかを同じリクエストIDで照合します。

現在の構成とMac環境を比較してから常時稼働へ進めます

自宅やオフィスのMacでOmniRouteを動かす構成は、初期費用を抑えやすい一方、電源断、スリープ、回線障害、管理者不在、ポート公開の安全対策が運用上の負担になります。複数の遠隔メンバーが同じAI Agent入口を使うなら、こうした停止要因がルーティング障害や再試行の増加につながります。

まずは非本番Agentで4種類のルーティングシミュレーションを完了し、継続運用が必要になった段階で、常時接続しやすいMacレンタル環境やMacの仮想デスクトップ構成を比較するのが安全です。物理ポートや長期の固定負荷が必要なら自前機が適し、短期検証や遠隔チームで共有するAgent基盤なら、ZilmacのMac環境を試すほうが停止要因を減らしやすい選択肢になります。

• Agentの利用量とモデル別コストを比較するなら、API料金の計算方法を確認
• 定額プランと従量課金の違いを整理し、Agentの予算上限を決める参考に