Agent SDK は各 query() の結果メッセージにコスト情報を載せます。ただしその数字は請求データそのものではなく、二重計上・過小計上・ゼロ化といった落とし穴があります。本稿は 2026-09-16 時点の公式ドキュメントで検証済みの仕様に絞り、コストを正しく読み取り集計するための要点を整理します。
コスト値の性質とローカル計算
total_cost_usd と costUSD はクライアントサイドの推計値であり、正式な請求データではありません。SDK はビルド時にバンドルされた価格テーブルからこれらの値をローカルで計算します。したがって表示される金額は目安であり、確定金額は別途の請求データで確認する前提で扱います。
データレジデンシー課金
レスポンスの usage に inference_geo: "us" が報告される場合、SDK はそのレスポンスのトークン定価に 1.1 を乗算します。この対応には TypeScript Agent SDK v0.3.239 以降、または Python Agent SDK v0.2.144 以降が必要です。
トークン集計の注意点
Claude が 1 ターンで複数のツールを並列使用すると、そのターンの全メッセージが同一の ID を共有します。ID で重複排除しないとトークン集計が水増しされます。また、アシスタントメッセージの per-step output_tokens はプレースホルダーであり、正確な出力トークン数はリザルトメッセージから読み取る必要があります。
サブエージェントと集計
サブエージェント（ネスティング）が存在する場合、usage フィールドはトークンを過小計上します。一方 total_cost_usd はサブエージェントのリクエストをトップレベルのループと合算して計上します。金額はサブエージェント込み、usage のトークン数は本体のみ、という非対称に注意します。
modelUsage と costBasis
リザルトメッセージの modelUsage フィールドは、モデル名をキーとし、モデルごとのトークン数とコストをマッピングするオブジェクトです。各エントリは costBasis フィールド（値は list / managed / unknown）を持ちますが、このフィールドは Claude Code v2.1.246 以降でのみ利用可能です。
プロンプトキャッシング
Agent SDK はプロンプトキャッシングを自動的に使用するため、手動でキャッシュを設定する必要はありません。usage オブジェクトには cache_creation_input_tokens（標準入力トークンより高い料金）と cache_read_input_tokens（割引料金）の 2 フィールドが含まれます。
API キー認証、Amazon Bedrock、Google Cloud の Agent Platform、Microsoft Foundry、AWS 上の Claude Platform で実行する場合、キャッシュエントリのデフォルト TTL は 5 分です。環境変数 ENABLE_PROMPT_CACHING_1H を設定すると書き込み TTL を 1 時間に延長できますが、1 時間 TTL の書き込みは 5 分 TTL より高い料金で課金されます。TTL はメインの会話が CLAUDE_CODE_PROMPT_CACHE_TTL（または promptCacheTtl）、それ以外が CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL（または subagentPromptCacheTtl）で制御できます。
エラー時と予算リセット
セッションクラッシュ時に発行される error_during_execution リザルトでは、全コストフィールドがゼロになる可能性があります。error_max_budget_usd エラー時は、usage フィールドは予算を超過したレスポンスを除外しますが、total_cost_usd と modelUsage はそのレスポンスを含みます。
streaming input モードで /clear を送信すると running total がリセットされ、maxBudgetUsd（Python では max_budget_usd）の予算カウントも同時にリセットされます。Python SDK v0.2.137 より前では ConversationResetMessage がイテレータから欠落するため、/clear ターンの回数を自前でカウントする必要があります。
セッション合計の自前集計
SDK はセッション全体の累計コストを提供しません。複数の query() 呼び出しにわたるコストは、アプリケーション側で自前集計する必要があります。