# Claude Task Budgets設計——エージェントの費用上限

> Task Budgetsはエージェントループ全体のトークン消費をモデルに伝えるベータ機能です。最小20,000トークン、max_tokensとの違い、設定手順を中小企業向けに整理します。

- Canonical: https://kuucorp.com/blog/claude-task-budgets-advisory-token-cap-smb-guide/
- Date: 2026-10-13
- Last modified: 2026-10-13
- Publisher: Kuu株式会社 (https://kuucorp.com)

---
自社で動かすAIエージェントが、夜間に延々とツールを呼び続けて請求額だけが膨らむ。自走型の業務エージェントを導入した中小企業で起きやすい問題です。`max_tokens`は1回の応答を切る道具で、ループ全体の消費は止められません。この穴を埋めるのが、ベータ提供中のTask Budgetsです。

## Task Budgetsとは何か

> Task Budgetsは、エージェントループ全体で使えるトークン量をClaudeに伝える機能です。最小値は20,000トークンです。

Claudeには残量のカウントダウンが見えており、予算が減るにつれて作業の優先順位を付け、終盤は調査結果の要約などで締めくくります。対象は思考、ツール呼び出し、ツール結果、出力のすべてです。

設定は`output_config`に`task_budget`（`type`は`"tokens"`、`total`に総量）を追加し、ベータヘッダー`task-budgets-2026-03-13`を付けるだけです。64,000トークンの設定例が公式ドキュメントにあります。

## max_tokensやeffortとは何が違うのか

> max_tokensは1リクエストの強制上限、Task Budgetsはループ全体の助言的な目標値です。両者は独立しています。

Task Budgetsは「ソフトな目安」であり、途中で止めるほうが危険な操作中は超過することがあります。費用の天井を保証したい場合は、`max_tokens`を併用してください。

`effort`との役割分担も押さえておきます。effortは各ステップの思考の深さ、Task Budgetsは作業全体の量を調整します。effortの使い分けは[Extended Thinking設計指針](/blog/extended-thinking-adaptive-thinking-design/)も参照してください。

## 予算はいくらに設定すべきか

> 予算は、まず予算なしで実測し、タスク別の消費量のp99を起点に決めます。20,000未満は400エラーです。

手順は次の3段階です。

1. 代表的な業務タスクを予算なしで流し、ループ内の`usage.output_tokens`とツール結果のトークン数を合計する
2. 分布のp99を初期値にして、挙動の変化を確認する
3. 結果を見て上下に調整する

厳しすぎる予算には副作用があります。タスクに対して明らかに足りない場合、Claudeが着手を断る、範囲を絞る、途中で止まるといった挙動を示すことがあります。想定外の拒否や早期終了が出たら、他のパラメータを疑う前に予算を引き上げてください。事前見積もりには[トークン事前カウントAPI](/blog/claude-token-counting-api-preflight-cost-design/)も使えます。

## 運用で注意すべき点は何か

> 予算は初回に1度だけ設定し、毎回書き換えないのが原則です。値を変えるとプロンプトキャッシュが効かなくなります。

運用上の注意は次のとおりです。

- 残量の値はAPIレスポンスに含まれない。自社側の集計が必要なら、ループ内の使用量を足し上げる
- 履歴を毎回再送する構成で`remaining`を自前で減らすと、モデルに過少な残量が見え、早く切り上げてしまう
- 自前で履歴を要約・書き換える場合のみ、消費済み分を差し引いた`remaining`を渡す
- Sonnet 5、Opus 4.6、Sonnet 4.6、Haiku 4.5は非対応。Claude CodeとCoworkでも使えない

反復回数やタイムアウトなど他の制御との組み合わせは[ループ実行制御の設計](/blog/agent-loop-execution-control-budget-timeout/)にまとめています。運用の仕組みづくりは[Kuuの運用管理サービス](https://kuucorp.com/services/ai-ops/)でも支援しています。

## 参考

- [Task budgets — Claude Platform Docs](https://platform.claude.com/docs/en/build-with-claude/task-budgets)
- [Effort — Claude Platform Docs](https://platform.claude.com/docs/en/build-with-claude/effort)

## まとめ

> Task Budgetsは、エージェントの費用暴走を抑える第一歩です。ただしソフト上限なのでmax_tokensとの併用が前提です。

最小20,000トークンから、実測のp99を起点に設定し、`max_tokens`で天井を固めてください。ベータ機能のため仕様は変わりえます。導入設計に迷う場合は、Kuuにご相談ください。