Claude APIのadvisor toolの最小構成 — executorとadvisorモデルの組み合わせ

Claude APIのadvisor toolとは何か — Claude Codeの/advisorとの違い

advisor toolは、実行を担うexecutorモデルが生成の途中で、より高性能なadvisorモデルへ相談できるMessages APIのツールです。大半のターンは機械的でも、要所の計画の質が結果を左右するタスク(コーディングエージェント、コンピューター操作、複数手順のリサーチなど)に向きます。助言を出すだけのadvisorは最終出力を書かないので、出力の大部分はexecutorの単価で生成されます。

advisorモデルに選べるのは、Sonnet 4.6以上で、executorと同等以上の能力のモデルです。executorがSonnet 5.5なら、助言役はOpus 5・5.5、Fable 5・5.1、Mythos 5・5.1、Sonnet 5.5自身に限られます。全パターンは記事後半の表にあります。

逆に向かないのは、計画することが無い単発のQ&A、利用者が自分でコストと品質を選ぶモデルピッカー、毎ターンadvisor級の能力が要るワークロードです。

この仕組みはClaude Code CLIのadvisor機能と同じ土台です。Claude Codeの公式ドキュメントは、--advisorを「サーバー側のadvisor toolを有効にする」フラグと説明しています。

Claude Code側でモデルを選ぶ入口は3つあります。

• /advisor [model|off]: fable・opus・sonnetか完全なモデルIDを受け付けます。非対話のセッションなどで引数を渡す形式はv2.1.260以降です
• --advisor <model>: そのセッションだけ有効にします(例: claude --advisor opus)
• advisorModel設定キー: 未設定ならadvisorは無効で、/advisorのピッカーで選ぶとこのキーに保存されます

環境変数CLAUDE_CODE_DISABLE_ADVISOR_TOOLでadvisorを切ると、advisorModelでは入れ直せません。自分のアプリケーションやエージェントフレームワークで同じことをするには、Messages APIへadvisorツールを直接渡します。Claude Code内での使い分けはClaude Code advisorの使い分けにまとめています。

最小構成のリクエストを組み立てる

advisor toolの最小構成は、tools配列にtype: "advisor_20260301"のエントリを1つ足すだけです。executorのモデルはトップレベルのmodelフィールド、advisorのモデルはツール定義内のmodelフィールドに分けて指定します。

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: advisor-tool-2026-03-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 4096,
    "tools": [{
      "type": "advisor_20260301",
      "name": "advisor",
      "model": "claude-opus-4-8"
    }],
    "messages": [{
      "role": "user",
      "content": "Goでgracefulシャットダウンつきのワーカープールを実装して"
    }]
  }'

executorであるSonnet 5が、途中でこのadvisorツールを呼ぶかどうかを自分で判断します。呼ぶタイミングを人間が指定する必要はなく、advisorに渡る文脈もサーバーが会話全体から組み立てます。

ツール定義にはmodelのほかに任意パラメータが3つあります。

advisorには、executorと同等以上の能力のモデルを指定します。組み合わせのルールは後述の対応表のとおりです。cache_control・allowed_callers・defer_loading・strictといった、どのツール定義にも付けられる共通プロパティも使えます。

advisor_tool_resultの中身をどう読むか — 2つの結果形式

advisorの助言はadvisor_tool_resultブロックのcontentに入りますが、advisorに指定したモデルによって中身の形式が変わります。この違いを知らずに実装すると、advisorのモデルを切り替えた途端にパースが壊れます。

max_tokensをツール定義に付けたときは、どちらの形式にもstop_reasonが入ります。付けなければこのフィールドはありません。

暗号化されたencrypted_contentは、次のターンでサーバーが復号してexecutorのプロンプトへ差し込みます。クライアントに読めなくても、executor自身は助言の中身を踏まえて動きます。どちらの形式でも、後続ターンへの送り返し方は次の節のとおりです。

画面に助言テキストを出したいなら、平文を返すadvisorを選びます。ただしSonnet 5.5・Fable 5.1・Mythos 5.1・Opus 5.5・Opus 5・Fable 5・Mythos 5をexecutorにすると、組めるadvisorは暗号化側だけです。この組み合わせでは助言の本文をレスポンスから読めません。

advisorを会話の途中で切り替えるなら、content.typeで分岐して両方の形に備えます。

2ターン目以降でadvisor_tool_resultをどう引き回すか

会話が複数ターンにまたがる場合、advisor_tool_resultブロックを含むassistantメッセージ全体を、そのまま次のリクエストのmessagesに積んで送り返します。暗号化されたadvisor_redacted_resultが入っていても、書き換えずに送り直せば、サーバー側で復号してexecutorのプロンプトへ差し込みます。この履歴保持のしくみはどのadvisorモデルでも同じです。

