Claude API のタスクバジェット（task budget）は、エージェントのループ全体で使ってよいトークン量をモデル自身に伝える機能です。モデルは残量のカウントダウンを見ながら作業を組み立てるため、途中で強制的に打ち切られるのではなく、限られた予算のなかで優先順位を付けて着地させようとします。本記事はベータ機能の仕様を日本語で整理した非公式の解説です。
タスクバジェットとは何か
タスクバジェットは、思考・ツール呼び出し・最終出力を合わせた1つのエージェント的なループに対して、「このタスクにはこれだけのトークンを使ってよい」という総量を渡す仕組みです。サーバー側が生成中のモデルにカウントダウンの目印を差し込むため、モデルは残りの予算を認識しながら進めます。
重要なのは、これが強制的な上限ではなく、モデルが認識できる目安だという点です。予算が厳しすぎるとタスクの仕上がりが浅くなり、モデルは「予算が制約だった」と述べることがあります。逆に十分な予算を渡せば、モデルは調査に時間を掛けたうえで最後にまとめる、といった配分ができます。
カウントの対象は、そのターンでモデルが生成したトークンと、そのターンで読み込んだツール結果です。毎回のリクエストで送り直している会話履歴の全体は含まれません。
max_tokens との違い
max_tokens と混同しやすいので、違いを整理します。
max_tokensは1回のレスポンスに対する強制的な上限です。到達した時点で出力は打ち切られ、stop_reasonはmax_tokensになります。そしてモデルはこの値を知りません。task_budgetはループ全体に対する目安です。モデルはこの値と残量を知っており、それを前提に作業を配分します。
つまり max_tokens は「ここで切る」という壁、task_budget は「ここまでで終わらせて」という依頼です。両方を併用できます。使い分けの目安としては、支出の上限を機械的に固定したいときは max_tokens、モデルに自分でペース配分させたいときは task_budget です。
実際のリクエストの書き方
output_config のなかに task_budget を置き、ベータフラグ task-budgets-2026-03-13 を付けてベータ版のメッセージエンドポイントを呼びます。max_tokens を大きく取るため、ストリーミングを使うのが前提です。非ストリーミングだと HTTP のタイムアウトに掛かります。
with client.beta.messages.stream(
model="claude-opus-5",
max_tokens=128000,
output_config={
"effort": "high",
"task_budget": {"type": "tokens", "total": 64000},
},
betas=["task-budgets-2026-03-13"],
messages=[...],
tools=[...],
) as stream:
response = stream.get_final_message()task_budget のフィールドは3つです。type は常に "tokens"、total が総量、remaining は任意で、省略すると total と同じ値になります。
remaining は通常のループでは指定しません。サーバー側がカウントダウンを管理しているためで、履歴を毎回送り直しながらクライアント側で計算した remaining を渡すと、予算の消費が実際より少なく見積もられます。指定するのは、途中で履歴を圧縮したり書き換えたりして、サーバーが過去の消費を追えなくなったときだけです。
進捗を画面に出したい場合は、ループの各回で response.usage.output_tokens と、自分が追加したツール結果ブロックのトークン数を足し込んでいく形になります。
対応モデルと制限
対応モデルは Claude Opus 5、Claude Fable 5、Claude Sonnet 5、Claude Opus 4.8、Claude Opus 4.7 です。ベータ機能であり、利用にはベータフラグ task-budgets-2026-03-13 が要ります。
task_budget.total の最小値は 20,000 トークンです。これを下回る値は指定できません。
提供面にも制限があります。Amazon Bedrock、Google Vertex AI、Microsoft Foundry では利用できません。第三者プラットフォーム向けのコードを書くときは、この機能を外した設計にしてください。
使いどころと注意点
向いているのは、ツールを何度も呼ぶ長時間のエージェント処理です。調査、コードベースの横断的な変更、複数ファイルにまたがる作業など、どこまで掘るかをモデルが判断する種類のタスクで効きます。逆に、1往復で終わる分類や抽出のようなタスクでは、max_tokens だけで十分です。
注意点を3つ挙げます。
- 値に確信がないまま導入しない。 予算が小さすぎるとタスクの完成度が下がります。実際のワークロードを計測できるなら計測してから決め、できないなら導入を急がないほうが安全です。
- 効率化の主役ではない。 1ターンあたりの深さを調整するのは
effortです。task_budgetはループ全体の累積を扱うもので、役割が違います。 - 残量の表示はモデルに見せる情報である。 残りトークン数を過度に意識させると、モデルが早めに切り上げようとすることがあります。作業を最後までやり切らせたい場面では、予算を十分に取ってください。
本記事は Anthropic の公式仕様に基づく非公式の日本語解説です。ベータ機能のため、フラグ名や仕様は変更される可能性があります。実装前に公式ドキュメントで最新の内容をご確認ください。