Claude API advisorツールの課金構造 — usage.iterationsの読み方

advisorの呼び出しはexecutorとは別料金の推論として課金される

Claude APIのadvisorツールは、executorモデルとは別に、advisorモデルへのサブ推論を1回ごとに走らせます。このサブ推論はadvisorに指定したモデルのレートで独立に課金され、executorのモデル料金には合算されません。executorがSonnet 5でadvisorがOpus 5なら、Sonnet 5の単価で課金される部分とOpus 5の単価で課金される部分が別々に発生する、という構造です。executorをSonnet 5.5にしても単価はSonnet 5と同額($2 / $10 per MTok)なので、以降の計算はそのまま当てはまります。ただしSonnet 5.5 executorが受け付けるadvisorは限られ、助言は暗号化されて返ります。

この内訳はレスポンスのusageオブジェクト内、usage.iterationsという配列にそのまま記録されます。

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

iterationsの各要素はtypeで2種類に分かれます。"message"はexecutor自身のターンで、executorモデルのレートで課金されます。"advisor_message"はadvisor呼び出しで、modelフィールドに使われたadvisorモデル名が入り、そのモデルのレートで課金されます。

トップレベルusageにadvisorの分が入らない理由

上の例でトップレベルのinput_tokens(1760)とoutput_tokens(531)は、2つの"message"イテレーションだけを合計した値です(412+1348=1760、89+442=531)。中間の"advisor_message"イテレーション(input 823・output 1612)はこの合計に含まれていません。

公式ドキュメントは、これを「executor分とadvisor分は異なるレートで課金されるため」と説明しています。もし両方を単純合算すると、合計トークン数だけを見た金額試算が実際の請求額とずれてしまいます。executorのコストを追いたいならトップレベルのusage、advisorを含めた総費用を追いたいならusage.iterationsを自前で集計する、という役割分担です。

executorが複数ターンにわたって会話を継続する構成では、後続のイテレーションのinput_tokensにそれ以前のイテレーションの出力が積み上がっていくため、トップレベルのinput_tokensは単一のプロンプトサイズより大きくなります。上の例でも2つ目の"message"イテレーションのinput_tokens(1348)には、直前までの会話と先行するイテレーションの出力を含む文脈が入っています。コスト集計用のログを組むなら、トップレベルの合計値だけでなくusage.iterationsを1件ずつ見る実装にしておいたほうが、あとから「advisor分だけ抜き出す」といった分析がしやすくなります。

ストリーミングで受けるときは、読む場所にも注意が要ります。advisorのサブ推論はストリームされず、server_tool_useブロックが閉じた時点でexecutorの出力が止まります。結果が届くまでの間は約30秒ごとのpingだけが流れ、advisor_tool_resultは1回のイベントで丸ごと届きます。advisor分のトークン数を含むusage.iterationsは、その後に来るmessage_deltaイベントで更新されます。課金の集計には、ストリーム途中の値ではなく、advisorの後に来るmessage_deltaにあるusage.iterationsを使います。

実例のJSONから実際の費用を計算する

公式のJSON例にexecutorモデルの記載はないため、ここではexecutorをSonnet 5と仮定して、Claude APIの標準料金(Sonnet 5: 入力$2/出力$10 per MTok、Opus 5: 入力$5/出力$25 per MTok)に当てはめます。3つ目の"message"イテレーションが持つcache_read_input_tokens: 412は、トップレベルのinput_tokensに含まれた通常入力ではなく別枠のキャッシュ読み取りなので、試算表でも行を分けます。

この試算では、リクエスト全体の費用のうち約83%をadvisorのサブ推論が占めています。advisorの出力トークン(1,612)がexecutorの出力トークン(531)より多く、Opus 5の出力単価もSonnet 5の2.5倍あるためです。

