Task budgets (タスク予算)

モデルは残量のカウントダウンを受け取り、それを使って作業の優先順位を付け、予算の消費に合わせて円滑に作業を終えます。予算は強制される上限ではなく、助言的な目安として働きます。

予算の単位は 1 回のエージェントターン (エージェントループ) です。

• ツール結果を含まないユーザーメッセージは、新しい予算で新しいターンを始めます。
• tool_result ブロックを含むユーザーメッセージは、ツール結果と一緒に新しい内容を加えていても、現在のターンの続きとして扱われます。
• ターンの途中でサーバー側の compaction (圧縮) が行われても予算はリセットされず、圧縮前に消費したトークンも数えられます。
• 予算が数えるのは Claude が見るもの (思考、ツール呼び出しと結果、テキスト) で、リクエストのペイロードの中身ではありません。そのため、再送した履歴は二重に数えられません。

カウントダウンはモデルだけが見られます。API のレスポンスに残り予算のフィールドは含まれず、usage オブジェクトにも task_budget の情報はありません。

Task budgets はソフトなヒントであり、強制される上限ではありません。中断するほうが完了させるよりも支障が大きい動作の途中では、Claude が時折予算を超える場合があります。

出力トークン全体に対して強制される上限は、引き続き max_tokens です。上限に達すると、レスポンスは stop_reason: "max_tokens" で打ち切られます。task_budget はエージェントループ全体にかかり、max_tokens は個々のリクエストにかかるため、2 つの値は独立しており、一方を他方以下にする必要はありません。

また、effort は各ステップでどれだけ丁寧に推論するかを調整するもので、Task budgets はエージェントループ全体で Claude が行う作業の総量に上限を設けるものです。

作業に対して明らかに足りない予算を渡すと、Claude がタスクを断る、範囲を大きく絞り込む、または途中の結果で早めに止める場合があります。

予算の水準は、次の流れで決めます。

1. task_budget を設定せずに代表的なタスクを実行し、タスクごとの総トークン数を記録します。エージェントループでは、ループ内のすべてのリクエストの usage.output_tokens と、リクエストの間に追加したツール結果のトークンを合計します。
2. 分布を記録し、タスクあたりの消費量の p99 から始めて、必要に応じて上下に調整して試します。

クライアント側の扱いは、履歴の送り方で変わります。

• 圧縮していない履歴を毎回すべて再送するループでは、remaining を省略し、カウントダウンをサーバーに任せます。
• 自分のコードでリクエストの間に履歴を圧縮・書き換える場合は、次のリクエストで remaining を渡し、カウントダウンが total に戻らずに続くようにします。圧縮前に消費したトークンは、履歴から取り除いたメッセージ分の使用量として計算し、送信するメッセージに残っているもの (追加した要約を含む) は除きます。この値は履歴を置き換えたときだけ更新し、リクエストごとに減らさず、圧縮したリクエストだけでなく以後のすべてのリクエストで渡します。

タスクの途中で予算を変えるには、次のリクエストの output_config に新しい task_budget を設定します。値を変えると、古い値で作られたキャッシュのエントリとは一致しません。prompt caching を保つには、最初のリクエストで予算を一度だけ設定し、クライアント側で変更せずに、モデルがサーバー側のカウントダウンに沿って自己調整するようにします。

Task budgets はベータとして提供されており、利用にはベータヘッダー task-budgets-2026-03-13 が必要です。対応モデルとして Claude Opus 4.7 と Claude Opus 4.8 があります。対象プランや提供地域は、公式のリリースノートには記載がありません。

リクエストには task-budgets-2026-03-13 ベータヘッダーを含めます。

1. リクエストの output_config に task_budget を追加し、ベータヘッダーを含めます。
2. task_budget の type を "tokens" にします。この値は常に "tokens" です。
3. total に、エージェントループ全体 (思考・ツール呼び出し・ツール結果・出力) で Claude が使えるトークン数を指定します。受け付けられる最小値は 20,000 トークンで、これより小さい値は 400 エラーになります。