task_budgetは強制上限でなくadvisoryという性質

task_budgetは「必ず守られる上限」ではない

task_budgetはadvisory(強制されない助言的な指定)であり、予算が小さすぎるとrefusal-likeな挙動(依頼を断る・スコープを縮める・途中で打ち切る)が起きます。

task_budget(ベータ)はエージェントループ全体で使えるトークン数をClaudeに伝える機能です。誤解されやすいのは、これをmax_tokensと同じ「ハードな上限」だと思い込むことです。公式ドキュメントは明確にtask_budgetはソフトなヒントであり強制上限ではないと定義しています。Claudeは、中断するより完了させたほうが影響が小さいと判断した作業の途中であれば、予算を超えることがあります。出力トークンの総量に対する強制的な上限は今でもmax_tokensが担い続けており、これに達するとstop_reason: "max_tokens"でレスポンスが打ち切られます。

コストや遅延に対するハードな上限が必要な場合は、task_budgetと適切なmax_tokensを組み合わせます。task_budgetはClaudeがペース配分の目安にする数値、max_tokensは暴走的な生成を止める絶対的な天井、という役割分担です。task_budgetはエージェントループ全体(複数リクエストにまたがりうる)にかかり、max_tokensは個々のリクエストにかかるため、両者は独立した値であり、どちらかがどちらかを下回っている必要もありません。

どういう場面でtask_budgetを使うべきか

task_budgetが向くのは、Claudeが最終出力を返すまでに複数回のtool callと判断を経るエージェント型のワークフローです。具体的には次のような場面で有効です。

• 長時間かかるタスクでClaude自身にトークン消費のペース配分を任せたい場合
• タスクごとのコストや待ち時間の上限をある程度予測可能にしたい場合
• 予算を使い切りそうなタイミングで、作業を中途半端に打ち切るのではなく、それまでの調査結果を要約して区切りよく報告してほしい場合

一問一答で完結するリクエストや、tool callを伴わない単発の生成には向きません。エージェントループが1回のユーザー入力に対して何往復もリクエストを重ねる構成で初めて、予算の効果が意味を持ちます。

予算が小さすぎるとrefusal-likeな挙動が起きる

task_budget運用で最も見落とされがちな副作用がこれです。明らかに作業量に対して不十分な予算を見せられたとき、Claudeはタスクへの着手そのものを断る、大幅にスコープを縮小する、あるいは完了させられない見込みの作業なら始める前に途中経過だけを返して打ち切る、といった振る舞いを取ることがあります。例えば数時間かかるエージェント型のコーディングタスクに20,000トークンの予算を設定するようなケースです。

もしtask_budgetを設定した後に「想定外のrefusal」や「早すぎる打ち切り」が起きたら、まず疑うべきは他のパラメータではなく予算の大きさです。予算を先に引き上げてから、他の原因を探すのが正しい順序です。固定のデフォルト値を決め打ちするのではなく、実際のタスクの長さの分布に合わせて予算を設計する必要があります。

なお、「早すぎる打ち切り」はクライアント側の実装が原因で起きることもあります。詳しくは後述の「Compaction併用時に予算を引き継ぐremaining」を参照してください。

予算が小さすぎるとrefusal-likeな挙動が出た場合の対処に固定の倍率はありません。まず実測手順(次節のp99の消費量)で妥当な水準を出し、そこから予算を段階的に上げながらrefusal-likeな挙動が消えるかを確認するのが安全です。予算を極端に大きくしすぎるとペース配分の効果自体が薄れるため、実測値からかけ離れた値を最初から設定しないことが前提になります。

実測ベースで予算を決める手順

task_budgetを設定せずに代表的なタスクのサンプルを実行し、タスクごとの合計トークン消費を記録します。エージェントループであれば、ループ内のすべてのリクエストでusage.output_tokensを合計し、リクエスト間で受け渡すtool resultのトークン数も加えます。

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    messages=[{"role": "user", "content": "Review the codebase and propose a refactor plan."}],
)
 
# output_tokens(テキスト・thinking・tool callを含む)をループ内の全リクエストで合計する
print(response.usage.output_tokens)

代表的なタスク集合でこれを実行し、分布を記録します。まずp99(上位1%)の消費量を起点に予算候補を決め、そこから上下に調整しながらモデルの振る舞いへの影響を見ていくのが公式の推奨手順です。中央値ではなくp99から始める理由は、平均的なタスクに合わせた予算では、長めのタスクが前段の「refusal-likeな打ち切り」に引っかかりやすくなるためです。

task_budget.totalの最小受理値はモデルによらず一律20,000トークンで、これより小さい値を指定すると400エラーになります。

task_budgetの設定方法

output_configにtask_budgetを追加し、ベータヘッダーを付けます。

curl https://api.anthropic.com/v1/messages \
  -N \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: task-budgets-2026-03-13" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-5",
    "max_tokens": 128000,
    "stream": true,
    "messages": [{
      "role": "user",
      "content": "Review the codebase and propose a refactor plan."
    }],
    "output_config": {
      "effort": "high",
      "task_budget": {"type": "tokens", "total": 64000}
    }
  }'

effortパラメータとの役割分担にも注意します(effortの使い分け全般はClaude effortとはを参照)。effortはClaudeが各ステップをどれだけ丁寧に推論するかを制御し、task_budgetはエージェントループ全体でこなせる作業量に天井を付けます。xhighやmaxのeffortを使う場合、max_tokensは少なくとも64k程度を確保し、Claudeが各リクエストで考え・行動する余地を残すことが推奨されています。

