Claudeのtask_budgetとは？max_tokensと費用上限の違い

task_budgetは一連の作業を配分するための目安

task_budgetはモデルが考える過程、ツールへの指示、ツールが返す結果、最終回答を含む一連の処理にトークン予算を与えます。Claudeはサーバー側から示される残量を見ながら、何を先に調べ、どこで回答をまとめるかを調整します。[1]

例えば、コードを調べて改修案を出す作業なら、検索を際限なく広げず、得られた情報を基に途中までの成果をまとめることが期待されます。これは機能の狙いを説明する例であり、設定した量で必ず完了するという保証ではありません。

公式資料はこの予算を助言的なものと位置づけています。処理を途中で切るより終えた方がよいとモデルが判断する場合などには、設定値を超えることがあります。予算を渡しただけで、追加の生成やツール実行を確実に防げるとは考えないでください。[1]

max_tokensと費用上限は、どう違うか？

max_tokensは1回のAPIリクエストで生成するトークン数の強制上限です。到達すると、応答はstop_reasonがmax_tokensとなって打ち切られます。一方、task_budgetは複数のリクエストにまたがる作業全体の目安です。対象の範囲が違うため、2つの数値の大小をそろえる必要はありません。[1]

設定・仕組み	何を制御するか	残る課題
task_budget	一連の作業に使うトークン量の目安	設定量を超える場合がある
max_tokens	1リクエストで生成するトークン数	次のリクエストやツールの実行は別に制御する
アプリ側の実行制御	リクエスト回数、許可する操作、実行時間など	使用量・単価・外部ツール料金に合わせて設計する

下段は編集部による実装上の整理です。例えば、1回の出力を制限しても、アプリが次のAPI呼び出しを繰り返せば作業は続きます。金額の上限を管理したい場合は、入力や出力などの課金量と、その時点の単価を基にした集計も必要です。task_budgetの残量は請求金額の残高とは別のものです。

設定はoutput_configに置く

公式資料ではoutput_config内にtask_budgetを置き、ベータヘッダーtask-budgets-2026-03-13を付ける方法を示しています。totalに指定できる最小値は20,000トークンで、それより小さい値は400エラーになります。[1]

次は設定部分だけを示したJSONです。認証、モデル、入力メッセージなどを含む完全なリクエストではなく、編集部でのAPI実行結果でもありません。64,000は構造を示す例であり、すべての仕事に適した推奨値ではありません。

{
  "output_config": {
    "task_budget": {
      "type": "tokens",
      "total": 64000
    }
  }
}

typeはtokensを指定します。totalが全体の目安で、remainingは必要な場合に残量を引き継ぐための省略可能な項目です。対応モデルかどうかと、必要なベータ指定を確認してから組み込んでください。[1]

remainingを毎回減らすと、二重に差し引くことがある

ツールの結果を追加しながら会話の全履歴を再送する通常の処理では、公式資料はremainingを省略し、サーバー側のカウントに任せるよう案内しています。同じ履歴を送り直した量を毎回予算から引くわけではありません。[1]

ここでアプリも独自にremainingを減らすと、モデルに実際より少ない残量を伝え、作業を早く終わらせてしまう場合があります。入力として送った累計量と、その作業で新たに処理した量を混同しないことが重要です。

remainingが必要になる例は、アプリ自身が古い会話を要約して履歴を作り直す場合です。削除した履歴で使った分を引き継ぎ、まだ送信する履歴や追加した要約を重ねて差し引かないようにします。具体的な計算と、以後のリクエストへの渡し方は公式の履歴圧縮の説明に従ってください。[1]

また、APIのusageにはtask_budgetの残量フィールドが返りません。SDKにも、その残量を直接取得するための機能はないとされています。「レスポンスの残量を読み、そのまま次へ渡す」という前提で実装しないようにしてください。[1]

Claude Codeの設定と混同しない

10月21日確認の対応表では、Opus 4.7・4.8、Opus 5・5.5、Fable 5・5.1などがベータ機能の対象です。一方、Opus 4.6やSonnet 4.6、Haiku 4.5は非対応と記載されています。モデル名が近くても、すべてに同じ設定を渡せるわけではありません。[1]

同じ資料はClaude CodeおよびCoworkではtask budgetsに対応せず、対応モデルのMessages APIを通じて使うよう明記しています。これはアプリの設定ファイルへJSONを足せば有効になる、という説明ではありません。[1]

導入時にはまず代表的な作業で現在の使用量と完了状況を記録し、その分布を見て予算を調整する方法が公式に示されています。予算が小さすぎると、作業を断るような挙動や、範囲の縮小、途中結果での終了が起こり得ます。単に数値を下げるだけでは、必要な品質を保った節約になるとは限りません。[1]

まとめ

• task_budgetは複数回のツール利用を含む作業量の目安です。設定量を超える可能性があり、金額の強制上限にはなりません。
• max_tokensは1リクエストの生成上限です。作業全体を止める条件や費用の集計は、アプリ側でも設計する必要があります。
• 全履歴を再送する通常の処理ではremainingを独自に減らし続けません。対応モデルとベータ指定を確認し、Messages APIで扱います。

出典・参考

1. Anthropic「Task budgets」（2026年10月21日確認）