Claude API advisorのmax_tokensで出力を7分の1に抑える

advisorのコストはadvisorの出力トークンで決まる

advisorツールは、executorとは別レートで課金されるサブ推論として動きます。費用の最大の変動要因はadvisorの出力トークン数です。

リクエスト直下のmax_tokensは、executorの出力にしか効きません。advisorのトークンには効かず、executorに掛けたタスクバジェットも消費しません。レスポンスのusageの合計もexecutor分だけで、advisor分はusage.iterationsのtype: "advisor_message"の行に出ます。

公式の例では、Opus 5をadvisorにした1回の呼び出しで、executorの2回分の出力が89トークンと442トークン、advisorの出力が1,612トークンでした。軽めのワークロードなら、advisor出力は思考込みで1,400〜1,800トークン程度です。難しい推論タスクでは、未設定のまま平均4,200〜5,900トークンまで伸びます。

Opus 5の出力単価(100万トークンあたり$25)で、この平均トークン数から1回あたりの出力コストを概算すると次のとおりです。

抑える手段は3つあります。ツール定義のmax_tokensによるハードな上限、プロンプトでのソフトな依頼、そして呼び出しの回数とタイミングの調整です。効き方も、品質へのリスクも違います。

上限を確実に切るならmax_tokens

ツール定義にmax_tokensを置くと、advisorの出力(thinkingとテキストの合計)に対する1回ごとの上限になります。最小値は1024です。advisor自身の出力上限より大きい値を入れると、400エラーになります。

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

advisorツールはベータ機能なので、リクエストにはベータヘッダーadvisor-tool-2026-03-01が要ります。Python SDKならbetas引数で渡します。

response = client.beta.messages.create(
    model="claude-sonnet-5",
    max_tokens=4096,
    betas=["advisor-tool-2026-03-01"],
    tools=[
        {
            "type": "advisor_20260301",
            "name": "advisor",
            "model": "claude-opus-5",
            "max_tokens": 2048,
        }
    ],
    messages=[{"role": "user", "content": "Goでワーカープールを実装して"}],
)

Anthropicが難しい推論ベンチマーク(設定ごとn=40)で測った結果は次のとおりです。

2048は、平均出力を約7分の1に縮めながら切り詰めがほぼ出ない設定で、Anthropicが勧める出発点です。1024まで下げると出力は約10分の1になりますが、約10%の呼び出しで途中で切れます。正解率はどの設定でもサンプル数の誤差範囲に収まり、明確な劣化は出ていません。

ただし、この数字は特定のハード推論ベンチマークのものです。冒頭の1,400〜1,800トークンという軽めの出力量とは前提が違うので、削減率は自分のワークロードで測り直します。

stop_reasonも末尾の注記も、max_tokensを設定したときにしか出ません。未設定のままでは、切り詰めの有無を結果ブロックから知る手段がありません。

上限は1回の呼び出しごとに独立して掛かり、同じリクエストの中で複数回呼んでも共有されません。

途中で切られたくないならプロンプトで頼む

advisorは、executorのシステムプロンプトとユーザーメッセージの両方を、executorの作業内容を伝える引用文脈として受け取ります。このため、advisorに直接呼びかける指示は、第三者視点の説明より確実に守られます。Anthropicの検証で最も効いたのは、ユーザーメッセージにadvisorを名指しした1行を足す配置でした。

(Advisor: please keep your guidance under 80 words — I need a focused starting point, not a comprehensive plan.)

この1行は、エージェントのフレームワーク側で送信前に自動で先頭へ付けられます。あくまでソフトな制約で、advisorが超えることもあります。本当に許せる上限の8割ほどを頼むと収まりやすい、という結果です。

面白いのは、この1行でexecutorがadvisorに相談する頻度が増えたことです。それでも1回が短くなるため、総コストは下がりました。

呼び出しの回数に天井を作る

ツール定義のmax_usesは、1回のリクエストの中での呼び出し上限です。上限に達すると、以降の呼び出しはerror_code: "max_uses_exceeded"のエラー結果になり、executorは助言なしで続けます。リクエスト自体は失敗しません。

会話単位の天井はAPIに組み込まれていません。クライアント側で呼び出し回数を数え、上限に達したら次のリクエストのtools配列からadvisorエントリを外します。履歴にあるadvisor_tool_resultブロックを削る必要はありません。

advisor自身の文脈をキャッシュするcachingは、{"type": "ephemeral", "ttl": "5m"}のような設定です。ブロックごとのcache_controlと違い、サーバーがキャッシュの境界を決めるオンとオフのスイッチです。公式は、advisorの呼び出しが3回以上になる会話に限って有効にするよう書いています。

課金の面では、Priority Tierの扱いにも注意がいります。Priority Tierはモデルごとに独立して適用され、executorに結んだ契約はadvisorには及びません。advisorをPriority Tierで走らせるには、advisor側のモデルにも契約が必要です。

executorごとに呼び出し頻度の最適点が違う

呼び出しの回数を減らす前に、そもそも呼びすぎなのか呼び足りないのかを、executorのモデルごとに見分ける必要があります。公式の検証では、同じ促し方がモデルによって逆向きに効きました。