ただし、この比率だけでadvisorパターンを高コストと決めつけることはできません。コスト面の狙いは、最終出力を低レートのexecutorに書かせることにあります。advisorの出力は典型的には本文400〜700トークン、思考ブロックを含めて1,400〜1,800トークンほどです。上の例の1,612トークンはこの範囲に収まっています。

組み合わせごとの見立ても書かれています。Sonnetをexecutorにして上位モデルをadvisorにする構成では、Opusをadvisorにすると総費用は同程度かそれ以下に収まり、Claude Fable 5.1なら品質の上積みが最大になります。Haikuをexecutorにする構成は、Haiku単体より高くなる一方、executor自体をより大きなモデルに替えるよりは安くなります。結果は課題によって変わるため、自分のワークロードで測る前提です。executorだけの単価感覚で見積もると、advisorの呼び出しが増えるほど請求額との差が開きます。advisorの出力トークン数を抑える具体策はClaude API advisorツールのコスト削減にまとめています。

advisorに指定するモデルを替えると、同じ呼び出しはいくらになるか

advisorの単価はmodelに何を指定するかで決まります。同じトークン数のままadvisor_messageだけ別モデルのレートに掛け替えると、1回の呼び出しの総額は次のように動きます。executorはSonnet 5のままで、executor分は約$0.0089です。

Opus 5.5はOpus 5より単価が低く、単価だけを見れば総額は約17%下がります。Fable 5.1は同じトークン数でも約1.8倍です。

選べるadvisorには制約もあります。advisorはClaude Sonnet 4.6以上で、executor以上の能力を持つモデルでなければなりません。たとえばSonnet 5.5をexecutorにすると、組み合わせられるのはSonnet 5.5・Opus 5・Opus 5.5・Fable 5・Fable 5.1・Mythos 5・Mythos 5.1に限られます。Opus 4.8はSonnet 5.5をexecutorにしたときのadvisorには選べません。

Opus 4.8はOpus 5と同じ入力$5・出力$25で、助言が平文のadvisor_resultで返ります。助言の中身を自分のログで読みたいときは、単価が同じOpus 4.8が候補になります。無効な組み合わせを指定すると、APIは400 invalid_request_errorを返します。

トップレベルmax_tokensとtask budgetは及ばない

executorのリクエストに設定するmax_tokensは、あくまでexecutor自身の出力に対する上限です。advisorのサブ推論の出力トークン数を制限する効果はありません。advisorの出力を制限したい場合は、ツール定義側のmax_tokensを別途設定する必要があります(設定方法と実測の削減率は前段のリンク先にまとめています)。同様に、executorに適用したtask budgetも、advisorのトークン消費には影響しません。executorの予算管理とadvisorのコスト管理は別の設定として扱う必要があります。

ツール定義側のmax_tokensは思考と本文の合計に効く上限で、最小値は1024です。設定すると結果ブロックにstop_reasonが付き、上限に達した呼び出しでは"max_tokens"になります。サーバーは残りのトークン予算もadvisorに渡すので、advisorは出力がその範囲に収まるよう応答を組み立てます。単純な打ち切りだけの仕組みではありません。上限にどれだけ近づいたかは、該当するadvisor_messageのoutput_tokensで見ます。プロンプトで短さを頼む方法と違い、途中で打ち切られる可能性は残ります。保証された上限が必要なときだけツール側のmax_tokensを使う、という分担です。

advisor側のキャッシュを有効にすると請求はどう変わるか

ツール定義にcachingを設定すると、advisor自身のトランスクリプト(会話全体の引用コンテキスト)を会話内でキャッシュできます。仕組みはプロンプトキャッシュと同じで、N回目のadvisor呼び出しのプロンプトは(N-1)回目のプロンプトに1セグメント追記しただけの形になるため、接頭辞が安定して再利用できます。cachingを有効にすると、advisor呼び出しのたびにキャッシュへの書き込みが発生し、次の呼び出しはそこまでの内容をキャッシュ読み取りとして扱い、差分だけを新規入力として支払います。この挙動はusage.iterationsにもそのまま現れ、2回目以降の"advisor_message"イテレーションでcache_read_input_tokensが0でない値になります。プロンプトキャッシュ全般の仕組みはAnthropic APIのPrompt Cachingを理解するで扱っています。

