LLMゲートウェイの設定ファイルに「このモデルはthinkingが使える」「このモデルはPDFを受けられる」と手書きしていると、新モデルの追加や退役のたびに設定が実態からずれる。ずれた設定は本番で400エラーとして表面化する。
Claude Models APIは、モデルごとの対応機能と提供状態を機械可読な形で返す。複数チームが共有するプラットフォームでは、この情報を設定の正本にする設計が有効だ。ルーティング全体の考え方はLLMゲートウェイのルーティング設計を参照してほしい。
Models APIのcapabilitiesは何を返すのか
GET /v1/modelsとGET /v1/models/{model_id}は、モデルごとにcapabilitiesとlifecycleを返す。キーは既知の機能すべてについて常に存在する。
capabilitiesには、batch・citations・image_input・pdf_input・structured_outputs・effort・thinking・context_management・server_toolsなどが並び、各項目はsupportedの真偽値を持つ。effortはlowからmaxまでのレベル別に、thinking.typesはadaptive・enabled・disabled・between_toolsの4種別ごとに対応可否を返す。context_managementにはcompact_20260112などの戦略別フラグがある。
モデル本体のメタ情報として、max_input_tokens、max_tokens、line(haiku・sonnet・opus・fable・mythos)も取得できる。lineがnullのモデルもあり、公式ドキュメントはIDから系列を推測しないよう求めている。
lifecycleとretires_atはどう扱うべきか
lifecycleはactive・deprecated・retiredの3値で、退役の判定に使えるのはlifecycleだけだ。retires_atは予定日で、改定されうる。
deprecatedのモデルは既存の利用組織には呼び出せるが、新規採用は閉じられている。retires_atの日付が過ぎてもlifecycleがdeprecatedのままなら、それは退役の遅延を意味し、退役済みではない。一覧の既定ではactiveとdeprecatedだけが返り、retiredはlifecycleパラメータで明示的に要求したときだけ現れる。
運用上の判断材料は次の3点に絞れる。
lifecycle: deprecatedを検知したら、ルーティング候補から外す前に警告をチームへ通知するretires_atまでの残日数を、移行計画のチケット期限に紐づける- 退役判定そのものは
retires_atの日付ではなくlifecycleの値で行う
退役ポリシーの全体像はモデル非推奨化の移行計画に整理してある。
ルーティングにcapabilitiesをどう組み込むか
要求機能のセットを宣言し、
capabilitiesと突き合わせて候補モデルを絞る。これでモデルID直書きの条件分岐が消える。
設計の核は、リクエスト側が必要な機能を宣言し、ゲートウェイが候補モデルをフィルタすることだ。
- 画像添付があるリクエストは
image_input.supportedが真のモデルだけを残す - 厳密なスキーマ出力が必要な呼び出しは
structured_outputs.supportedで絞る between_toolsのthinking種別を使うエージェント経路はthinking.types.between_tools.supportedで判定する。この種別はthinkingを無効にしたうえで、ツール呼び出しの合間に書かれる短い進捗を返す仕組みで、非対応モデルに送ると400になる- 長大な入力は
max_input_tokens、出力量はmax_tokensの上限で候補を切る
between_toolsの移行詳細はbetween_toolsへの移行設計に、effortをメッセージ単位で切り替える設計はper-message effortのルーティング設計にある。
運用で何に注意すべきか
capabilitiesは「モデルの能力」であり、組織で許可された利用可否ではない。ポリシーや組織設定による拒否は別途ありうる。
公式ドキュメントには、2つの前提が明記されている。1つ目は、server_toolsが対応でも、管理者がWeb検索を無効にしていれば組織としては拒否される点だ。2つ目は、between_toolsが対応でも、thinkingを切った状態では許されないeffortレベルなど、別の理由でリクエストが拒否される点だ。したがってcapabilitiesは「送ってよい候補」を絞る一次フィルタに過ぎず、実行時のエラーハンドリングとフォールバックは残す必要がある。
実装上のポイントは次のとおりだ。
- 起動時と一定間隔でModels APIを取得し、ゲートウェイ内のカタログを更新する
- 複数Workspaceを扱う認証情報では
anthropic-workspace-idヘッダーで対象を明示する - 取得失敗時は直近のカタログを保持し、取得失敗をアラート対象にする
- カタログの差分(機能の追加・
lifecycleの変化)を変更履歴として監査ログに残す
規模別の留意点(SMB / エンタープライズ)
数十チームがモデルを共有する環境では、カタログ取得をゲートウェイに一元化し、各チームの設定にはモデルIDではなく「必要機能」と「系列(line)」だけを書かせる。これにより、モデル追加や退役の影響が個別アプリの改修を要さなくなる。組織横断のモデル統制はKuuの大企業向けAI変革プログラム(RDE)で設計から支援している。
参考
まとめ
Models APIのcapabilitiesとlifecycleを設定の正本にすると、モデルの追加・退役に追随する作業をカタログ更新に集約できる。ただし組織設定による拒否は別に起こるため、実行時のフォールバックは残す。まずはゲートウェイで取得と差分監査を始めるのが現実的な一歩だ。ルーティング統制の設計はKuu株式会社のRDEにご相談ください。
