Claude Agent SDKはプランの利用上限を消費するか
サブスクリプション経由のClaude Agent SDKとclaude -pはプランの利用上限を消費します。2026年6月に予告された専用クレジット化がなぜ撤回されたのか、APIキー経由との違いも含めて解説します。
Claude Agent SDKの利用はプランの利用上限を消費する
Claude Agent SDKを自分のClaudeサブスクリプション(Pro・Max・Team・Enterprise)で認証して使う場合、その消費は対話的なClaude CodeやClaude、Coworkと同じプラン利用上限から差し引かれます。Agent SDK専用の別枠はありません。claude -p(Claude Codeの非対話モード)や、Agent SDKで認証するサードパーティ製アプリも同じ扱いです。対話的な利用との共有を前提に、上限そのものの仕組みを知りたい場合はClaude Codeの利用上限が参考になります。
利用上限の状態変化はCLIがrate_limit_eventメッセージで通知します。Python SDKの旧バージョンでは、受信時にMessageParseErrorで停止する不具合もありました(詳細)。
認証方法で消費の行き先が変わる
サブスクリプションで認証
対話的なClaude Code・Cowork・チャットと同じプラン利用上限から消費されます。上限に達すると、同じプランの対話利用にも響きます。
APIキーで認証
最初から従量課金(pay-as-you-go)です。プランの利用上限とは無関係で、この記事の話は当てはまりません。
専用クレジット化は撤回された
この現状には経緯があります。Anthropicは2026年6月15日から、Agent SDKとclaude -pの消費をサブスクリプションの利用上限から切り離し、代わりに月次の専用クレジットを付与する変更を予告していました。ところが同じ日付で、この変更を一旦停止すると発表しています。
公式サポート記事の冒頭には「現時点では何も変わっていません」という趣旨の更新注記があり、Agent SDK、claude -p、サードパーティアプリの利用は引き続きサブスクリプションの利用上限から消費されると明記されています。予告されていた月次クレジットも、対象になり得たユーザーに提供されません。変更前の説明は参考情報として同じページに残っていますが、発効はしていません。
予告から一旦停止まで
- 2026年6月14日まで利用上限から消費
Agent SDKと
claude -pは、サブスクリプションの利用上限から消費されていました。 - 2026年6月15日(予告)専用の月次クレジットへ分離
利用上限から切り離し、プラン別の月次クレジットで賄う案が示されました。
- 2026年6月15日(一旦停止)発効せず据え置き
分離は始まらず、利用上限からの消費が続いています。
Anthropicは、サブスクリプションでの開発をより良く支える形にプランを更新する作業を進めているとし、発表の際は発効前に周知するとしています。SDK自体の使い方やセットアップはClaude Agent SDK入門で扱っています。
一旦停止された専用クレジット案の中身
発効しなかった案の設計を見ておくと、今後同種の変更が出たときに読み解きやすくなります。予告されていたのは、プランごとに額が違う月次クレジットをAgent SDK専用に付与する仕組みでした。
| プラン | 予告されていた月次クレジット |
|---|---|
| Pro | 予告されていた月次クレジット$20 |
| Max 5x | 予告されていた月次クレジット$100 |
| Max 20x | 予告されていた月次クレジット$200 |
| Team(標準シート) | 予告されていた月次クレジット$20 |
| Team(プレミアムシート) | 予告されていた月次クレジット$100 |
| Enterprise(従量課金制) | 予告されていた月次クレジット$20 |
| Enterprise(座席制・プレミアムシート) | 予告されていた月次クレジット$200 |
座席制Enterpriseの標準シートは対象外でした。クレジットはユーザー単位で、チーム内のプールや共有はできません。請求サイクルごとにリセットされ、未使用分は繰り越されない設計でした。使い切った後の扱いは使用量クレジットの設定で分かれ、有効なら標準APIレートでの課金に移り、無効なら次のサイクルまでAgent SDKのリクエストが止まります。
対象に挙がっていたのは、自分のプロジェクトでのAgent SDK利用、claude -p、Claude Code GitHub Actions連携、Agent SDKで認証するサードパーティ製アプリです。GitHub Actions連携もこの案の対象でしたが、案は発効していません。一旦停止の告知文が挙げているのはAgent SDK、claude -p、サードパーティ製アプリで、GitHub Actionsには直接触れていません。対話的なClaude Code・Cowork・チャットの利用は、この案でも従来どおり利用上限を使う設計でした。
Agent SDKが返すコスト推定値は目安であって請求額そのものではない
Agent SDKは各query()呼び出しの結果メッセージに、累計のtotal_cost_usdを返します。モデル別の内訳はTypeScriptがmodelUsage[].costUSD、Pythonがmodel_usageです。公式ドキュメントは、これらの値を、クライアント側の見積もりであって正式な請求データではないと位置づけています。
SDKはビルド時に組み込まれた価格表(またはmodelPricing設定)からローカルで計算しているだけです。価格改定、SDKが未対応の新モデル、クライアント側で再現できない請求ルールがあると、実際の請求額とずれます。契約単価を見積もりに反映する設定はmodelPricingの使い方で扱っています。
SDKがモデル化している請求ルールの1つに、データレジデンシー価格があります。レスポンスのusageがinference_geo: "us"を返すと、そのレスポンスのトークンの定価に1.1倍を掛けます(TypeScript Agent SDK v0.3.239以降、Python Agent SDK v0.2.144以降が対象)。Web検索のようなリクエスト単位の追加料金は、この倍率の対象外です。
開発時の目安や大まかな予算感覚には使えます。正式な請求額はUsage and Cost APIかConsoleのUsageページで確かめるのが確実で、この推定値だけでエンドユーザーへの課金や財務判断をしてはいけない、と公式ドキュメントは注意しています。集計の実装はAgent SDK Cost Trackingにあります。
利用上限に近づくと、キャッシュの有効期間も変わる
サブスクリプションの含まれる利用量の範囲内では、自分のターンと一部の補助リクエストのプロンプトキャッシュは、環境変数を設定しなくても1時間のTTL(有効期間)になります。公式ドキュメントによると、使用量クレジットを使い始めた時点で、Claude Codeはそのターンを5分のTTLに落とします。APIキー認証では既定が5分で、1時間にするにはENABLE_PROMPT_CACHING_1Hを設定します。promptCacheTtlを1hにするか、環境変数CLAUDE_CODE_PROMPT_CACHE_TTLに1hを指定すれば、使用量クレジットに移った後も1時間のキャッシュを保てます。効くのはメインの会話のターンだけで、サブエージェントなどはsubagentPromptCacheTtlで別に決めます。前提はClaude Code v2.1.242以降です。
間隔の長い短時間セッションを何本も回す自動化では、このTTLの差がキャッシュ書き込みのやり直しに響きます。利用上限を使い切って使用量クレジットに移った時点で、同じジョブの単価が上がり得る点は、プランの余裕を見積もるときに頭に入れておくとよい条件です。
max_budget_usdで使いすぎを事前に防ぐ
共有の利用上限を圧迫しすぎないための手段が、max_budget_usd(TypeScriptではmaxBudgetUsd)です。query()に渡しておくと、推定コストが指定額に達した時点で実行が止まり、結果メッセージのResultMessage.subtypeがerror_max_budget_usdになります。見積もりである以上は厳密な請求額と一致しませんが、暴走したループが利用上限を一気に食いつぶす事態を防ぐ安全弁になります。
公式ドキュメントによると、この予算が数えるのはその呼び出し自身の支出だけです。再開したセッションから復元された合計は含まれず、/clearで予算は最初からになります。resumeを重ねる運用では、呼び出しごとに予算が新しくなるので、全体の上限としては働きません。
もう1つ、error_max_budget_usdで終わった結果では、usageが予算を超えた最後のレスポンスを含みません。total_cost_usdとmodelUsageは含みます。失敗した呼び出しの消費を数えるときは、usageではなく後者の2つを見ます。
サブエージェントの消費は見えにくい
サブエージェントを組み合わせると、消費の見え方に注意が必要です。結果メッセージの3つのフィールドは、サブエージェント分の扱いが違います。
| フィールド | サブエージェントの分 |
|---|---|
usage | サブエージェントの分含まない(最上位のエージェントループだけ) |
total_cost_usd | サブエージェントの分含む |
modelUsage(Pythonはmodel_usage) | サブエージェントの分含む(モデル別の内訳つき) |
usageだけを見ていると、サブエージェントを多用する構成ほど実際の消費を過小評価します。ツリー全体を把握するならmodelUsageかtotal_cost_usdが基準です。
サブエージェントは自分でさらにサブエージェントを起動できるため、1回の指示がエージェントの木に育つことがあります。共有の利用上限を消費する構成では、成長を先に絞っておけます。
サブエージェントの増え方を3つの設定で絞る
- 1
入れ子の深さを決める
環境変数
CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTHで指定します。既定は主エージェントの下に3層で、1にするとサブエージェントは自分ではサブエージェントを起動しません。 - 2
同時に動く数を決める
環境変数
CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTSで指定します。既定は20で、上限に達するとConcurrent subagent limit reachedが返ります。 - 3
支出の上限を決める
max_budget_usdを使います。サブエージェントのリクエストも合算され、上限に達すると新規起動をBudget limit reachedで断り、動いているバックグラウンドのサブエージェントも止めます。
深さと同時実行数の設定は、TypeScript SDK v0.3.219以降、Python SDK v0.2.127以降(Claude Code v2.1.219以降を同梱するリリース)が前提です。それより前は一部の上限がなく、既定値も違います。
上限に達したときの実際のつまずき
利用上限まわりの挙動は、SDKのイシューにも報告されています。cost-trackingのページには、上限到達時の待機や再開の手順は載っていません。自分の環境で起き得るかを見る材料になります。
- TypeScript SDKのイシュー#403では、
rate_limit_eventを受け取ったあとにストリームが閉じられても、query()の非同期イテレーターが終了せずfor awaitが止まり続けたと報告されています。外部のタイムアウトを持たない呼び出し側は、無期限に待つことになります - 同じくTypeScript SDKのイシュー#456は、セッションの利用上限に達したとき、ターミナルのCLIが出す「低い優先度で続ける」の選択肢に、非対話・SDKのセッションからは到達できないという要望です。上限で止まったSDKジョブを自動で再開する構成が組めない、という文脈で挙がっています
どちらも報告された時点の話で、修正されたかどうかはイシューの状態で変わります。長時間回すジョブでは、rate_limit_eventを受けたら自前の時間切れで打ち切る実装にしておくと、無期限に止まる事態を避けられます。
Team・Enterprise管理者の判断材料
組織でAgent SDKを使うかどうかは、次の2点で切り分けられます。
- 対話利用への影響: サブスクリプション経由のAgent SDK利用は、対話的な利用と同じプランの利用上限から引かれます。本番で常時Agent SDKを回すなら、対話利用を圧迫しないようAPIキー課金で見積もる方が、コストを予測しやすくなります
- 用途の規模: 一旦停止された案のクレジットは、個人の実験・自動化向けの大きさで設計されていました。チームで共有する本番の自動化には、Claude PlatformのAPIキーによる従量課金が向く、というのが公式の整理です
組織の消費プール全体の管理はClaude Enterpriseの消費管理、Team・座席制Enterpriseで含まれる利用量を使い切った後の使用量クレジットはClaude Teamの使用量クレジットに書いています。
まとめ
サブスクリプション認証のAgent SDKとclaude -pは、対話利用と同じ利用上限を食います。判断の軸は、そのジョブが対話利用と上限を分け合ってよいかどうかです。分け合えない本番の自動化はAPIキー課金で見積もり、分け合う場合はmax_budget_usdと深さ・同時実行数の上限を先に決めます。専用クレジット化は一旦停止の段階なので、大きな自動化を組む前にサポートページの更新注記も見ておくと安全です。