途中の会話でadvisorをツール定義から外すこともできます。tools配列からadvisorエントリを削除しても、履歴に残ったadvisor_tool_resultブロックはそのまま送って構いません。リクエストは受理され、履歴は保持されますが、そのターンではadvisorを新たに呼べません。過去ブロックが履歴に含まれる限り、anthropic-beta: advisor-tool-2026-03-01ヘッダーは送り続けます。

pause_turnで止まったとき

advisorの呼び出しが完了する前にターンが打ち切られることもあります。stop_reasonがpause_turnで、server_tool_useブロックに対応するadvisor_tool_resultがまだ無いなら、呼び出しは保留中です。

resumeリクエストからadvisorツールを外すと、保留中のserver_tool_useに対応するツール定義が無いため400 invalid_request_errorになります。一方、executorが同じターンで自前のツールも呼んでいた場合はstop_reasonがtool_useになります。このときは通常どおりtool_resultを送れば、次のリクエストの冒頭で保留中のadvisor呼び出しが処理されます。

ストリーミングでは待ちが一度に出る

advisorの推論自体はストリームされません。server_tool_useブロックが閉じた時点(content_block_stop)でexecutorのストリームが止まり、advisorが終わるまで静かになります。待ちの間に流れるのは、約30秒おきのSSE pingだけです。短い呼び出しならpingすら出ないことがあります。

終わるとadvisor_tool_resultが1回のcontent_block_startイベントで丸ごと届き(deltaは無し)、その後でexecutorの出力が再開します。最後のmessage_deltaに、advisorのトークン数を含むusage.iterationsが載ります。UIに「考え中」の表示を出すなら、server_tool_useの終了をきっかけにする形が考えられます。

エラーコードと失敗時の挙動

advisorの呼び出しが失敗しても、リクエスト全体は失敗しません。advisor_tool_resultのcontentがadvisor_tool_result_error型になり、executorはそのエラーを見て助言なしで続行します。

advisorのレート制限は、そのモデルへの直接呼び出しと同じ枠を消費します。advisor側のレート制限はtoo_many_requestsとしてツール結果の中に現れますが、executor側がレート制限を受けた場合はツール結果ではなくHTTP 429でリクエスト全体が失敗する点が異なります(Claude APIのエラーコード全般の分類とリトライ設計はClaude APIのエラーハンドリング設計を参照してください)。

Priority Tierも、モデルごとに別々に効きます。executorにPriority Tierの契約があっても、advisorには及びません。advisorがPriority Tierで動くのは、advisorモデル側にも契約があるときだけです。

executorとadvisorの組み合わせ表

advisorはSonnet 4.6以上で、かつexecutorと同等以上の能力でなければなりません。同格のモデル同士(例えばOpus 4.7とOpus 4.8)は相互にadvisorになれます。

無効な組み合わせを指定すると、リクエストは400 invalid_request_errorで拒否されます。実行時エラーではなくリクエスト時点で弾かれるため、モデルIDのタイプミスもここで検出できます。advisor toolはClaude APIとClaude Platform on AWSで使え、Amazon Bedrock・Google Cloud・Microsoft Foundryでは使えません。

使い始めの構成を決める

advisorの効き方は、今どのモデルを使っているかで変わります。

• Sonnetで複雑なタスクを回している場合: 上位のadvisorを足します。Opusなら総コストは同程度かそれ以下で、Fable 5.1なら品質の伸びが最大になります
• Haikuを使っていて知能を一段上げたい場合: OpusかFableのadvisorを足します。Haiku単独より高くなる一方、executorを大きなモデルに替えるよりは安く収まります

効果はタスク次第なので、自分のワークロードで測ることが前提です。executorの能力がadvisorに近づくほど、得られる差は小さくなります。

コーディングやエージェント作業では、呼ぶタイミングが成果を左右します。advisorが総ツール呼び出し数と会話の長さを減らすと、同程度のコストでより高い知能が出ます。効くのは2つのタイミングです。

1. 数回の探索的な読み取りがトランスクリプトに入った後の、早い最初の呼び出し
2. 難しいタスクでの、ファイル書き込みとテスト出力が入った後の最後の呼び出し

システムプロンプトで誘導しないと、特にコーディングではexecutorがadvisorを呼び控える傾向があります。タスクあたり2〜3回の安定した呼び出しを狙うなら、公式ドキュメントにあるコーディング向けの推奨プロンプトをexecutorのシステムプロンプトの先頭に置く方法があります。todoリストのような計画系ツールを併設しているときは、それらより先にadvisorを呼ぶよう書き添えると、助言がそちらへ流れ込みます。

呼び控えの対策には、会話途中の追い促しもあります。Haiku executorが最初のターンでadvisorを呼ばなかったとき、2回目のassistantターンの前に短いリマインダーをユーザーメッセージとして足します。Anthropicの内部評価では、Haikuでタスク通過率が約7ポイント上がりました。Sonnetでは測定できる効果がなく、Opusでは通過率がわずかに下がったため、Opusには使いません。

