Claude API の Advisor Tool(beta)実践 — 安価な Sonnet 4.6 を実行役、Opus 4.7 を相談役として組み合わせ、コストを抑えつつ精度を引き上げる

Claude API の Advisor Tool が beta 公開(2026-05-06、Code with Claude 2026)。速い executor model(Sonnet 4.6 / Haiku 4.5)が、賢い advisor model(Opus 4.7)に途中で相談する仕組みです。本記事では beta header と tool 構成、server_tool_use と advisor_tool_result の構造、推奨 system prompt(timing block)、advisor 出力を 35-45% 削るテクニック、advisor-side caching の損益分岐、cost control のベストプラクティスまでを実装目線で整理します。

author
r43
date
(2026年5月7日)
category
Claude Code
reading
6 min
commit
3b17ec9

Anthropic が Code with Claude 2026 のタイミングで Advisor Tool を beta 公開しました。コンセプトは単純で、速い executor model が、賢い advisor model に途中で相談する——これだけです。具体的には Sonnet 4.6 + Opus 4.7 や Haiku 4.5 + Opus 4.7 という組み合わせで、Sonnet 単独より高品質、Opus 単独より大幅に安価という領域を狙えます。本記事では beta の使い方とハマりどころを実装目線でまとめます。

何が新しいか

Advisor は server-side tool(web_search / code_execution 系の仲間)です。executor が tool として advisor を呼ぶと、サーバ側で別 inference が advisor model 上で走り、その結果が advisor_tool_result として executor の文脈に注入されます。1 リクエストの中で完結するので、こちらでラウンドトリップを増やさず、普通の Messages API 呼び出し 1 回で利用できます。

ポイント:

  • 速い executor が作業の主体(token 生成のほとんどはここ)
  • 賢い advisor が戦略・計画の主体(全文脈を読んで 400〜700 token の助言を返す)
  • 結果として、advisor-solo 品質に近づきつつ、生成の大半は安いほうのレートで billed

使えるモデル組み合わせ

executor(top-level model)と advisor(tool 内の model)は有効ペアでなければならない。advisor は executor 以上の能力でなければなりません。

ExecutorAdvisor
Claude Haiku 4.5(claude-haiku-4-5)Claude Opus 4.7
Claude Sonnet 4.6(claude-sonnet-4-6)Claude Opus 4.7
Claude Opus 4.6(claude-opus-4-6)Claude Opus 4.7
Claude Opus 4.7(claude-opus-4-7)Claude Opus 4.7

組み合わせが不正だと 400 invalid_request_error で名指しで弾かれます。

最小コード

beta header:

anthropic-beta: advisor-tool-2026-03-01

cURL:

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-7"
    }],
    "messages": [{
      "role": "user",
      "content": "Go で graceful shutdown 付きの concurrent worker pool を実装して"
    }]
  }'

Python SDK:

import anthropic
client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=4096,
    betas=["advisor-tool-2026-03-01"],
    tools=[{
        "type": "advisor_20260301",
        "name": "advisor",
        "model": "claude-opus-4-7",
    }],
    messages=[{
        "role": "user",
        "content": "Go で graceful shutdown 付きの concurrent worker pool を実装して",
    }],
)

内部で起きていること

  1. executor が server_tool_use ブロック(name: "advisor"、input: {})を出して呼出を宣言
  2. サーバ側で advisor model が executor の全文脈を見ながら別 inference を回す(thinking 含む)
  3. advisor の thinking はサーバで落とされ、助言テキストだけ advisor_tool_result として executor に戻る
  4. executor が助言を読んで生成を続行

レスポンスはこう見えます:

{
  "role": "assistant",
  "content": [
    { "type": "text", "text": "Let me consult the advisor on this." },
    { "type": "server_tool_use", "id": "srvtoolu_abc", "name": "advisor", "input": {} },
    { "type": "advisor_tool_result", "tool_use_id": "srvtoolu_abc",
      "content": { "type": "advisor_result",
        "text": "Use a channel-based coordination pattern. The tricky part is..." } },
    { "type": "text", "text": "Here's the implementation..." }
  ]
}