task_budgetを会話の途中で変更する

task_budgetはリクエスト単位の設定です。ユーザーの要求が広がって予算を伸ばしたい場合など、途中で予算を変えるには次のリクエストのoutput_configに新しいtask_budgetを渡します。ここで注意すべきはキャッシュへの影響です。予算の値はレンダリングされるプロンプトの一部として扱われるため、値を変えると古い予算で作られたキャッシュエントリとは一致しなくなります。

キャッシュとの相性はもう一段深いところにも影響します。予算のカウントダウンマーカーはリクエストごとにサーバー側で注入されるため、そもそもリクエスト間で完全には一致しません。加えて、クライアント側でtask_budget.remainingを毎リクエスト減らして送ると、その値を含むキャッシュプレフィックスがそのたびに無効化されます。キャッシュを保ちたい運用では、最初のリクエストで一度だけ予算を設定し、以降はクライアント側で値を書き換えずサーバー側のカウントダウンに任せるのが公式の推奨です。頻繁に予算を変更する運用では、この再キャッシュコストも織り込んで設計します。

Compaction併用時に予算を引き継ぐremaining

長時間のエージェントループでは、呼び出し側が独自にメッセージ履歴を圧縮(compaction)することがあります。サーバー側はcompaction以前にどれだけ予算を消費したかを覚えていないため、そのままでは次のリクエストで予算のカウントダウンがtotalにリセットされてしまいます。この引き継ぎにはremainingフィールドを使い、totalから使用済みトークン数を引いた値を次のリクエストに渡すことで、カウントダウンを圧縮前の続きから再開できます。Compaction自体の発動しきい値の考え方はCompactionの発動しきい値の決め方、一時停止と組み合わせる運用はCompactionの一時停止で合計トークン予算を強制する実装パターンにまとめています。

remainingを使うべきなのは、独自にcompactionを行い会話履歴を圧縮しているループだけです。通常のエージェントループ、つまり毎回のリクエストで会話履歴をまるごと再送する構成では、remainingは渡さずサーバー側のカウントダウンに任せてください。履歴を再送しながらクライアント側でremainingを独自に減らしてしまうと、Claudeが見る予算の残量が実際より少なく報告され、カウントダウンが本来より速く減っていきます。結果として、予算がまだ十分残っているにもかかわらず、Claudeが作業を早めに切り上げてしまいます。これは前述の「予算が小さすぎるとrefusal-likeな挙動が起きる」節で説明した早すぎる打ち切りの直接の原因になりうるため、compactionを自前で実装していないならremainingには触れないのが安全です。

予算は「送信したペイロード」ではなく「Claudeが見た新規分」だけ減る

task_budgetの消費量を誤解しやすいポイントがもう一つあります。エージェントループでは、クライアント側は毎回のリクエストで会話履歴全体を再送します。ペイロードのサイズはリクエストのたびに膨らみますが、予算が減るのはClaudeが新しく見た分(生成したトークンと、まだ見ていないtool result等)だけです。以前のリクエストで送った内容が再送されても、二重にカウントされることはありません。

task_budgetはthinkingトークンも消費に含めるため、予算が減っていくにつれてadaptive thinkingの深さも自動的にスケールダウンします。長いエージェントループの後半で推論が浅くなったように感じる場合、原因の一つはこの予算の残量です。

公式ドキュメントの実例では、100,000トークンの予算で3リクエストからなる1ターンを検証しています。

送信した累計ペイロードは約20,820トークンですが、予算から実際に減ったのは19,000トークンだけです。この違いを知らずに「送信量ベース」で予算消費を見積もると、実際より早く予算切れになると誤解し、必要以上に大きな予算を設定してしまいがちです。

「1ターン」の区切りとCompactionをまたぐときの扱い

予算がカバーする範囲は1つのエージェントターン(agentic turn)です。tool resultを含まないユーザーメッセージは新しいターンを開始し、予算はそこでリセットされます。ただし、現状ではそのリセット後も、それ以前のターンの履歴がコンテキストに残っている間は、カウントダウンの計算にその履歴分が引き続き数えられます。逆にtool resultを含むユーザーメッセージは、同じターンの継続として扱われます。ターンの途中でサーバーサイドCompactionが発生しても予算はリセットされず、そのターンでCompaction以前に消費した分は引き続きカウントされます。ターン開始前の履歴がCompactionで要約された場合、その要約対象だった分は今回のターンの予算にはカウントされません。ただしこの「カウントされない」扱いは、あくまでサーバーサイドCompactionをまたいで引き継がれる予算に限った話です。要約を挟まず単に前のターンの履歴が残っているだけの場合は、上で述べたとおり引き続きカウントに含まれます。

task_budgetの対応モデルと制約

task_budgetはベータ機能で、ベータヘッダーはtask-budgets-2026-03-13です。対応・非対応はモデルごとに分かれます。

Claude CodeやCoworkの利用面ではtask_budgetは使えません。使う場合はMessages APIを対応モデルへ直接呼び出す実装が前提になります。エージェントが複数回のtool callと判断を経て最終出力に至るような、長時間の自律タスクを対象とした設計であり、単発の一問一答的なリクエストで使う機能ではありません。