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

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

advisorツールのコストは、executorとは別レートで課金されるサブ推論として発生します。この費用の主な変動要因はadvisorの出力トークン数です。一般的なワークロードでのadvisor出力はthinkingを含めて1,400〜1,800トークン程度ですが、難しい推論タスクでは4,000〜6,000トークン近くまで伸びることがあります。ここを抑えられれば、advisor呼び出し1回あたりのコストを大きく圧縮できます。

抑える方法は大きく3つあります。①ツール定義のmax_tokensによるハードな上限設定 ②プロンプトでの依頼によるソフトな抑制 ③呼び出しのタイミングと回数そのものを最適化する、の3つで、それぞれ効き方も安全性も異なります。

①max_tokensでハードに上限を切る

ツール定義にmax_tokensを設定すると、advisorの出力(thinking + テキスト)の合計に対する絶対的な上限になります。最小値は1024です。

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

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

max_tokens: 2048は、未設定時と比べて平均出力を約7分の1に圧縮しながら、切り詰めがほぼ発生しない設定として、Anthropicが推奨する出発点です。最小値の1024までさらに削ると出力は約10分の1まで縮みますが、約10%の呼び出しで出力が途中で切られています。この計測の正解率(タスク成功率)は、いずれの設定でもサンプル数の誤差範囲内に収まっており、明確な劣化は確認されていません。ただし計測は特定のハード推論ベンチマークに基づくもので、前段で触れた基本的なワークロードでの出力量(1,400〜1,800トークン程度)より大きく伸びるタスクを前提にした数値です。自分のワークロードでの削減率を鵜呑みにせず、実測で確認したほうが安全です。

このstop_reasonと末尾注記は、ツール定義にmax_tokensを設定した場合にだけ現れます。設定していれば、切り詰めが発生した際に結果ブロックのstop_reasonが"max_tokens"になります。advisor_result(平文)とadvisor_redacted_result(暗号化)のどちらの形式でもこのフィールドは共通で、切り詰めの検出に使えます。APIはさらに[Advisor output truncated at max_tokens=2048.]という注記を助言テキストの末尾に自動で追加するため、平文形式ならクライアント側でもこの注記が見えます。stop_reasonを監視して、切り詰めが多いようなら上限を緩める、といった調整ができます。また、usage.iterationsに含まれる対応するadvisor_messageのoutput_tokensを見れば、各呼び出しが上限にどれだけ近づいたかをstop_reasonとは別に把握できます。

max_tokensはcachingやmax_usesと違い、advisorの呼び出し1回ごとに独立して適用されます。会話内で複数回advisorを呼んでも、上限がまとめて消費されることはありません。また、上限をadvisorモデル自身の出力上限より大きく設定すると400エラーになります。

②プロンプトでソフトに依頼する

max_tokensは絶対的な上限で、超えれば出力はそこで止まります。ただし単純な打ち切りではなく、サーバーはadvisorに残りのトークン予算も渡しており、advisor自身がその予算に収まるよう応答の分量を調整したうえで上限に達します。上限を超えるかどうかはハードに決まる一方、超え方は「予算を意識した応答形成の結果として止まる」という2段構えです。これに対し、プロンプト側で分量を依頼する方法はソフトな制約です。advisorはexecutorのシステムプロンプト・ユーザーメッセージの両方をトランスクリプトとして読みますが、Anthropicの計測で最も効いた配置はユーザーメッセージ内に、advisorを名指しした依頼文を1行加える方法でした。

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

この一文はエージェントフレームワーク側でリクエスト送信前に自動挿入できます。あくまでソフトな依頼のため、advisorがこの分量を超えることもあります。目安としては、本当に必要な上限の8割程度を依頼するとちょうどよく収まりやすい、という結果が出ています。

興味深いのは、この依頼文を入れるとexecutorがadvisorに相談する頻度自体は増えたことです。それでも「呼び出し回数は増えるが1回あたりが軽くなる」ことで、総コストはむしろ下がりました。1回を短く保つ設計は、単に出力を削るだけでなく呼び出しやすさにも影響する、という点は覚えておく価値があります。

max_tokensとの使い分けは単純です。コストやレイテンシに絶対的な上限が必要ならmax_tokens、途中で不自然に切れるリスクを避けつつ簡潔さに寄せたいならプロンプト依頼で、両方を併用しても構いません。

③呼び出しの回数とタイミングを最適化する

出力を削る2つの方法とは別に、そもそも何回呼ぶか・いつ呼ぶかもコストを左右します。advisorツールには会話単位の呼び出し上限が組み込まれていないため、コストの天井を作りたい場合はクライアント側で呼び出し回数を数え、上限に達したら次のリクエストからtools配列のadvisorエントリを外す運用が必要です。履歴に残ったadvisor_tool_resultブロックを削る必要はありません。

