Claude APIのadvisor toolを実装する最小構成 — executor/advisorモデルペア
Messages APIのadvisor toolは、実行役のexecutorモデルが要所で上位モデルadvisorへ相談する仕組みです。最小構成のリクエストと結果の読み方をまとめます。
Claude APIのadvisor toolとは何か — Claude Codeの/advisorとの違い
advisor toolは、実行を担うexecutorモデルが生成の途中で、より高性能なadvisorモデルへ相談できるMessages APIのツールです。executorがadvisorを呼ぶと、Anthropicのサーバー側でadvisorモデルへの別推論が走り、会話全体の文脈を読んだ助言がexecutorに返り、executorはその助言を踏まえて生成を続けます。コーディングエージェントやリサーチパイプラインのように「大半のターンは機械的だが、要所の計画品質が結果を左右する」タスクに向きます。
この仕組み自体は、Claude Code CLIのadvisor機能と地続きです。Claude Codeのadvisorはメインで使うモデルとは別のモデルに要所だけ相談させる機能で、内部的にはこのMessages APIのadvisor toolと同じ発想を使っています。ただしClaude Code側は設定ファイルでモデルペアを選ぶだけで、tools配列にツール定義を書くAPI操作は開発者に見えません。自分のアプリケーションやエージェントフレームワークにこの仕組みを直接組み込みたい場合は、Claude Code経由ではなく本記事のようにMessages APIへ直接advisorツールを渡す必要があります。Claude Code内でのadvisorとPlanモード・code-reviewの使い分けは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ツールを呼ぶかどうかを自分で判断します。呼ぶタイミングを人間が指定する必要はありません。server_tool_useブロックのinputは常に空オブジェクトです。advisorに渡す文脈はサーバーがexecutorの会話全体(システムプロンプト・ツール定義・それまでのやり取り)から自動的に組み立てるため、inputに何かを書いてもadvisor側には届きません。
ツール定義にはmodelのほかに任意パラメータが3つあります。
| パラメータ | 役割 |
|---|---|
max_uses | 役割1リクエストあたりのadvisor呼び出し回数の上限。超えるとmax_uses_exceededエラーになり、executorは助言なしで続行する |
max_tokens | 役割advisorの出力(thinking込み)の上限。最小値は1024 |
caching | 役割advisor側のプロンプトキャッシュを{"type": "ephemeral", "ttl": "5m"}のように有効化する。既定は無効(プロンプトキャッシュ自体の仕組みはAnthropic APIのPrompt Cachingを理解するを参照) |
advisorモデルにはclaude-opus-4-8のように、executorより十分強いモデルを指定します。組み合わせのルールは後述の対応表のとおりです。
cachingは最小構成では省略してかまいません。有効化する価値が出るのは、1つの会話でadvisorを3回以上呼ぶときだけです。会話が進むほどadvisorへ渡す文脈(それまでの全ターン)が伸びるため、2回以下の呼び出しではキャッシュの書き込みコストが読み取りで節約できる分を上回ります。有効化する価値があるのは長いエージェントループで、会話の途中で切り替えるとそのたびにキャッシュミスが発生します。
advisor_tool_resultの中身をどう読むか — 2つの結果形式
advisorの助言はadvisor_tool_resultブロックのcontentに入りますが、advisorに指定したモデルによって中身の形式が変わります。この違いを知らずに実装すると、advisorのモデルを切り替えた途端にパースが壊れます。
advisor_result:textフィールドに平文の助言が入る。claude-opus-4-8をadvisorにした場合はこちらadvisor_redacted_result:encrypted_contentフィールドに暗号化されたブロブが入る。クライアント側では読めない。claude-opus-5・claude-fable-5・claude-fable-5.1・claude-mythos-5・claude-mythos-5.1をadvisorにした場合はこちら
暗号化されたencrypted_contentは、次のターンでサーバーが復号してexecutorのプロンプトへ差し込みます。つまりクライアントに読めなくても、executor自身は助言の中身を踏まえて動作します。どちらの形式でも、後続ターンへはブロックの中身をそのまま(改変せず)round-tripさせる必要があります。advisorの助言テキストを画面に表示したい場合は、平文を返すclaude-opus-4-8のようなモデルをadvisorに選ぶ必要があります。
2ターン目以降でadvisor_tool_resultをどう引き回すか
会話が複数ターンにまたがる場合、advisor_tool_resultブロックを含むassistantメッセージ全体を、そのまま次のリクエストのmessagesに積んで送り返します。opus-5系のadvisorで暗号化されたadvisor_redacted_resultが入っていても、内容を書き換えずに送り直せば、サーバー側で復号してexecutorのプロンプトへ差し込みます。この履歴保持のしくみはどのadvisorモデルでも同じです。
途中の会話でadvisorをツール定義から外すことも可能です。tools配列からadvisorエントリを削除しても、履歴に残ったadvisor_tool_resultブロックはそのまま送って構いません。リクエストは受理され、その履歴は保持されますが、そのターンではadvisorを新たに呼び出せなくなります。ただし過去ブロックが履歴に含まれる限り、anthropic-beta: advisor-tool-2026-03-01ヘッダーは送り続ける必要があります。
advisorの呼び出しが完了する前にターンが打ち切られることもあります。stop_reasonがpause_turnで終わり、server_tool_useブロックに対応するadvisor_tool_resultがまだ無い場合は、advisorの呼び出しが保留中です。この場合、そのassistantメッセージを内容を変えずにmessagesへ追加し、advisorツール定義とベータヘッダーを含めて同じリクエストを送り直せば、保留中のadvisor呼び出しが実行されてexecutorのターンが続きます。ユーザーメッセージやtool_resultを新たに足す必要はありません。再開後のターンが再びpause_turnで終わることもあり、その場合は同じ手順を繰り返します。resumeリクエストでadvisorツールを外すと、保留中のserver_tool_useブロックに対応するツール定義が無いため400 invalid_request_errorになります。一方、executorが同じターンで自前のツールも呼んでいた場合はstop_reasonがtool_useになり、通常どおりtool_resultを送ると、次のリクエストの冒頭で保留中のadvisor呼び出しが処理されます。
エラーコードと失敗時の挙動
advisorの呼び出しが失敗しても、リクエスト全体は失敗しません。advisor_tool_resultのcontentがadvisor_tool_result_error型になり、executorはそのエラーを見て助言なしで続行します。
| エラーコード | 意味 |
|---|---|
max_uses_exceeded | 意味ツール定義のmax_uses上限に到達した |
too_many_requests | 意味advisor側のサブ推論がレート制限に達した |
overloaded | 意味advisor側のサブ推論が容量上限に達した |
prompt_too_long | 意味会話全体がadvisorモデルのコンテキストウィンドウを超えた |
execution_time_exceeded | 意味advisor側のサブ推論がタイムアウトした |
model_not_found | 意味指定したadvisorモデルが存在しない |
unavailable | 意味上記以外のadvisor側の失敗全般 |
advisorのレート制限は、そのモデルへの直接呼び出しと同じ枠を消費します。advisor側のレート制限はtoo_many_requestsとしてツール結果の中に現れますが、executor側がレート制限を受けた場合はツール結果ではなくHTTP 429でリクエスト全体が失敗する点が異なります(Claude APIのエラーコード全般の分類とリトライ設計はClaude APIのエラーハンドリング設計を参照してください)。
executorとadvisorの組み合わせ表
advisorに指定できるモデルには制約があります。advisorはSonnet 4.6以上の性能を持ち、かつexecutorと同等以上の性能でなければなりません。同格のモデル同士(例えばOpus 4.7とOpus 4.8)は相互にadvisorになれます。
| executorモデル | advisorに選べる代表的な範囲 |
|---|---|
| Haiku 4.5 | advisorに選べる代表的な範囲Sonnet 4.6以上ならほぼ全モデル |
| Sonnet 5 | advisorに選べる代表的な範囲Opus 4.7以上、またはSonnet 5自身 |
| Opus 4.8 | advisorに選べる代表的な範囲Opus 4.7/4.8、Fable 5、Mythos 5、Opus 5 |
| Opus 5 | advisorに選べる代表的な範囲Fable 5.1、Mythos 5.1、Fable 5、Mythos 5、Opus 5自身のみ |
| Fable 5.1 / Mythos 5.1 | advisorに選べる代表的な範囲Fable 5.1・Mythos 5.1のみ |
無効な組み合わせを指定すると、リクエストは400 invalid_request_errorで拒否されます。実行時エラーではなくリクエスト時点で弾かれるため、モデルIDのタイプミスもここで検出できます。advisor toolはClaude APIとClaude Platform on AWSで使え、Amazon Bedrock・Google Cloud・Microsoft Foundryでは使えません。
コストの目安とmax_tokensで抑える方法
advisorの呼び出しは、executorとは別料金のサブ推論として課金されます。レスポンスのusage.iterations配列に、type: "message"(executor)とtype: "advisor_message"(advisor)が別々に記録され、advisor分はexecutorのモデル料金には合算されません。advisorの出力は典型的にthinking込みで1,400〜1,800トークン程度ですが、難しいタスクではこれより大きく伸びることがあります。
コストを抑える主な手段は、ツール定義にmax_tokensを設定してadvisorの出力上限を切ることです。Anthropicの計測では、上限を2048に設定すると未設定時と比べて出力トークンが平均で約7分の1に減り、切り詰めが発生した割合はほぼ0%でした。最小値の1024まで下げるとさらに縮みますが、約10%の呼び出しで出力が途中で切られたとの報告もあります。切り詰めが起きると結果ブロックのstop_reasonが"max_tokens"になるため、これを見て上限を緩めるかどうかを判断できます。
会話単位で呼び出し回数に予算を設けたい場合、クライアント側でadvisor呼び出しの回数を数え、上限に達したら次のリクエストからtools配列にadvisorエントリを含めない、という運用がシンプルです。過去のターンに残ったadvisor_tool_resultブロックを会話履歴から削る必要はありません。
まとめ
advisor toolは、tools配列にtype: "advisor_20260301"とadvisorのmodelを1エントリ足すだけで最小構成が動きます。ただし結果の形式がadvisorモデル次第で平文/暗号化に分かれる点、executorとadvisorの組み合わせに制約がある点、コストが別建てで加算される点は導入前に押さえておく必要があります。Claude Code上のadvisor機能を既に使っている場合でも、自分のエージェントに同じ仕組みを組み込むにはこのMessages API側の実装が別途必要です。