effortとの組み合わせでは、コーディングタスクで「Sonnet executor(medium effort)+ Opus advisor」が、既定のeffortのSonnet単独と同程度の知能をより低いコストで出します。最大の知能を取りたいときは、executorを既定のeffortのままにします。

コストの目安とmax_tokensで抑える方法

advisorの呼び出しは、executorとは別料金のサブ推論として課金されます。公式の例では、1回のリクエストがusage.iterationsに3つの区間として記録されます。

"iterations": [
  { "type": "message", "input_tokens": 412, "output_tokens": 89 },
  { "type": "advisor_message", "model": "claude-opus-5",
    "input_tokens": 823, "output_tokens": 1612 },
  { "type": "message", "input_tokens": 1348,
    "cache_read_input_tokens": 412, "output_tokens": 442 }
]

advisor_messageの分はadvisorのモデル料金、messageの分はexecutorのモデル料金で課金されます。トップレベルのusageにはexecutorの分だけが入り、advisorの分は合算されません。さらにトップレベルの各フィールドは全executor区間の合計なので、毎回会話を送り直す分だけinput_tokensは1回のプロンプトより大きく見えます。コストの集計はusage.iterationsを区間ごとに足し上げて行います。

トップレベルのmax_tokensはexecutorの出力にだけ効き、advisorのサブ推論は制限しません。advisorのトークンは、executorに適用したタスクバジェットからも引かれません。advisorを絞るには、ツール定義のmax_tokensを使います。

2048を起点にするのが公式の推奨です。上限に達したかどうかは結果ブロックのstop_reasonが"max_tokens"になるので分かります。助言テキストの末尾にも[Advisor output truncated at max_tokens=2048.](上限値が入ります)が付き、平文を返すadvisorならクライアントからも見えます。各advisor_messageのoutput_tokensで上限までの余裕も測れます。ハードな上限なので、コストやレイテンシの保証が要るときに向きます。簡潔さへ誘導したいだけなら、プロンプトで頼む方法を併用するか、そちらだけにします。サーバーは残りトークンの予算もadvisorへ渡すため、advisorは上限に収まるよう応答を作ります。

キャッシュは呼び出しが3回以上のときだけ

cachingは最小構成では省略してかまいません。advisorのN回目のプロンプトは、N-1回目に1区間足したものなので、先頭が安定しています。有効にすると2回目以降のadvisor_messageでcache_read_input_tokensが0以外になります。

ただしキャッシュの書き込みは、2回以下の呼び出しでは読み取りで浮く分を上回ります。損益分岐は3回前後で、長いエージェントループ向けです。会話の途中で切り替えるとそのたびにキャッシュミスになるため、cachingは会話の最初に決めて変えません。

executor側のキャッシュは別の層です。advisor_tool_resultは他のブロックと同じようにキャッシュでき、後続ターンでその直後にcache_controlの境界を置けば当たります。executorのプロンプトには、クライアントが平文と暗号化のどちらで受け取ったかにかかわらず平文の助言が入るので、キャッシュの挙動は2つの結果形式で変わりません。

他のAPI機能との組み合わせでは、3点に注意します。トークンカウントはexecutorの最初の区間の入力トークンだけを返すので、advisor側の見積りはadvisorのモデルを指定してcount_tokensを呼びます。バッチ処理は使えます。clear_tool_usesはadvisorのブロックと完全には互換でないため、併用するときは挙動を確かめてから使います。

会話単位の予算は自前で数える

会話単位で呼び出し回数に予算を設けたい場合、max_usesは1リクエスト内の上限にしかならないので、クライアント側で数えます。上限に達したら次のリクエストからtools配列にadvisorエントリを含めないだけです。

advisor_tool = {
    "type": "advisor_20260301",
    "name": "advisor",
    "model": "claude-opus-5",
    "max_tokens": 2048,
}
 
tools = my_tools + ([advisor_tool] if advisor_calls < 5 else [])

過去のターンに残ったadvisor_tool_resultブロックを会話履歴から削る必要はありません。advisorは他のサーバー側ツールやクライアント側ツールと同じtools配列に並べて使えます。

Claude Managed Agentsでは設定の形が違う

Claude Managed Agentsのセッションでもadvisorを使えますが、ツール定義では書きません。エージェントのmultiagent roster(構成員の一覧)に{"type": "advisor", "model": ...}のエントリを足し、セッションの主スレッドが途中でそのモデルへ相談します。

このエントリにはmax_uses・max_tokens・cachingのオプションがなく、助言はadvisor_tool_resultブロックではなく、セッションのイベントストリーム上のスレッドイベントとして届きます。Messages API向けのパース処理を、そのまま持ち込めない点に注意が要ります。

まとめ

最小構成は、tools配列にadvisorのエントリを1つ足すだけで動きます。実装で崩れやすいのは、advisorモデルで平文と暗号化が分かれる結果の形式と、executorごとに決まる組み合わせの2点です。コストはusage.iterationsでexecutorと別建てに数え、max_tokensで絞り、キャッシュは呼び出しが3回以上見込めるときだけ検討します。