呼び出しタイミングのチューニングは、モデルによって効果が逆に出ることがあります。このリマインダー(nudge)は、最初のassistantターンでexecutorがadvisorをまだ呼び出していない場合に、2ターン目のassistant応答を生成する前へ短いuserメッセージとして差し込みます(既定でリマインダーを入れるターン数NUDGE_TURNは2)。Haiku 4.5のexecutorにこの仕組みで短いリマインダーを追加すると、タスク通過率が約7ポイント上昇しました。同じ働きかけをSonnet 5のexecutorに行っても効果は測定できず、Opus executorに行うとむしろ通過率がわずかに下がっています。モデルによって呼び出し頻度の最適点が違うため、全executorに同じ促し方を機械的に適用するのは避けたほうがよく、対象モデルごとに効果を計測してから採用するのが安全です。

コーディング・エージェントタスクでは、探索的な読み込みが少し進んだ段階での早めの1回目の呼び出しと、ファイル書き込みとテスト結果が揃った後の最終確認の呼び出しの、2回のタイミングが総合的な精度向上に寄与しやすいという傾向が確認されています。呼び出し回数を絞るほどコストは下がりますが、判断が必要な節目を飛ばすと精度が落ちるトレードオフがあるため、コスト削減だけを目的に呼び出し回数を機械的に減らすのは推奨されません。

Opus executorは呼びすぎより呼び忘れ対策が効く

Opus executorは元々、追加のプロンプト調整なしでも適切な頻度でadvisorを呼ぶ傾向があります。そのため、コスト削減の主眼は「呼びすぎを減らす」ことよりも、逆に「設計判断が必要な場面でadvisorを呼び忘れていないか」の確認に置いたほうが実効性があります。もしOpus executorがadvisor呼び出しを不当に省略していると分かっている場合に限り、「ファイルを書き換える前に必ずadvisorへ相談する」というチェックポイントをシステムプロンプトに追加する手があります。

ただしこの追加ルールには副作用があります。呼び忘れが起きていたタスクでは通過率が約7〜10ポイント改善した一方、そもそも計画を必要としない単純なタスクではadvisorを不必要に呼ぶ「呼びすぎ」が発生し、混在したワークロード全体で見ると効果はほぼ横ばいでした。したがって、このチェックポイントは既定で入れておくものではなく、実際にOpus executorがadvisorをスキップしている場面を観測できたときだけ、限定的に追加するのが安全です。「呼び出し回数を絞ってコストを下げたい」という動機だけでこのルールを外す・入れるを決めると、狙いと逆方向に効くことがある点には注意が必要です。

Haiku executorとOpus executorで最適なプロンプト戦略の向きが逆になるのは、両者のベースラインの呼び出し傾向が違うためです。Haikuは既定で呼び出しを控えめにしがちなので促す方向のプロンプトが効き、Opusは既定でも適切に呼ぶため同じ促し方をすると過剰になりやすい、という構図です。コーディングタスク向けにAnthropicが提示している既定のシステムプロンプトは、executorへ「実質的な作業(書き込み・編集・解釈の確定)の前に必ずadvisorを呼ぶ」タイミングと、「advisorの助言をどこまで重く扱うか」の判断基準の2つをセットで指示する構成になっており、上記の追加チェックポイントはこの既定プロンプトの上に載せる追加ルールという位置づけです。

effort設定と組み合わせる

コーディングタスクでは、Sonnet executorをeffort(推論の労力設定)の中程度に落とし、Opus advisorと組み合わせる構成が、Sonnetを既定effortで単独稼働させる場合と同等の知能をより低いコストで達成できるとAnthropicは報告しています。最大限の知能を優先する場合は、executorのeffortを既定のままにするのが基本方針です。executor自体のコストとadvisorのコストは別会計のため、executor側のeffort調整はadvisorのコスト削減策と独立して併用できます。

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

max_tokens以外のツール定義パラメータ(max_uses・caching)や、executorとadvisorの組み合わせ制約そのものはClaude APIのadvisor toolを実装する最小構成にまとめています。本記事はコストを抑える3つの手段に絞っています。

まとめ

advisorツールのコストを抑える主な手段は、max_tokensによるハードな上限設定(2048設定で実測約7分の1、切り詰めほぼ0%)、プロンプト内でのソフトな分量依頼、呼び出し回数・タイミングの最適化の3つです。max_tokensは確実な上限が欲しいとき、プロンプト依頼は途中で不自然に切れるリスクを避けたいときに向き、両方の併用も可能です。呼び出し頻度のチューニングはモデルごとに効果の向きが違うため、全executorへ機械的に同じ設定を適用せず、自分のワークロードで計測してから採用することをすすめます。