メインコンテンツまでスキップ

タスク予算 — エージェントを優雅に終わらせる助言的トークン上限

上級
What you'll learn
  • タスク予算とは何かを理解する — エージェントループ全体にわたる、モデルに見える助言的なトークンのカウントダウン
  • task_budget を正しく設定する — output_config 内に、task-budgets-2026-03-13 ベータヘッダーを付け、サポートされるモデルで
  • 実際に予算にカウントされるもの（このターンで Claude が見るトークン）と、されないもの（再送された履歴の繰り返しペイロード）を読み解く
  • 拒否のような挙動を引き起こすのではなく助けになる予算サイズを選ぶ — まず計測し、それから余裕を持って設定する
  • remaining フィールドでコンパクション（圧縮）をまたいで予算を引き継ぎ、プロンプトキャッシュ無効化の罠を避ける
  • タスク予算、セッション予算、effort、max_tokens を区別する — 4 つのレバー、4 つの異なる役割

長期間動くエージェントは、外からは予測しにくい形でトークンを消費します。思考とツール呼び出しを十数ラウンド繰り返すことになった 1 つのリクエストが、通常のターンの 10 倍のコストを静かに生むことがあります。タスク予算は Anthropic の答えです：エージェントループ全体に対する助言的なトークン上限を Claude に渡し、モデルに自己調整させます — 思考のペースを配分し、アクションに優先順位を付け、予算が尽きるにつれて要約で締めくくる。max_tokens によってツール呼び出しの途中で切断されるのではなく。

タスク予算が、すでに知っている他のあらゆるコストレバーと異なる点は 2 つあります：

  • カウントダウンはモデルに見えます。 Claude はサーバー側で挿入される「残りトークン」のマーカーを見て、それに基づいて挙動を調整します。クライアントは usage フィールドでこのマーカーを見ることはありません。
  • 強制ではなく助言的です。 タスク予算はソフトなヒントであり、ハードキャップは依然として max_tokens です。これは仕様です — 進行中のアクションを中断する方が完了させるより破壊的な場合、Claude は時折予算を超過することがあります。

予算カウントダウンの仕組み​

カウントダウンは、リクエストペイロードのサイズではなく、このループで Claude が処理したトークン — 思考、ツール呼び出し、ツール結果、出力 — を反映します。クライアントが毎ターン会話全体を再送する場合、ペイロードは単調に増加しますが、予算はこのターンで Claude にとって新しい分だけ減少します。

Watch out
  • カウントダウンはモデルにのみ見えます。API レスポンスには残り予算のフィールドは含まれません — usage に task_budget のエントリはなく、SDK のアクセサもありません。クライアント側で消費を追跡するには、ループ内のリクエスト全体で output_tokens を合計してください。
  • クライアントがすべてのフォローアップで全履歴を送信し、かつその際に remaining を減算すると、モデルは過少に報告された予算を見て、予算が実際に許す時点より早く締めくくってしまいます。余裕のある予算を設定し、サーバー側のカウントダウンに対してモデルに自己調整させてください。

最初の予算付きリクエストを送る​

Guided walkthrough1 of 4
  1. リクエストに anthropic-beta: task-budgets-2026-03-13 を追加します。これがないと output_config.task_budget は無視されます。

最小のリクエスト — コードベースレビューエージェントを 64k トークンに予算設定

curl https://api.anthropic.com/v1/messages \
-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}
  }
}'

実際にサポートしているモデル​

モデルサポート
Claude Opus 5ベータ — task-budgets-2026-03-13 を設定
Claude Fable 5ベータ — task-budgets-2026-03-13 を設定
Claude Mythos 5ベータ — task-budgets-2026-03-13 を設定
Claude Sonnet 5非サポート
Claude Opus 4.8ベータ — task-budgets-2026-03-13 を設定
Claude Opus 4.7ベータ — task-budgets-2026-03-13 を設定
Claude Opus 4.6非サポート
Claude Sonnet 4.6非サポート
Claude Haiku 4.5非サポート

タスク予算は Claude Code や Cowork のサーフェスではサポートされていません — サポートされるモデルの 1 つで、Messages API を通じて直接使用してください。代わりに Managed Agents セッションに対する金額のハードキャップが必要な場合、それは別の機能です：Managed Agents セッション予算。

予算を選ぶ — 推測せず、まず計測する​

適切な予算は、ループが現在どれだけの作業を行っているかに依存します。Anthropic 自身の推奨：まず計測し、それから調整する。

Guided walkthrough1 of 3
  1. サンプル内の各タスクについて、ループ内のすべてのリクエストにわたる usage.output_tokens の合計に、リクエスト間で追加したツール結果のトークンサイズを加えます。それがモデルが見た合計です。
Watch out
  • タスクに対して小さすぎる予算は、拒否のような挙動を引き起こすことがあります。Claude が明らかに作業に不十分な予算（たとえば、数時間かかるエージェント型コーディングタスクに 20,000 トークン）を見た場合、完了できない作業を始めるのではなく、タスクの試行を断る、大幅にスコープを縮小する、部分的な結果で早期に停止するといったことがあります。
  • 予算を追加した後に予期しない拒否や早すぎる停止を観察したら、他のパラメーターをデバッグする前に予算を上げてください。固定のデフォルトではなく、実際のタスク長の分布に対してサイズを決めてください。

