Claude の advisor tool 入門 - 速いexecutorモデルに賢いadvisorモデルの助言を挟むツール使用パターン

「賢いモデルは高いが質が高い、速いモデルは安いが判断を誤ることがある」——この二択に、Anthropic が新しい答えを出しました。advisor tool（アドバイザーツール）です。速くて安いexecutor（実行）モデルが、生成の途中で賢いadvisor（助言）モデルに相談し、要所だけ上位モデルの判断を借りる、というツール使用のパターンです。本記事では、Anthropic 公式ドキュメントを一次ソースに、仕組み・使い方・コスト・落とし穴を整理します。

advisor tool とは

advisor tool は、安価な executor モデルに、上位の advisor モデルの「戦略的な助言」を途中で挟み込む仕組みです。流れはこうです。

1. executor が「ここは相談すべき」と判断した時点で advisor を呼ぶ
2. Anthropic のサーバー側で、advisor モデルが会話の全文（システムプロンプト・ツール定義・これまでのやり取り・生成途中のテキスト）を読み、計画や軌道修正を返す
3. executor はその助言を受けて、続きの生成を進める

ポイントは、これがすべて 1 回の /v1/messages リクエスト内で完結することです。あなたの側で追加のラウンドトリップは不要で、web_search などと同じサーバーツールとして動きます。

狙いはコスト対効果です。トークン生成の大半は安い executor が担い、計画が重要な数箇所だけ advisor が助言するため、「advisor 単体に近い品質」を「executor 単体に近いコスト」で得ることを目指します。コーディングエージェント、コンピュータ操作、多段のリサーチパイプラインのような長工程のエージェント処理——大半の手順は機械的だが、良い計画が効いてくる——に向いた設計です。

いつ使うか、いつ使わないか

公式が挙げる典型的な組み合わせは次の 2 つです。

• いま複雑なタスクで Sonnet を使っている: advisor に Opus を足すと、同等かそれ以下の総コストで品質が上がる
• いま Haiku を使っていて知能を一段上げたい: advisor に Opus を足す。Haiku 単体より高くつくが、executor 自体を大きいモデルに替えるより安い

逆に向かないケースも明記されています。

• 単発の Q&A（計画する余地がない）
• ユーザー自身がコストと品質を選ぶパススルー型のモデル選択
• 毎ターンが本当に advisor 級の能力を要するワークロード

効果はタスク依存です。公式も「自分のワークロードで評価せよ」と繰り返しています。

最小の使い方

beta ヘッダを付け、tools 配列に advisor ツールを 1 つ足すだけです。executor は最上位の model、advisor はツール定義内の model で指定します。

curl https://api.anthropic.com/v1/messages \
  --header "x-api-key: $ANTHROPIC_API_KEY" \
  --header "anthropic-version: 2023-06-01" \
  --header "anthropic-beta: advisor-tool-2026-03-01" \
  --header "content-type: application/json" \
  --data '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 4096,
    "tools": [
      { "type": "advisor_20260301", "name": "advisor", "model": "claude-opus-4-8" }
    ],
    "messages": [
      { "role": "user", "content": "Go で graceful shutdown 付きの並行ワーカープールを作って。" }
    ]
  }'

ツール定義の必須・任意パラメータは次のとおりです。

動作の仕組み

executor が advisor を呼ぶと、アシスタントの content に次の 2 ブロックが現れます。

1. server_tool_use（name: "advisor"、input は常に空）。executor は「呼ぶタイミング」だけを示し、文脈はサーバーが供給します
2. advisor_tool_result（advisor の助言）

{
  "type": "server_tool_use",
  "id": "srvtoolu_abc123",
  "name": "advisor",
  "input": {}
},
{
  "type": "advisor_tool_result",
  "tool_use_id": "srvtoolu_abc123",
  "content": {
    "type": "advisor_result",
    "text": "channel ベースの協調パターンを使うとよい。難所はシャットダウン時の in-flight..."
  }
}

advisor はツールなし・コンテキスト管理なしで走り、思考ブロックは破棄され、助言テキストだけが executor に届きます。advisor 用のシステムプロンプトは Anthropic 側が用意し、executor のトランスクリプトは引用された文脈として advisor の入力に入ります。

結果は 2 種類

advisor_tool_result.content は判別可能なユニオンで、advisor モデルによって形が変わります。

• advisor_result: text（人が読める助言）。Opus など通常のモデル
• advisor_redacted_result: encrypted_content（読めない暗号化ブロブ）。Claude Fable 5 / Mythos 5 が該当

いずれも次ターンにそのまま（verbatim）返送します。暗号化版はサーバーが次ターンに復号して executor のプロンプトへ展開します。advisor モデルを会話の途中で切り替える場合は content.type で分岐してください。