キャッシュ書き込みは、読み取りで節約できる分より高くつくことがあります。会話内のadvisor呼び出し回数で、有効にするかどうかが分かれます。

設定は会話の最初から最後まで一貫させます。途中でオン・オフを切り替えるとキャッシュミスが発生し、余計な費用がかかります。cachingオブジェクトは、コンテンツブロックのcache_controlのような境界マーカーではなく、オン・オフのスイッチです。ttlは"5m"か"1h"で、境界の位置はサーバーが決めます。

キャッシュ読み取りの単価は、advisorに選ぶモデルでも変わります。標準は基準入力単価の0.1倍ですが、Opus 5.5は0.05倍($0.20 / MTok)です。Sonnet 5.5も0.05倍($0.10 / MTok)、Fable 5.1とMythos 5.1は0.025倍($0.25 / MTok)です。同じ呼び出し回数でも、advisorに置くモデルによってキャッシュの回収速度は違ってきます。

もう1点、思考ブロックの保持設定(clear_thinking)でkeepの値を"all"以外にしていると、advisorに渡すトランスクリプトの内容がターンごとに変わり、advisor側のキャッシュが毎回ミスします。これは助言の質そのものには影響しませんが、コストだけが余計にかかる状態です。拡張思考を有効にしていてclear_thinkingを明示していない場合、既定値はkeep: {type: "thinking_turns", value: 1}(思考ターンを1つしか保持しない設定)になります。この既定値が適用されるのはOpus 4.5より前のOpusモデル・Sonnet 4.6より前のSonnetモデル、およびHaiku 4.5を含む全Haikuモデルで、Opus 4.5以降・Sonnet 4.6以降では既定で全ターンを保持するため、この挙動にはなりません。旧世代のOpus/Sonnetやいずれかの世代のHaikuをexecutorに使っていて、かつclear_thinkingを明示していない場合は、意図せずこのコスト劣化を踏んでいることがあります。advisorのキャッシュを効かせたい場合はkeep: "all"を明示しておくと安全です。

Priority Tierはモデルごとに個別適用される

Priority Tier(優先処理の容量コミットメント)を契約している場合も、executorモデルへのコミットメントはadvisorモデルには自動的に及びません。advisor呼び出しがPriority Tierで処理されるのは、組織がadvisorに指定したモデル自体についても別途コミットメントを持っている場合だけです。executorだけPriority Tierを契約し、advisorには契約していない構成では、advisor呼び出しは標準ティアで処理されます。

なおPriority Tierの容量コミットメントは新規購入が終了しており、既存のコミットメントを持つ組織のみ契約期間内で利用を継続できます(Priority Tierの新規購入停止と使い分けの詳細はClaude APIのservice_tierにまとめています)。新規に容量保証を検討する場合は、営業窓口(contact sales)への問い合わせが必要です。

advisorのレート制限は、advisorに指定したモデルへの直接呼び出しと同じモデル別の枠を共有します。どちらが制限に当たったかで、失敗の現れ方が変わります。

advisor側のエラーコードはtoo_many_requestsのほかに6種類あります。max_uses_exceeded(max_usesの上限到達)、overloaded(容量上限)、prompt_too_long(トランスクリプトがadvisorのコンテキストウィンドウ超過)、execution_time_exceeded(タイムアウト)、model_not_found、unavailableです。いずれもリクエスト自体は失敗せず、executorが助言なしで続けます。リトライ戦略を分けるときは、この2種類の経路を別々に扱います。prompt_too_longは長いエージェントループで会話が伸びたときに起きる点が、コストの管理とも関係します。