コンパクションをまたいで予算を引き継ぐ​

ループがリクエスト間でコンテキストをコンパクション（圧縮）または書き換える場合 — たとえばペイロードを小さくするために以前のターンを要約する場合 — サーバーはコンパクション前に消費した予算を記憶していません。次のリクエストで remaining を渡し、カウントダウンが中断した地点から続くようにします：

Python — コンパクションをまたいで remaining を引き継ぐ

# Tokens spent before compaction, tracked client-side
tokens_spent_so_far = 45000

output_config = {
  "effort": "high",
  "task_budget": {
      "type": "tokens",
      "total": 128000,
      "remaining": 128000 - tokens_spent_so_far,
  },
}

毎ターン、圧縮していない全履歴を再送するループでは remaining を省略し、サーバーにカウントダウンを追跡させてください。必要がないのに手動で設定すると、クライアントが消費したと考える量と Claude が実際に見た量との間にずれが生じます。

他のパラメーターとの相互作用​

相互作用の相手どう相互作用するか
max_tokens直交。 max_tokens はリクエスト単位のハードキャップ、task_budget はループ全体にわたる助言的な上限です。どちらかが他方以下である必要はありません。組み合わせて使います：task_budget は Claude にペース配分の目標を与え、max_tokens は個々のリクエストでの暴走生成を防ぎます。
Effort補完的。 effort はステップごとに Claude がどれだけ深く推論するか（思考の幅）を制御します。タスク予算はループ全体でどれだけの作業ができるか（反復の幅）を制御します。両方を一緒に調整してください。
適応的思考タスク予算は思考トークンをカウントに含むため、予算が減るにつれて適応的思考は自然にスケールダウンします。
プロンプトキャッシュキャッシュ無効化の罠。 予算カウントダウンのマーカーはターンごとに挿入され、リクエスト間で一致しません。クライアントがフォローアップごとに task_budget.remaining を減算すると、変更された値がそれを含むキャッシュプレフィックスを無効化します。最初のリクエストで一度だけ予算を設定し、モデルに自己調整させてください。

タスク予算と他の予算の比較​

Ailmanac はすでに 3 つの「予算」型の機能を扱っています。これらは交換可能ではありません。

機能単位スコープ強制必要なヘッダー
タスク予算（このページ）トークン1 つのエージェントループ（複数リクエストになることも）助言的 — モデルへのソフトなヒントanthropic-beta: task-budgets-2026-03-13
max_tokensトークン1 つのリクエストハード — stop_reason: max_tokens で切り詰めるなし
output_config.efforteffort レベルステップごとの深さ助言的（モデルが制御）なし
Managed Agents セッション予算米セントManaged Agents セッション全体ハード — budget_reached でサーバーが一時停止Managed Agents のベータヘッダー

こう考えてください：max_tokens はヒューズ（決まった点で切れる）、タスク予算は Claude にスコアを囁くコーチ（プレーを調整する）、effort はプレースタイル、セッション予算は給与上限を執行する会計係です。境界があり、自己調整し、金額に上限のあるエージェントが必要なときは、4 つすべてを一緒に使ってください。

理解度テスト​

Check yourself

0/3
  1. コードベース監査エージェントで task_budget.total を 100000 に設定しました。実行中、毎ターン全履歴を再送するため、クライアントの累積ペイロードはリクエスト全体で 250000 トークンに達しました。終了時に Claude が見るカウントダウンはどうなっていますか？
  2. リクエスト間でコンテキストをコンパクションしています。カウントダウンがリセットされないようにするには、何をしますか？
  3. 長いエージェント型コーディングタスクに task_budget.total を 20000 に設定したところ、Claude が突然拒否したり、部分的な結果で早期に停止したりします。修正方法は？

用語集​

タスク予算の用語集
Enter キーまたはスペースキーでカードを裏返します。左右の矢印キーでカードを移動できます。用語を表示しました。
1 / 6

まとめ​

Key takeaways
  • タスク予算は、エージェントループ全体にわたるモデルに見える助言的なトークンのカウントダウン — Claude はそれに対して自己調整する
  • サポートされるモデル — Opus 5、Fable 5、Mythos 5、Opus 4.8、Opus 4.7 — で task-budgets-2026-03-13 ベータヘッダーを付けてオプトインする。Sonnet、Haiku、Claude Code はサポートしていない
  • カウントダウンは再送されたペイロードのサイズではなく、このターンで Claude が見るトークンをカウントする — したがって繰り返しの履歴は二重に課金されない
  • まず計測し（タスクごとのトークン分布の p99）、それから余裕を持って設定する。小さすぎる予算は拒否のような挙動を引き起こす
  • コンパクションをまたいで予算を引き継ぐには remaining を使う。圧縮していない履歴を再送する場合は省略し、サーバーに追跡させる
  • ハードなヒューズとして max_tokens と、ステップごとの深さを調整する effort と組み合わせる — 4 つのレバーが 4 つの異なる役割を担う

次のステップ​