server_tool_use.input は常に空です。advisor が見るのはサーバが構築する全文脈で、input に何を入れても advisor には届きません(誤解しやすい)。

マルチターン: 助言ブロックはそのまま戻す

advisor_tool_result ブロックを履歴に保ったまま assistant content をそのまま 次ターンの messages に積みます。advisor tool を tools から外したまま、履歴に advisor_tool_result を残すと 400 で落ちるので注意。

# OK: advisor を維持
messages.append({"role": "assistant", "content": response.content})
response2 = client.beta.messages.create(
    model="claude-sonnet-4-6", tools=tools,  # advisor を維持
    betas=["advisor-tool-2026-03-01"], messages=messages, max_tokens=4096,
)

会話単位で advisor を打ち切りたい場合は、(a) tools から advisor を外し、(b) 履歴から advisor_tool_result を全部 strip する——両方やる必要があります。

推奨 system prompt — timing block

公式が「コーディングエージェントならこの prompt が高インテリジェンス×Sonnet 級コストを出した」と明言しているテンプレがあります。要旨を日本語で意訳して掲載します。

You have access to an `advisor` tool backed by a stronger reviewer model.
It takes NO parameters — when you call advisor(), your entire conversation
history is automatically forwarded.

Call advisor BEFORE substantive work — before writing, before committing
to an interpretation, before building on an assumption. If the task
requires orientation first (finding files, fetching a source, seeing
what's there), do that, then call advisor. Orientation is not substantive
work. Writing, editing, and declaring an answer are.

Also call advisor:
- When you believe the task is complete. BEFORE this call, make your
  deliverable durable: write the file, save the result, commit the change.
- When stuck — errors recurring, approach not converging, results that
  don't fit.
- When considering a change of approach.

On tasks longer than a few steps, call advisor at least once before
committing to an approach and once before declaring done. On short
reactive tasks where the next action is dictated by tool output you just
read, you don't need to keep calling.

そしてその直後に、助言の扱い方ブロック:

Give the advice serious weight. If you follow a step and it fails
empirically, or you have primary-source evidence that contradicts a
specific claim, adapt. A passing self-test is not evidence the advice
is wrong — it's evidence your test doesn't check what the advice is
checking.

If you've already retrieved data pointing one way and the advisor points
another: don't silently switch. Surface the conflict in one more advisor
call — "I found X, you suggest Y, which constraint breaks the tie?"

この 2 ブロックを executor の system prompt の冒頭に置くだけで、ばらつきの大きい「いつ呼ぶか問題」がかなり安定します。

advisor 出力を 35〜45% 削る一行

advisor のコストは助言の長さで決まります。公式が紹介している1 行制約でかなり短くできます:

The advisor should respond in under 100 words and use enumerated steps,
not explanations.

社内テストで呼び出し頻度を変えずに advisor 出力 token 35〜45% 減を確認したと書かれています。timing block と組み合わせるのが最強。

advisor の billing と usage.iterations

advisor は executor とは別レートで billed です。usage.iterations[] で反復ごとに breakdown されます:

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

top-level の output_tokens は executor の合計(advisor は含まれない)、advisor は iterations[].type == "advisor_message" を抜き出してadvisor のレートで集計します。コスト計算ロジックを書くときはこの構造を前提にしないと取り違えます。

advisor-side caching の損益分岐

advisor は会話を進めるたびに過去の advisor 呼び出しの prompt + 新規分を見ます。つまりprefix が安定なので、prompt caching が効きます。

tools = [{
  "type": "advisor_20260301",
  "name": "advisor",
  "model": "claude-opus-4-7",
  "caching": {"type": "ephemeral", "ttl": "5m"},  # 5m or 1h
}]

ただし書き込みコストもかかるので、1 会話で 2 回以下の呼び出しなら不要、3 回以上で損益分岐を超える——これが公式の目安。長い agentic loop で on、短い Q&A で off が基本。

注意点:

  • caching を会話途中で toggle すると cache miss を誘発。会話単位で固定する
  • clear_thinking を keep != "all" で使うとadvisor 側のキャッシュが毎ターン無効化(品質ではなくコスト劣化)。Opus 4.5+ / Sonnet 4.6+ の default は keep: "all" だが、それ以外のモデルでは明示で keep: "all" を入れる

max_tokens / task_budget との相互作用

  • max_tokens: executor の生成だけを bound する。advisor の token はここに入らない
  • task_budget(公式 docs): executor の budget だけで、advisor のサブ推論はカウントされない

つまり会話単位で advisor のコストを縛る組み込みの仕組みは無い。クライアント側でカウントして、上限に達したら**(a) tools から advisor を外し、(b) 履歴から advisor_tool_result を strip**(両方必要)で打ち切る、というパターンになります。

ストリーミング時の挙動

advisor のサブ推論はストリームしません。executor のストリームが一時停止し、advisor が完了すると advisor_tool_result が content_block_start 一発で全文届きます(deltas 無し)。

  • ポーズ中は 30 秒ごとの SSE ping だけ流れる(短い advisor 呼び出しでは ping すら出ないことも)
  • ポーズ完了後、message_delta で usage.iterations が更新される

UI 側で「advisor 相談中…」のスピナーを出したいなら、server_tool_use ブロック検出 → advisor_tool_result ブロック到着までの区間にイベントを噛ませると素直に組めます。

他の tool との合わせ技

server tool / client tool と自由に同居できます:

tools = [
  {"type": "web_search_20250305", "name": "web_search", "max_uses": 5},
  {"type": "advisor_20260301", "name": "advisor", "model": "claude-opus-4-7"},
  {"name": "run_bash", "description": "Run a bash command",
   "input_schema": {"type": "object",
                    "properties": {"command": {"type": "string"}}}},
]

executor は web 検索 → advisor 相談 → bash 実行、を1 ターン内で連鎖できます。「advisor の plan を踏まえて bash を選ぶ」という流れが現実的に組めるのがこの tool の強み。

採用判断

強く効くケース:

  • 既に Sonnet で agentic loop(コーディング、computer use、研究 pipeline)を回している → Opus advisor を足して質を底上げ
  • Haiku で動かしているが、たまに頭の良さが欲しい → Opus advisor で局所的に Opus 級
  • effort を medium に下げてコスト削減しつつ、要所で Opus advisor を呼ぶ(公式が「Sonnet medium + Opus advisor ≒ Sonnet default」とコメント)

そうでもないケース:

  • 1 turn の Q&A(plan する余地が無い)
  • ユーザーが自分でモデルを選ぶ pass-through 系(advisor が割り込むと UX が壊れる)
  • 全 turn で advisor 並みの能力が要るワークロード(executor を Opus にしたほうが素直)

まとめ

Advisor Tool は 「強い model に planning を預け、執行は安い model に任せる」 という、これまで自前で multi-call 設計していたパターンを 1 リクエストの中で公式に成立させる機能です。実装上は:

  • beta header advisor-tool-2026-03-01 と advisor_20260301 で組み込み
  • timing block + 100 word constraint を system prompt に置いて挙動を安定化
  • マルチターンでは assistant content をそのまま回す(strip するなら tool も外す)
  • usage.iterations で advisor を別レート billing
  • 3 回以上呼ぶ会話なら advisor caching を on

の 5 点を押さえれば、Sonnet 4.6 ベースのエージェントで 「Opus 級の判断、Sonnet 級のコスト」 を現実的に手に入れられます。Code with Claude 2026 では「コストを約 1/5 に抑えつつフロンティアモデル品質を出せる」(原文: “frontier model quality at 5x lower cost”)と紹介されました。テンプレ通りに組めば手元で再現できます。

参考