呼び出しが失敗した場合は advisor_tool_result_error が返り、error_code は max_uses_exceeded / too_many_requests / overloaded / prompt_too_long / execution_time_exceeded / unavailable のいずれか。リクエスト自体は失敗せず、executor は助言なしで続行します。

対応モデルの組み合わせ

advisor はClaude Sonnet 4.6 以上で、かつexecutor と同等以上に賢い必要があります（同格同士、例えば Opus 4.7 と 4.8 は相互に助言可能）。主な組み合わせは次のとおりです。

無効な組み合わせは 400 invalid_request_error になります。モデルの系譜はClaude Fable 5 / Mythos 5 の記事やOpus 4.8 の記事も参照してください。なお提供はClaude API と Claude Platform on AWS（ベータ）で、Amazon Bedrock・Google Cloud・Microsoft Foundry では現時点で未提供です。

課金の見え方

advisor 呼び出しは別のサブ推論として advisor モデルの料金で課金され、usage.iterations[] に内訳が出ます。

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

• トップレベルの usage は executor 分だけ。advisor のトークンは料金が違うため合算されません
• type: "advisor_message" の反復が advisor 料金、type: "message" の反復が executor 料金
• advisor の出力はおおむね 400〜700 テキストトークン（思考込みで 1,400〜1,800 トークン）。あなたの最終成果物を生成しないぶんが節約になります

コスト面はClaude Code のトークン消費とコストの記事の考え方も参考になります。

コストを抑える 3 つの手段

1. max_tokens（ツール定義側）で advisor 出力を上限化。最小 1024、推奨は 2048。Anthropic の計測では、難しい推論タスクで advisor 出力が無指定比約 7 分の 1になり、ほぼ切り詰めなし・品質劣化も検出されずとのこと。上限に達すると stop_reason: "max_tokens" が付き、助言末尾に切り詰めの注記が入ります
2. caching で advisor 側のプロンプトキャッシュ。advisor のプロンプトは呼ぶたびに 1 セグメント増えるだけなので前方一致が安定します。3 回以上呼ぶ会話で得になり、2 回以下だと書き込みコストが上回ります。長いエージェントループでのみ有効化を
3. max_uses で 1 リクエスト内の回数を制限。会話全体の上限が欲しい場合はクライアント側で回数を数え、上限に達したら tools から advisor を外し、履歴中の advisor_tool_result も全て取り除きます（残すと 400 になります）

実運用のコツ

• 組み込みの説明文で、executor は複雑なタスクの序盤や行き詰まり時に advisor を呼ぶよう促されます。コーディング系は過少呼び出しになりがちなので、公式の「推奨システムプロンプト」を先頭に足すと、序盤 1 回＋完了前 1 回の呼び出しが安定します
• Haiku executorが初手で呼ばない場合、2 ターン目の前に短いリマインダ（nudge）をユーザーメッセージで挟むと、Anthropic の内部評価で合格率が約 7 ポイント向上。ただし Sonnet では効果なし、Opus では逆効果なので付けないこと
• effort との併用: コーディングでは Sonnet executor を medium effort にして Opus advisor を付けると、Sonnet を既定 effort で使うのに近い知能をより低コストで得られます

まとめ

• advisor tool は、安い executor が要所で賢い advisor に相談するツール使用パターン。1 リクエスト内で完結するサーバーツールです（beta ヘッダ advisor-tool-2026-03-01）
• 定番は Sonnet + Opus（同コストで品質向上）や Haiku + Opus（安価に知能を一段上げる）。単発 Q&A には不向き
• 課金は usage.iterations に分離。max_tokens・caching・max_uses でコストを制御できる
• Fable 5 / Mythos 5 は暗号化結果（advisor_redacted_result）を返す点、advisor_tool_result を外すと 400 になる点に注意

「モデルを 1 つ選ぶ」から「速いモデルに賢いモデルの判断を差し込む」へ——エージェント設計のコスト対品質の選択肢を一つ増やす機能です。長工程のエージェントを運用しているなら、自分のワークロードで A/B する価値があります。関連してClaude Code のバージョン履歴やプロンプトキャッシュの記事もどうぞ。

参考リンク

• Advisor tool（Claude Platform Docs・一次ソース）
• Introducing advanced tool use on the Claude Developer Platform（Anthropic Engineering）
• Tool use with Claude（概要）

関連記事

• Claude Fable 5 / Mythos 5
• Claude Opus 4.8 と動的ワークフロー
• Claude Code のトークン消費と日本円コスト
• Claude のプロンプトキャッシュとウォームアップ