アドバイザーツールで高性能モデルに戦略を聞く

アドバイザーツールは、速くて安い「実行モデル」が、生成の途中で上位の「アドバイザーモデル」に方針を相談するための仕組みです。相談は Anthropic 側のサーバーで完結するので、/v1/messages の1リクエストの中で完了し、こちらから追加のAPI呼び出しをする必要はありません。ベータ機能で、ヘッダー advisor-tool-2026-03-01 が必要です。

アドバイザーツールとは何か

コーディングエージェントやコンピュータ操作、複数段階のリサーチのように長い工程を自動で進める用途では、ほとんどのターンは機械的な作業で、決定的に効くのは最初の方針だけ、ということがよくあります。アドバイザーツールはこの構造を狙ったもので、トークン生成の大部分を安い実行モデルのレートで進めつつ、方針の質だけを上位モデルに寄せます。

動作は次の4段階です。

1. 実行モデルが server_tool_use ブロック（name: "advisor"、input は空）を出す。いつ相談するかを決めるのは実行モデルで、何を渡すかはサーバーが用意します。
2. Anthropic 側でアドバイザーモデルの推論が別途1回走る。アドバイザーは Anthropic が用意したシステムプロンプトの下で動き、入力として実行モデルのトランスクリプト全体（あなたのシステムプロンプト、ツール定義、これまでのターンとツール結果、そのターンでこれまでに生成されたテキスト）を引用の形で受け取ります。
3. アドバイザーの回答が advisor_tool_result ブロックとして実行モデルに戻る。
4. 実行モデルが助言を踏まえて生成を続ける。

アドバイザー自身はツールを持たず、コンテキスト管理もしません。thinking ブロックは結果が返る前に落とされ、助言のテキストだけが実行モデルに届きます。

公式が挙げている向き・不向きははっきりしています。向いているのは、複雑なタスクで既に Sonnet を使っていて上位のアドバイザーを足す構成（Opus なら総コストは同等かむしろ下がる）と、Haiku を使っていて知能を一段上げたい構成（Haiku 単独より高いが、実行モデルごと大きなモデルに替えるよりは安い）です。逆に、単発の質疑応答（計画する対象がない）、利用者が自分でモデルを選ぶ構成、毎ターン上位モデルの能力が要る作業には向きません。

リクエストの書き方

ツール配列に advisor_20260301 を1つ足すだけです。実行モデルはトップレベルの model、アドバイザーモデルはツール定義の中の model で、この2つが別物である点がこの機能の要です。

{
  "model": "claude-sonnet-5",
  "max_tokens": 4096,
  "tools": [
    {
      "type": "advisor_20260301",
      "name": "advisor",
      "model": "claude-opus-5"
    }
  ],
  "messages": [
    { "role": "user", "content": "Go で graceful shutdown 付きの並行ワーカープールを作って" }
  ]
}

ヘッダーに anthropic-beta: advisor-tool-2026-03-01 を付けます。Python SDK なら client.beta.messages.create(..., betas=["advisor-tool-2026-03-01"])、TypeScript なら betas: ["advisor-tool-2026-03-01"] です。

ツール定義で指定できるパラメータは次のとおりです。

caching の形は {"type": "ephemeral", "ttl": "5m" | "1h"} です。コンテンツブロックに付ける cache_control と違ってブレークポイントの指定ではなく、単なるオン/オフのスイッチで、境界をどこに置くかはサーバーが決めます。

レスポンスの読み方

アドバイザーが呼ばれると、アシスタントの content に server_tool_use ブロックと、それに対応する advisor_tool_result ブロックが並びます。

{
  "role": "assistant",
  "content": [
    { "type": "text", "text": "アドバイザーに相談します。" },
    {
      "type": "server_tool_use",
      "id": "srvtoolu_abc123",
      "name": "advisor",
      "input": {}
    },
    {
      "type": "advisor_tool_result",
      "tool_use_id": "srvtoolu_abc123",
      "content": {
        "type": "advisor_result",
        "text": "チャネルベースの協調パターンを使うこと。難所はシャットダウン時の処理中タスクの排出で、まず入力チャネルを閉じ、その後 WaitGroup を待つ..."
      }
    },
    { "type": "text", "text": "実装はこうなります。書き込み側の飢餓を避けるためチャネルベースの..." }
  ]
}

server_tool_use.input は常に空です。アドバイザーが見る内容はサーバーがトランスクリプトから組み立てるので、実行モデルが input に何を書いてもアドバイザーには届きません。

ここで実装上つまずきやすいのが、advisor_tool_result.content がアドバイザーモデルによって形の変わる判別可能ユニオンであることです。

