タスク予算

タスク予算を使用すると、思考、ツール呼び出し、ツール結果、出力を含む完全なエージェントループに対してClaudeが使用できるトークン数を指定できます。モデルは実行中のカウントダウンを確認し、それを使用して作業を優先順位付けし、予算が消費されるにつれて適切に終了します。

タスク予算を使用する場合

タスク予算は、Claudeが複数のツール呼び出しと決定を行ってから最終出力を確定するエージェントワークフローに最適です。以下の場合に使用してください：

• Claudeが長期的なタスクのトークン支出を自己調整するようにしたい場合。
• タスクごとの予測可能なコストまたはレイテンシー上限を実施したい場合。
• モデルが予算に近づくにつれて適切に終了（結果の要約、進捗の報告）するようにしたい場合。

タスク予算はeffortパラメータを補完します：effortは各ステップについてClaudeがどの程度徹底的に推論するかを制御し、タスク予算はエージェントループ全体でClaudeが実行できる総作業量を制限します。

タスク予算の設定

output_configにtask_budgetを追加し、ベータヘッダーを含めます：

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-4-7",
    max_tokens=128000,
    output_config={
        "effort": "high",
        "task_budget": {"type": "tokens", "total": 64000},
    },
    messages=[
        {"role": "user", "content": "Review the codebase and propose a refactor plan."}
    ],
    betas=["task-budgets-2026-03-13"],
)

task_budgetオブジェクトには3つのフィールドがあります：

• type：常に"tokens"です。
• total：思考、ツール呼び出し、ツール結果、出力を含むエージェントループ全体でClaudeが支出できるトークン数。
• remaining（オプション）：前のリクエストから引き継がれた予算の残り。省略された場合はtotalがデフォルトになります。

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

Claudeは会話全体を通じてサーバー側で注入された予算カウントダウンマーカーを確認します。マーカーは現在のエージェントループに残っているトークン数を表示し、モデルが思考、ツール呼び出し、出力を生成し、ツール結果を処理するにつれて更新されます。Claudeはこの信号を使用して自分のペースを調整し、予算が消費されるにつれて適切に終了します。

実例：ターン間での予算カウント

タスク予算は、リクエストペイロードにあるものではなく、Claudeが確認するもの（思考、ツール呼び出しと結果、テキスト）をカウントします。エージェントループでは、クライアントがすべてのリクエストで完全な会話を再送信するため、ペイロードはターンごとに増加しますが、予算は今回Claudeが確認するトークンによってのみデクリメントされます。

task_budget: {type: "tokens", total: 100000}と単一のbashツールを持つループを考えてみてください。

ターン1。 初期リクエストを送信します：

{
  "messages": [
    { "role": "user", "content": "Audit this repo for security issues and report findings." }
  ]
}

Claudeは思考してからツール呼び出しを発行し、stop_reason: "tool_use"で停止します：

{
  "role": "assistant",
  "content": [
    {
      "type": "thinking",
      "thinking": "I'll start by listing dependencies to look for known-vulnerable packages..."
    },
    {
      "type": "tool_use",
      "id": "toolu_01",
      "name": "bash",
      "input": { "command": "cat package.json && npm audit --json" }
    }
  ]
}

このアシスタントターン（思考とツール呼び出し）が合計5,000生成トークンであると仮定します。生成中にClaudeが確認したカウントダウンはremaining ≈ 95,000の近くで終了しました。

ターン2。 クライアントはツールを実行し、ツール結果を追加した完全な履歴を再送信します：

{
  "messages": [
    { "role": "user", "content": "Audit this repo for security issues and report findings." },
    {
      "role": "assistant",
      "content": [
        { "type": "thinking", "thinking": "I'll start by listing dependencies..." },
        {
          "type": "tool_use",
          "id": "toolu_01",
          "name": "bash",
          "input": { "command": "cat package.json && npm audit --json" }
        }
      ]
    },
    {
      "role": "user",
      "content": [
        {
          "type": "tool_result",
          "tool_use_id": "toolu_01",
          "content": "<2,800 tokens of npm audit output>"
        }
      ]
    }
  ]
}

再送信されたターン1のユーザーとアシスタントメッセージは再度カウントされませんが、2,800トークンのツール結果は今回Claudeが確認する新しいコンテンツであり、予算に対してカウントされます。Claudeは思考に別の4,000トークンを費やし、2番目のツール呼び出し（grep -rn "eval(" src/）を行います。カウントダウンはremaining ≈ 88,200の近くで終了します。

