マルチエージェントAgent SDK の料金確認｜トークン使用量の正しい数え方
この記事の要点
- Agent SDK は呼び出しの最後の結果メッセージに、料金の見積もり（total_cost_usd）とトークン使用量をまとめて返す
- 見積もりは手元の価格表で計算した目安で、請求額そのものではない。請求や支払いの判断には使わない
- サブエージェント込みで数えるならモデル別の内訳を使う。途中のメッセージは同じIDを1回だけ数え、出力トークンは結果から読む
活用例：社内で動かす AI エージェントの利用料を部署ごとに把握する
- 部署
- 情報システム・経営企画
- 使うもの
- Claude Agent SDK
- AIに任せる
- 作業の実行と、呼び出しごとの使用量・見積もりの記録
- 人が決める
- 予算の上限・請求の確認・どの業務に回すか
AI エージェントを業務で動かし始めると、すぐに出てくるのが「で、いくらかかったの？」という質問です。Claude Agent SDK の全体像は Claude Agent SDK とは で解説しました。
この記事では、公式ドキュメント「Track cost and usage」（2026年11月8日確認）にもとづいて、Agent SDK で料金の見積もりとトークン使用量を確認する方法 と、数え間違えやすいポイントを整理します。
結論：最後の結果を読めば合計がわかる。ただし「見積もり」
Agent SDK は、1回の呼び出しが終わるときに 結果メッセージ を返します。そこに、その呼び出しで使った 料金の見積もり（total_cost_usd）とトークン使用量 が入っています。合計だけ知りたいなら、この1つの値を読めば足ります。
| 知りたいこと | 見る場所 |
|---|---|
| 1回の呼び出しの料金（目安） | 結果メッセージの total_cost_usd |
| サブエージェント込みのトークン | 結果メッセージのモデル別の内訳（modelUsage・Python は model_usage） |
| 1往復ごとの入力トークン | 途中の AI のメッセージの usage（同じ ID は1回だけ数える） |
| 出力トークン | 結果メッセージの usage（途中の値は仮の数字） |
| キャッシュの効き具合 | cache_creation_input_tokens・cache_read_input_tokens |
大事な注意があります。 total_cost_usd などの金額は、SDK が手元の価格表を使って計算した 見積もり です。価格の変更、SDK が知らないモデル、手元では再現できない請求のルールがあると、実際の請求額とずれます。公式は、この値で利用者に請求したり、お金の判断をしたりしないように と書いています。正確な請求額は、組織の利用料の管理画面で確認します。
数える単位は「呼び出し」「1往復」「セッション」の3つ
料金を正しく読むには、どの範囲の数字なのか を区別するのが先です。公式は3つの単位で説明しています。
| 単位 | 中身 | 料金の数字 |
|---|---|---|
| 呼び出し | query() を1回呼ぶこと。中で何往復もする | 最後に結果メッセージが1つ出る |
| 1往復（ステップ） | AI が答える→道具を使う→結果を受け取る、の1回 | AI のメッセージごとに使用量が付く |
| セッション | 再開（resume）でつないだ複数の呼び出し | 再開した呼び出しの結果は、それまでの分も含む |
TypeScript と Python で数字の中身は同じで、違うのは項目名と置き場所だけ です。たとえば Python では、AI のメッセージの使用量を message.usage、モデル別の内訳を model_usage で読みます。Python では合計の項目が「無いこともある」型になっているので、空でないか確かめてから読みます。
サブエージェント込みで数えるならモデル別の内訳
子の AI（サブエージェント）を使う場合、結果メッセージの3つの数字は、子の分を含むかどうかが違います。
| 項目 | 子の分 |
|---|---|
| usage | 含まない。親の分だけ |
| total_cost_usd | 含む |
| modelUsage・model_usage | 含む。モデルごとに分かれる |
そのため、子を使うときにトークンを数えるなら、モデル別の内訳を使います。 usage だけを見ると、子が増えた分だけ少なく出ます。なお、終わりの時点で裏の子がまだ動いている場合は、待った分も結果の数字に入ります。子の作り方や、子が増えすぎないようにする上限の付け方は Agent SDK のサブエージェント で解説しています。
モデル別の内訳には、入力・出力・キャッシュの読み書きのトークン数と金額が入ります。たとえば「親は高いモデル、子は軽いモデル」と分けたとき、どこにトークンが流れているか がひと目でわかります。各モデルには、どの価格表で計算したかを示す costBasis も付き、価格表に無いモデルは unknown と出ます。
1往復ごとに数えるときの2つの落とし穴
途中のメッセージから自分で数える場合は、同じ ID の重複と、出力トークンの仮の数字 に気をつけます。
1つ目は重複です。AI が1回のターンで複数の道具を同時に使うと、同じ ID・同じ使用量を持つメッセージが複数 流れてきます。そのまま足すと二重に数えてしまうので、すでに数えた ID は飛ばします。公式の例では、子の中から出たメッセージも除いて、親の分だけを数えています。
2つ目は出力トークンです。途中のメッセージに入っている出力トークンは、答えを書き始める前の時点の仮の数字 です。本当の出力の数は、最後の結果メッセージに入ります。
| 数えたいもの | 途中のメッセージ | 最後の結果 |
|---|---|---|
| 入力トークン | 重複を除けば正確 | 使える |
| キャッシュのトークン | 重複を除けば正確 | 使える |
| 出力トークン | 仮の数字なので使わない | こちらを使う |
複数回の呼び出しを合計する
何回も呼び出す場合、足すか、最新を読むかは「同じセッションかどうか」で決まります。
- それぞれ独立した呼び出し：結果はその呼び出しの分だけ。自分で足していく
- 同じセッションを再開した呼び出し：結果に、それまでの分も入っている。最新の結果を読む。足すと二重になる
1回の呼び出しで何度も話しかける「ストリーミング入力モード」では、話しかけるたびに結果が出ます。このとき total_cost_usd とモデル別の内訳は その時点までの合計 なので、最新の結果を読みます。ただし、会話をリセットする /clear・/reset・/new を送ると合計が0から数え直しになります。その場合は、リセット直前の結果と最後の結果を足します。
失敗したとき・落ちたときの数え方
途中で失敗しても、そこまでのトークンは使っています。 結果メッセージは成功でも失敗でも金額を持っているので、すべての結果から読み取ります。
ただし、数字が少なく出る場合があります。
- 金額の上限で止まったとき：usage には上限を超えた最後の1回が入らない。total_cost_usd とモデル別の内訳には入る
- 処理そのものが落ちたとき：最後の結果の数字がすべて0になることがある
そのため、公式は できるだけ total_cost_usd かモデル別の内訳で数える よう勧めています。落ちたときは、ひとつ前の結果の合計を使うか、それも無ければ途中のメッセージの使用量を足して、親の入力とキャッシュの分だけを取り戻します（子の分・出力・金額はこの方法では戻りません）。
キャッシュのトークンも分けて見る
Agent SDK は、くり返し送る内容に プロンプトキャッシュを自動で使います。 自分で設定する必要はありません。使用量には、次の2つの数字が別に入ります。
- cache_creation_input_tokens：新しくキャッシュに書き込んだ分。通常の入力より高い
- cache_read_input_tokens：キャッシュから読んだ分。通常の入力より安い
API キーなどで使う場合、キャッシュは既定で5分で切れます。同じ指示で短い作業を5分以上あけて何度も回すなら、環境変数 ENABLE_PROMPT_CACHING_1H で1時間にできます。ただし 1時間の書き込みは5分より高い ので、読み出しが増える使い方のときに効きます。キャッシュの仕組みそのものは Claude Code のプロンプトキャッシュ で解説しています。
仕事に入れるときの考え方
業務で使うときは、「記録は SDK の見積もり、請求の確認は管理画面」と役割を分ける のが基本です。
- 呼び出しごとに、結果メッセージの total_cost_usd とモデル別の内訳を記録する（部署・業務名と一緒に）
- サブエージェントを使う業務では、金額の上限（maxBudgetUsd・max_budget_usd）を先に決めておく
- 月末は管理画面の請求額と見比べ、ずれが大きければ SDK の版や価格表を確かめる
Claude Code 全体の料金の考え方は Claude Code の料金、利用状況を継続して見える化する方法は Claude Code のモニタリング も参考にしてください。
まとめ
- 料金とトークンは 最後の結果メッセージ を読めばわかる。ただし金額は 見積もり で、請求額ではない
- サブエージェント込みなら モデル別の内訳。途中のメッセージは 同じ ID を1回だけ 数え、出力トークンは結果から読む
- 再開したセッションは最新の結果を読み、失敗時は total_cost_usd かモデル別の内訳で数える
出典
この記事はAIを使って下書きし、著者が事実確認・加筆しています。ツールの機能や料金は変わることがあるため、最新の情報は各社の公式ページでご確認ください。