リマインダーは、最初のassistantターンでadvisorが呼ばれていないときに限り、2ターン目の応答を生成する前へ短いuserメッセージとして差し込みます。差し込むターンを決めるNUDGE_TURNの既定値は2で、モデルが課題を把握したあと、方針を決め切る前に届く位置です。

You have not consulted the advisor yet. If the task has a non-obvious
design decision or a failure mode you haven't ruled out, call advisor
now before committing to an approach.

コーディングやエージェントのタスクでは、2つのタイミングが効くとされています。探索的な読み込みが少し進んだ段階での1回目と、難しいタスクでファイル書き込みとテスト結果が揃ったあとの最終確認です。advisorがツール呼び出しの総数と会話の長さを減らせると、同程度のコストで精度が上がります。

Haiku向けの別ブロックには副作用がある

Haikuが書き込み中心のタスクを回すなら、公式は別のシステムプロンプトも用意しています。「最初の書き込みや状態を変えるbash呼び出しの前に、必ずadvisorを呼ぶ」という規則を含むもので、社内のコーディングベンチマークで標準より通過率が約7.5ポイント上がりました。

一方で、ブラウズを使った読解のベンチマーク(n=1,266)では、近い変種が精度を約4ポイント下げています。コーディングと調べ物が混ざるワークロードでは、標準のブロックのままにするか、ワークロードの種類で切り替えを判定します。

Opusは呼び忘れの観測が先

推奨のコーディング用システムプロンプトは、advisorの呼び出しをタスクあたり2〜3回に揃えたいときのものです。

Opusが呼び足りない場合の追加チェックポイントは、設計・アーキテクチャ・リスクの質問ではファイルに触れなくてもadvisorを先に呼ぶこと、という指示です。さらに「最初のファイル書き込みか状態を変えるbash呼び出しは、必ずadvisor呼び出しの後」と置きます。Anthropicの検証では、このブロックの近い変種が呼び足りないタスクで通過率を約7〜10ポイント上げました。ただしOpusが、計画の要らないタスクでも呼びすぎるようになりました。混在したワークロード全体ではほぼ横ばいです。Opusがadvisorを飛ばす場面を観測してから入れるもので、既定では加えません。

呼び出し回数を絞ってコストを下げたいだけの動機で、このルールを外したり入れたりすると、狙いと逆に効くことがあります。

effort設定と組み合わせる

コーディングタスクでは、Sonnet executorのeffort(推論の労力設定)を中程度にし、Opus advisorを組み合わせる構成が、既定effortのSonnet単独と同程度の知能を、より低いコストで出すと公式は書いています。最大限の知能を優先するなら、executorのeffortは既定のままにします。

Sonnet 5.5をexecutorにするときの注意

Sonnet 5.5の単価はSonnet 5と同額で、入力$2、出力$10(100万トークンあたり)です。executor側のコスト計算は変わりません。

変わるのはadvisorの選び方です。Sonnet 5.5 executorと組めるadvisorは、Opus 5.5・Opus 5・Fable 5.1・Fable 5・Mythos 5.1・Mythos 5とSonnet 5.5自身です。Opus 4.8やSonnet 5を指定すると400エラーになります。

advisorの出力単価もモデルで違います。Opus 5.5は100万トークンあたり$20、Opus 5は$25です。max_tokensで出力量を絞ったうえで、どちらのモデルをadvisorに置くかで、1回あたりの単価がさらに変わります。

これらのadvisorは暗号化された助言を返すため、テキストを見て切り詰めを判断することはできません。上限に達したかどうかは、結果ブロックのstop_reasonで確かめます。

この手段が使えない構成とadvisorが合わない場面

ここまでの手段が通るのは、Claude APIとClaude Platform on AWSのベータ提供です。Amazon Bedrock、Google Cloud、Microsoft Foundryでは、advisorツール自体が提供されていません。

Claude Managed Agentsにもadvisorはありますが、設定の形が違います。エージェントのmultiagentロスターに{"type": "advisor", "model": ...}の1行を足す方式で、max_uses・max_tokens・cachingのどれも受け付けません。助言はadvisor_tool_resultブロックではなく、セッションのイベントストリームに流れます。この記事のmax_tokensは、Managed Agentsでは使えません。

そもそもadvisorが合いにくい場面もあります。1往復で終わるQ&Aは計画する余地がなく、利用者が自分でコストと品質のバランスを選ぶ素通しのモデルセレクターでは、使う意味が薄れます。どのターンでもadvisorの全力が要るワークロードでも、executorを安く回す利点が出にくくなります。

ツール定義の書き方そのものは別記事にある

max_tokens以外のパラメータ(max_uses・caching)や、executorとadvisorの組み合わせ制約はClaude APIのadvisor toolを実装する最小構成にあります。

まとめ

出力を抑える最初の一手は、max_tokens: 2048を入れてstop_reasonの切り詰め率を見ることです。途中で切れるのが困る用途では、プロンプトの依頼を足します。呼び出し頻度の促し方はモデルで効き方が逆になるので、executorごとに自分のワークロードで測ってから入れます。