ターン3。 2番目のツール結果（1,200トークンのgrep出力）が追加された完全な履歴が再送信されます。Claudeは6,000トークンの最終結果レポートを作成し、stop_reason: "end_turn"で停止します。remaining ≈ 81,000。

3つのターンを並べて配置すると、ペイロードサイズと予算支出の区別が明確になります：

クライアントはターン1のユーザーメッセージを3回、ターン1のアシスタントメッセージを2回送信しましたが、それぞれは1回カウントされました。予算は100,000トークンのうち19,000を費やしました。クライアントが送信した累積ペイロードはより大きく、ターン2と3のプロンプトキャッシュ入力はさらに大きかったにもかかわらずです。

remainingを使用した圧縮間での予算の引き継ぎ

エージェントループがリクエスト間でコンテキストを圧縮または書き直す場合（たとえば、以前のターンを要約することで）、サーバーは圧縮前に費やされた予算の量を記憶していません。次のリクエストでremainingを渡して、totalにリセットするのではなく、カウントダウンが中断した場所から続行するようにしてください：

すべての圧縮されていない履歴をすべてのターンで再送信するループの場合、remainingを省略し、サーバーがカウントダウンを追跡するようにしてください。

タスク予算は勧告的であり、強制されません

タスク予算はハードキャップではなくソフトヒントです。Claudeは、中断するよりも終了する方が破壊的な場合、予算を超える可能性があります。総出力トークンに対する強制制限は依然としてmax_tokensであり、到達時にstop_reason: "max_tokens"で応答を切り詰めます。

コストまたはレイテンシーのハードキャップの場合、タスク予算と合理的なmax_tokens値を組み合わせます：

• task_budgetを使用してClaudeがペースを調整するターゲットを提供します。
• max_tokensを使用して、暴走生成を防ぐ絶対上限として機能します。

task_budgetは完全なエージェントループ（潜在的に多くのリクエスト）にわたるのに対し、max_tokensは各個別リクエストを制限するため、2つの値は独立しており、1つが他方以下である必要はありません。

予算の選択

適切な予算は、エージェントループが現在実行する作業量によって異なります。推測するのではなく、まず既存のトークン使用量を測定してから、そこから調整してください。

現在の使用量を測定する

task_budgetを設定せずに代表的なタスクサンプルを実行し、タスクごとにClaudeが費やす総トークン数を記録します。エージェントループの場合、ループ内のすべてのリクエストにわたってusage.output_tokensと思考およびツール結果トークンを合計します：

代表的なタスクセット全体でこれを実行し、分布を記録します。タスクごとのトークン支出のp99から始めて、モデルにタスク予算を提供することがモデルの動作をどのように変更するかを理解し、必要に応じて上下でテストしてください。

最小受け入れtask_budget.totalは20,000トークンです。最小値より低い値は400エラーを返します。

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

• max_tokens： タスク予算に直交します。max_tokensは生成トークンに対するリクエストごとのハードキャップであり、task_budgetは完全なエージェントループ全体（潜在的に多くのリクエストにわたる）に対するアドバイザリキャップです。xhighまたはmax effortで、max_tokensを少なくとも64kに設定して、Claudeが各リクエストで思考と行動するための余地を与えてください。
• Effort： Effortはステップごとにどの程度深くClaudeが推論するかを制御します。タスク予算はエージェントループ全体でClaudeが実行する総作業量を制御します。2つは補完的です：effortは深さを調整し、タスク予算は幅を調整します。
• 適応的思考： タスク予算は思考トークンをカウントに含めるため、適応的思考は予算が枯渇するにつれて自然にスケールダウンします。
• プロンプトキャッシング： 予算カウントダウンマーカーはターンごとにサーバー側で注入されるため、リクエスト間で一致しません。クライアントが各フォローアップリクエストでtask_budget.remainingをデクリメントする場合、変更された値はそれを含むキャッシュプレフィックスを無効にします。キャッシングを保持するには、初期リクエストで予算を一度設定し、クライアント側で予算を変更するのではなく、モデルがサーバー側のカウントダウンに対して自己調整するようにしてください。

機能サポート

タスク予算は起動時にClaude CodeまたはCowork表面でサポートされていません。Claude Opus 4.7でMessages API経由でタスク予算を直接使用してください。