Priority Tierの容量は、input・outputそれぞれについてトークン種別ごとに異なる倍率で消費されます。キャッシュ読み取りは1トークンあたり0.1トークン分、5分TTLのキャッシュ書き込みは1.25トークン分、1時間TTLのキャッシュ書き込みは2.0トークン分としてカウントされ、通常の入力トークンは等倍です。advisor呼び出しでキャッシュを有効化している場合、Priority Tierはモデルごとに独立して適用されるため、advisor呼び出しの消費はadvisorモデル側の容量で数えます。executorとadvisorの両方でPriority Tierを契約している構成では、容量の消費ペースをモデルごとに別々に監視する必要があります。

コスト集計の実装方針

会話単位・組織単位でadvisorのコストを追跡したい場合、usage.iterationsをtypeで振り分けて自前集計するのが確実な方法です。"advisor_message"のイテレーションだけを取り出し、modelフィールドの値に応じたレートを掛ける処理を1か所に集約しておけば、advisorモデルを途中で切り替えても計算ロジックを変えずに済みます。

集計は、レートの表を1つ持ち、iterationsを1件ずつ足し込む形にします。

RATES = {  # USD / MTok: 入力, 出力, キャッシュ読み取り, 5分キャッシュ書き込み
    "claude-sonnet-5":  (2.0, 10.0, 0.2, 2.5),
    "claude-opus-5":    (5.0, 25.0, 0.5, 6.25),
    "claude-opus-5-5":  (4.0, 20.0, 0.2, 5.0),
    "claude-fable-5-1": (10.0, 50.0, 0.25, 12.5),
}
 
def calc_cost(usage, executor_model):
    total = 0.0
    for it in usage["iterations"]:
        # "message" 型は model が無いので executor のモデル名を使う
        inp, out, read, write = RATES[it.get("model", executor_model)]
        total += (it["input_tokens"] * inp
                  + it["output_tokens"] * out
                  + it["cache_read_input_tokens"] * read
                  + it["cache_creation_input_tokens"] * write) / 1_000_000
    return total

前半の実例のJSONをexecutor_model="claude-sonnet-5"で渡すと約$0.0533になり、上の表の合計と一致します。1時間TTLのキャッシュ書き込みは基準入力単価の2倍なので、使っている場合は書き込みの単価を分けて持ちます。"advisor_message"型はmodelを自身で持つため、advisorを会話の途中で切り替えても、このロジックを変えずに正しいレートが当たります。

ツール定義側のmax_usesは1リクエストあたりのadvisor呼び出し数の上限で、会話全体の上限ではありません。会話単位の予算は、上の手順のとおりクライアント側で数えて制御します。

Claude Managed Agentsのセッションでは、advisorはツール定義ではなくエージェントのロスターに{"type": "advisor", "model": ...}の形で加えます。このエントリにはmax_uses・max_tokens・cachingのオプションがなく、助言はadvisor_tool_resultブロックではなくセッションのイベントストリームにスレッドイベントとして届きます。ここまでのmax_tokensやcachingによる調整は、Messages APIにadvisorツールを直接載せる構成での話です。また、advisorツールはベータ版で、利用できるのはClaude APIとClaude Platform on AWSです。Amazon Bedrock・Google Cloud・Microsoft Foundryでは使えません。

最小構成の実装とツール定義の書き方は別記事にある

tools配列へのadvisor_20260301エントリの書き方や、executorとadvisorの組み合わせ制約そのものはClaude APIのadvisor toolを実装する最小構成にまとめています。advisor_tool_resultの中身が平文になるか暗号化されるかの分岐条件はClaude API advisorツールの結果が暗号化される条件で扱っており、本記事は料金とusage.iterationsの読み方に絞っています。

まとめ

advisorを含む費用は、usage.iterationsをtypeとmodelで振り分けて自前で足すことでしか分かりません。見積もるときはadvisorに選ぶモデルの単価、呼び出し回数(キャッシュの損益分岐は約3回)、ツール側max_tokensの有無の3点を先に決めておくと、請求額とのずれが小さくなります。