Claudeのadvisorツールとは｜速い実行役に賢い相談役を組み合わせる

エージェント型のワークロードでは、たいていのターンは機械的な作業です。ファイルを開く、検索する、結果を読む。そういう地味な処理が大半を占める一方で、最初にどう方針を立てるか、行き詰まったときにどう軌道修正するかという「数回の判断」が、成否をほぼ決めてしまいます。Claude APIのadvisorツールは、この構造に着目した仕組みです。安価で速いモデルにタスク全体を回させつつ、要所だけ高性能なモデルに相談させる。この記事では、advisorツールが何をするもので、どんなときに効き、どこに注意すべきかを整理します。

advisorツールが解く問題#

上位モデルは賢いぶん、トークン単価が高くなります。だからといって安いモデルだけで長いエージェント処理を回すと、方針の甘さがそのまま最終成果物の質に響きます。かといって全工程を上位モデルで動かすと、機械的な作業まで高い単価で処理することになり割に合いません。

advisorツールは、この二択の間を取ります。executorと呼ぶ実行役の安いモデルがタスクを進め、方針を立てるべき局面でadvisorと呼ぶ相談役の上位モデルに問い合わせる。advisorはそれまでの会話全体を読んで計画や軌道修正を返し、executorはその助言を踏まえて作業を続けます。最終的な大量の出力はexecutorの単価で生成されるため、上位モデル単独に近い品質を、より低いコストで狙えるという発想です。公式ドキュメントでは、コーディングエージェント・コンピュータ操作・多段の調査パイプラインといった長時間のワークロードが適するとされています。

どんなときに向くか・向かないか#

advisorが素直にはまるのは、次のような構成です。

一方で、向かない場面もはっきりしています。計画する余地のない単発の質問応答、利用者自身がコストと品質のトレードオフを選んでいる素通しのモデル選択、そして毎ターンが本当にadvisorモデルの実力を必要とするようなワークロードです。効果はタスク依存なので、自分のワークロードで実際に測るという前提は外せません。

効果の度合いや適性は、扱うタスクの性質に強く依存します。この記事の内容は公式ドキュメントの記載に基づく整理であり、数値的な改善幅の主張はしていません。導入前に、必ず自社の代表的なタスクで比較検証してください。

仕組み:1回のリクエストの中で完結する#

advisorツールをtools配列に加えると、executorが他のツールと同じ判断でadvisorを呼ぶかどうかを決めます。呼び出しが起きると、内部では次のように処理が進みます。

1. executorが server_tool_use ブロック(name: "advisor", input は空)を出す
   -> 呼ぶタイミングだけをexecutorが決め、文脈はサーバー側が用意する
2. サーバーがadvisorモデルで別の推論を実行
   -> advisor専用のシステムプロンプトの下で、executorの全文脈を読む
3. advisorの応答が advisor_tool_result ブロックとしてexecutorに返る
4. executorが助言を踏まえて生成を続ける

ポイントは、この一連の流れが1回の/v1/messagesリクエストの中で完結することです。呼び出し側で追加のやり取りは要りません(途中で一時停止するケースだけ、フォローアップのリクエストで再開します)。advisorへ渡る文脈は、システムプロンプト・ツール定義・過去のターンとツール結果・executorがそのターンで生成中のテキストまでを含みます。なおserver_tool_useのinputは常に空で、executorがそこに何を書いてもadvisorには届きません。文脈はすべてサーバーが会話全体から自動で組み立てます。

advisor自身はツールなし・コンテキスト管理なしで動き、思考ブロックは結果を返す前に破棄されます。executorに届くのは助言のテキストだけです。

最小構成のコード#

executorにclaude-sonnet-4-6、advisorにclaude-opus-4-8を組み合わせる例です。advisorはツール定義の中のmodelで指定します。

import anthropic

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-sonnet-4-6",           # executor(実行役)
    max_tokens=4096,
    betas=["advisor-tool-2026-03-01"],
    tools=[
        {
            "type": "advisor_20260301",
            "name": "advisor",
            "model": "claude-opus-4-8",   # advisor(相談役)
        }
    ],
    messages=[
        {
            "role": "user",
            "content": "Goで graceful shutdown 付きの並行ワーカープールを実装して。",
        }
    ],
)

マルチターンで続ける場合は、advisor_tool_resultブロックを含むアシスタントの応答内容をそのまま履歴に積み直して次のターンへ渡します。履歴にadvisor_tool_resultが残っているのにtoolsからadvisorツールを外すと、400 invalid_request_errorになる点に注意してください。

組み合わせられるモデルには制約がある#

executorモデル(トップレベルのmodel)とadvisorモデル(ツール定義内のmodel)は、有効なペアを組む必要があります。ルールはシンプルで、advisorはSonnet 4.6以上の性能で、かつexecutor以上の性能でなければなりません。同格どうし(たとえばOpus 4.7とOpus 4.8)は互いにadvisorになれます。無効な組み合わせを指定すると、400 invalid_request_errorが返ります。

代表的な使い方は、先ほどの表のとおりSonnetやHaikuをexecutorにしてOpusをadvisorに据える形です。実行役に安いモデルを置き、判断だけを賢いモデルに委ねる、という役割分担が基本になります。

コストの見え方#

advisor呼び出しは別の推論(サブインファレンス)として、advisorモデルの単価で課金されます。使用量はusage.iterations[]配列に分解して報告され、type: "advisor_message"の項目がadvisor単価、type: "message"の項目がexecutor単価です。

{
  "usage": {
    "output_tokens": 531,
    "iterations": [
      { "type": "message",         "output_tokens": 89 },
      { "type": "advisor_message", "model": "claude-opus-4-8", "output_tokens": 1612 },
      { "type": "message",         "output_tokens": 442 }
    ]
  }
}

トップレベルのusageはexecutorのトークンだけを表し、advisor分は別単価のため合算されません。コスト集計を実装するならusage.iterationsを見るのが正確です。公式ドキュメントによると、advisorの出力は軽めのワークロードでテキストで概ね400から700トークン、思考込みでも1,400から1,800トークン程度とされています。コスト削減が成立するのは、advisorが最終成果物そのものを生成しないからです。長い出力はあくまでexecutorが安い単価で書きます。

運用でつまずかないための勘所#

advisorは「入れて終わり」ではなく、呼び出し回数と出力量をどう制御するかが実務の中心になります。

まず何から試すか#

導入を検討するなら、既存のエージェントのうち「方針で結果が変わる」タスクを1つ選び、executorはそのまま、advisorにOpusを足して比較するのが手堅い入口です。品質とコストの両方をusage.iterationsで実測し、割に合うかを自分のワークロードで判断します。コスト設計全体の考え方は別記事でも扱っています。

よくある質問#

まとめ#

advisorツールは、モデルを1つ選んで終わりにしない発想の道具です。実行役と相談役を分け、賢い判断が必要な数回だけ上位モデルの力を借りる。うまくはまれば品質とコストのバランスは取りやすくなりますが、呼び出し回数と出力量を測らないと期待した効果は出ません。ベータ機能である点も踏まえ、まずは小さく試して数字で確かめるところから始めるのがおすすめです。