公式の記載では、Claude Opus 5・Claude Fable 5・Claude Mythos 5 をアドバイザーにすると暗号化された advisor_redacted_result が返り、互換表にあるそれ以外のアドバイザーモデルは平文の advisor_result を返します。暗号化された助言は実行モデルがサーバー側で読みますが、こちらのクライアントからは読めません。自分のレスポンスで助言の本文を読みたい場合は、claude-opus-4-8 のように平文を返すアドバイザーを選びます。

したがって、判定はブロックの型（常に advisor_tool_result）ではなく content の型で分岐させます。.text を無条件に読むコードは、Claude Opus 5 をアドバイザーにした瞬間に何も取れなくなります。

実行モデルとアドバイザーモデルの組み合わせ

実行モデルとアドバイザーモデルは有効な組み合わせでなければならず、外れると 400 エラーになります。規則は2つです。アドバイザーは Claude Sonnet 4.6 以上であること。そしてアドバイザーは実行モデルと同等以上の能力であること。同等どうし（たとえば Claude Opus 4.7 と Claude Opus 4.8）は相互にアドバイザーになれます。

表の読み方で注意したいのは、Sonnet 5 を実行モデルにすると Sonnet 4.6 や Opus 4.6 はアドバイザーに選べない点です。「上位モデルなら何でも指定できる」わけではなく、あくまで能力の順序で決まります。組み合わせを設定ファイルで外から差し替えられるようにしている場合、実行モデルだけを新しくしてアドバイザーの指定を据え置くと 400 で落ちるので、両方を対で管理してください。

コストを抑える設定

アドバイザーの副推論はアドバイザーモデルのレートで課金されます。つまり放っておくと、上位モデルの出力トークンがそのまま乗ります。公式が挙げている抑え方は3つです。

1. max_tokens で1回あたりの助言を短くする

{
  "type": "advisor_20260301",
  "name": "advisor",
  "model": "claude-opus-5",
  "max_tokens": 2048
}

最小値は 1024 で、アドバイザーモデル自身の出力上限を超える値を渡すと 400 エラーになります。上限は1回の呼び出しごとに独立して適用され、同一リクエスト内の複数回で共有されません。単なる打ち切りではなく、サーバーが残りトークン予算をアドバイザーに伝えるので、アドバイザー側が収まるように回答を整えます。

公式の推奨開始値は max_tokens: 2048 です。Anthropic の難易度の高い推論ベンチマークでの計測（各構成 n = 40）では、上限なしに比べて助言の平均出力が約7分の1になり、打ち切りはほぼゼロ、品質の劣化も検出されなかったとされています。

最小値の 1024 は出力が約10分の1まで減る代わりに、約1割の呼び出しが打ち切られます。この標本数では精度の差はいずれの構成でも誤差の範囲だったと明記されているので、数値を鵜呑みにせず自分のワークロードで検証してください。

2. 回数を制限する

1リクエスト内なら max_uses で足ります。会話全体の予算を管理したい場合は、アドバイザー呼び出しの回数をクライアント側で数えます。 上限に達したら tools からアドバイザーツールを外すだけでよく、過去の advisor_tool_result ブロックをメッセージ履歴から取り除く必要はありません。

3. キャッシュは呼び出しが多いときだけ

caching を有効にするのは、その会話でアドバイザー呼び出しが3回以上見込めるときに限る、というのが公式の目安です。キャッシュの書き込みには割増料金がかかるため、2回以下では元が取れません。

途中で止まった turn の再開

アドバイザー呼び出しが未処理のまま、レスポンスが stop_reason: "pause_turn" で終わることがあります。このときレスポンスにはアドバイザーの server_tool_use ブロックだけがあり、対応する advisor_tool_result がありません。

再開の手順は単純です。

1. そのアシスタントメッセージを、content を一切変えずに（server_tool_use ブロックを残したまま）messages に追加する。
2. 同じアドバイザーツール定義と同じベータヘッダーを付けて、もう一度リクエストを送る。

ユーザーメッセージを足す必要も、tool_result ブロックを自分で作る必要もありません。 APIが保留中のアドバイザー呼び出しを実行し、新しいレスポンスで実行モデルのターンを続けます。再開したターンがまた一時停止することもあり、その場合は同じ手順を繰り返します。

ここでの落とし穴は、再開リクエストからアドバイザーツールを外すと 400 invalid_request_error になることです。保留中の server_tool_use ブロックに対応するツール定義が無くなるためで、コスト制御のためにツールを外す処理を入れている場合は「保留中の呼び出しがあるあいだは外さない」という条件が要ります。

同じターンの中で実行モデルがあなたのクライアント側ツールも呼んでいた場合は、レスポンスは stop_reason: "tool_use" で終わり、アドバイザー呼び出しは保留のままになります。この場合は普段どおり tool_result ブロックを返せばよく、保留中のアドバイザー呼び出しは次のリクエストの冒頭で実行されます。