モデルの自動選択
モデルに "auto" を指定すると、Gateway がタスクの難しさを判断し、ワークスペースで許可されたモデルを選びます。指定したモデルが差し替えられることはなく、どの応答にも応答したモデルが示されます。
モデルを指定するか auto を使う#
model フィールドには、GET /v1/models のモデル名か auto を指定します。
model | 動作 |
|---|---|
auto | Gateway がタスクの難しさに応じて、ワークスペースで許可されたモデルを選びます。 |
auto:cost | auto と同じく選び、どのタスクも 1 段階安いモデルを使います。下記を参照。 |
auto:quality | auto と同じく選び、どのタスクも 1 段階強いモデルを使います。下記を参照。 |
| モデル名 | そのモデルだけが応答します。他のモデルに差し替えられることはありません。 |
agentlab/… | 400 invalid_model で拒否されます。メッセージに有効な値が一覧されます。 |
| Gateway が知らない名前 | 404 model_not_found で拒否されます。メッセージに有効な値が一覧されます。 |
| ワークスペースで除外されているモデル | 403 model_not_enabled で拒否されます。 |
/v1/chat/completions と /v1/responses は、どの会社のモデルかを問わず、許可されたすべてのモデルから選びます。/v1/messages は Claude のモデルだけを使い、OpenAI のモデルにしか処理できない Responses リクエスト(code_interpreter ツールを含むものなど)は OpenAI のモデルだけを使います。
Claude Code と Codex は送信前にモデル名を確認するため、auto を送れません。リクエストには実在するモデル名を入れたまま、ヘッダー X-AgentLab-Routing: auto を付けると、Gateway がモデルを選びます。ヘッダーには X-AgentLab-Routing: auto:cost のように優先設定も指定でき、本文の指定より優先されます。値は auto、auto:cost、auto:balanced、auto:quality のいずれかで、1 回だけ送る必要があります。それ以外は 400 で拒否されます。
auto の選び方#
- タスクを判断 構造化出力を返せる、許可されている最も安価なモデルが、リクエストの短い抜粋(システムプロンプトの冒頭、最初と最新のユーザーメッセージ、ツール名。最大 8 KiB で、会話全体は読みません)を読み、タスクの種類と、複数のステップが必要かを判断します。
- モデルを選択 複数ステップの作業には、より強力なモデルを使います。定型的な分析、コーディング、計画には標準のモデルを使います。定型的な抽出、書き換え、会話には、許可されている最も安価なモデルを使います。
- 1 回のやり取りをそろえる 同じツールループの後続ステップは最初のステップのモデルを使い続けるので、暗号化された推論、thinking の署名、プロンプトキャッシュが有効なまま保たれます。
判断が失敗した場合、タイムアウトした場合(6 秒後)、または確信が持てない場合は、標準のモデルが応答します。判断できないときに auto がより安価なモデルを選ぶことはありません。
ワークスペースの月間支出上限の残りが 20% を切ると、複数ステップと判断された作業にも、より強力なモデルではなく標準のモデルを使います。
判断はそれ自体が 1 回のモデル呼び出しです。同じキーで記録・課金され、対象のリクエストにひも付けられます。
auto がコストと品質のどちらを優先するか選ぶ#
auto はコストと品質のバランスを取ります。どちらかに寄せるには、model(または X-AgentLab-Routing)に優先設定を指定します:auto:cost または auto:quality。auto:balanced は auto と同じです。GET /v1/models は auto、auto:cost、auto:quality を一覧するので、クライアントのモデル選択画面から選べます。
どの優先設定でも、まず同じ方法でタスクを判断します。判断がモデルを決め、優先設定はそれを 1 段階だけ動かします。最も安いモデルより下、最も強いモデルより上には動きません:
| タスクの判断 | auto:cost | auto | auto:quality |
|---|---|---|---|
| 定型的な抽出、書き換え、会話 | 最も安価 | 最も安価 | 標準 |
| 定型的な分析、コーディング、計画 | 最も安価 | 標準 | より強力 |
| 複数ステップ | 標準 | より強力 | より強力 |
| 判断なし(失敗、タイムアウト、不確か) | 標準 | 標準 | 標準 |
auto:costはより強力なモデルを使いません。auto:qualityは最も安価なモデルを使いません。- 月間の支出上限の残りが 20% 未満のときは、
auto:qualityもより強力なモデルではなく標準のモデルを使います。 - 1 回のやり取りは、その優先設定で選ばれたモデルを使い続けます。同じやり取りを別の優先設定で送ると、もう一度判断します。
/v1/messagesは引き続き Claude のモデルだけを使い、provider.onlyとワークスペースのモデル設定も適用されます。modelsのフォールバック一覧に入れられるのはauto(auto:balancedを含む)だけです。auto:costやauto:qualityは 400 で拒否されます。auto:の後にそれ以外の値(auto:fastなど)を指定すると、400invalid_modelで拒否されます。メッセージに有効な値が一覧されます。
一部のプロバイダーだけを使う#
リクエストを特定の会社のモデルだけに限定するには、Chat Completions または Responses に OpenRouter と同じ形式で provider.only を指定します。
{
"model": "auto",
"provider": { "only": ["anthropic"] },
"messages": [{ "role": "user", "content": "Hello" }]
}- プロバイダーとは、コンソールのモデル一覧に表示されるとおり、モデルを作っている会社です:
anthropic、openai、google、meta、xai、deepseek、moonshot、mistral、zhipu、qwen、minimax、amazon、microsoft、cohere、black-forest-labs。anthropicには Amazon Bedrock と Google Vertex AI 上の Claude も含まれます。 - auto、その判断、再試行、
modelsのauto項目は、これらのプロバイダーのモデルだけを使います。ワークスペースのモデル設定も引き続き適用されます。 - 一覧にないモデルの指定、不明なプロバイダー、
providerのその他のオプションは、400 で拒否され、paramはprovider.only(またはそのオプション名)です。一覧のプロバイダーのどのモデルもリクエストを処理できない場合も 400 で拒否され、メッセージに処理できるプロバイダーが示されます。 providerは Gateway だけが読み取り、モデルには送られません。
auto が選んだモデルを確認する#
応答したリクエストには、次のヘッダーが付きます。
| ヘッダー | 値 |
|---|---|
X-Agentlab-Model | 応答したモデル。 |
X-Agentlab-Decision | 理由:モデルを指定した場合は requested_model、auto の場合は auto_assessed、auto_reused、auto_uncertain、auto_assessment_failed、auto_assessment_timeout、auto_budget_guard のいずれか。 |
X-Agentlab-Assessment | auto の場合の判断結果(analysis/multi_step など)。判断がなかった場合は unavailable。 |
X-Request-Id | リクエストの ID。使用量のページやエクスポートに表示されるものと同じです。 |
Chat Completions では、応答したモデルが model に、理由が agentlab_decision.reason(auto または requested_model)にも返されます。