約 3 分で読めます

Models APIのcapabilitiesで機能検出ルーティング

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点に絞れる。

  1. lifecycle: deprecatedを検知したら、ルーティング候補から外す前に警告をチームへ通知する
  2. retires_atまでの残日数を、移行計画のチケット期限に紐づける
  3. 退役判定そのものは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にご相談ください。

関連記事

Claudeモデルの非推奨化、移行計画はどう立てるかClaudeの並列ツール呼び出し、結果の返し方と実行設計Sonnet 5.5のbetween_tools移行ガイドClaude Opus 5.5移行の破壊的変更とチェックリスト