タスクバジェット

「task budget」（タスクバジェット）を使用すると、思考、ツール呼び出し、ツール結果、出力を含むエージェントループ全体で使用できるトークン数をClaudeに伝えることができます。モデルは実行中のカウントダウンを確認し、それを使って作業の優先順位を付け、バジェットが消費されるにつれて適切に終了します。



タスクバジェットを使用するタイミング

タスクバジェットは、Claudeが次の人間の応答を待つ前に出力を確定するまでに複数のツール呼び出しと判断を行うエージェントワークフローに最適です。次のような場合に使用してください。

• 長期的なタスクにおいてClaudeにトークン消費を自己調整させたい場合。
• タスクごとに予測可能なコストまたはレイテンシの上限を適用したい場合。
• バジェットに近づいたときに、アクションの途中で打ち切られるのではなく、モデルに適切に終了（調査結果の要約、進捗の報告）させたい場合。

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



タスクバジェットの設定

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

client = anthropic.Anthropic()

with client.beta.messages.stream(
    model="claude-opus-5",
    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"],
) as stream:
    response = stream.get_final_message()

print(response.usage)

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は思考と2回目のツール呼び出し（grep -rn "eval(" src/）にさらに4,000トークンを消費します。カウントダウンはremaining ≈ 88,200付近で終了します。

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

3つのターンを並べて比較すると、ペイロードサイズとバジェット消費の違いが明確になります。

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



remainingを使用してコンパクション間でバジェットを引き継ぐ

エージェントループがリクエスト間でコンテキストをコンパクションまたは書き換える場合（たとえば、以前のターンを要約するなど）、サーバーはコンパクション前にどれだけのバジェットが消費されたかを記憶していません。次のリクエストでremainingを渡すことで、カウントダウンがtotalにリセットされるのではなく、中断したところから継続されます。

# 圧縮前に消費されたトークン数（クライアント側で追跡）
tokens_spent_so_far = 45000

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

ターンごとにコンパクションされていない履歴全体を再送信するループの場合は、remainingを省略し、サーバーにカウントダウンを追跡させてください。



会話の途中でバジェットを変更する

task_budgetはリクエストレベルの設定です。タスクの途中でバジェットを変更するには（たとえば、ユーザーがリクエストの範囲を広げたときに延長する場合）、次のリクエストのoutput_configに新しいtask_budgetを設定します。キャッシングへの影響に注意してください。バジェット値はレンダリングされたプロンプトに含まれるため、変更された値は古い値で作成されたキャッシュエントリと一致しません（下記の機能サポートを参照）。



タスクバジェットは参考値であり、強制ではありません

タスクバジェットはソフトなヒントであり、ハードな上限ではありません。Claudeは、中断するよりも完了させる方が混乱が少ないアクションの途中である場合、バジェットを超過することがあります。出力トークンの合計に対する強制的な制限は依然としてmax_tokensであり、これに達するとstop_reason: "max_tokens"でレスポンスが切り捨てられます。

コストまたはレイテンシにハードな上限を設けるには、タスクバジェットと適切なmax_tokens値を組み合わせてください。

• task_budgetを使用して、Claudeにペース調整の目標を与えます。
• max_tokensを、暴走的な生成を防ぐ絶対的な上限として使用します。

task_budgetはエージェントループ全体（複数のリクエストにまたがる可能性がある）を対象とし、max_tokensは個々のリクエストに上限を設けるため、2つの値は独立しています。一方が他方以下である必要はありません。



バジェットの選択

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



現在の使用量を測定する

task_budgetを設定せずに代表的なタスクのサンプルを実行し、Claudeがタスクごとに消費する合計トークン数を記録します。エージェントループの場合、ループ内のすべてのリクエストのusage.output_tokensと、リクエスト間で追加するツール結果のトークンを合計します。

client = anthropic.Anthropic()

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（テキスト + 思考 + ツール呼び出し）を合計します。
print(response.usage.output_tokens)

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

受け入れられるtask_budget.totalの最小値はモデル固有です。現在タスクバジェットをサポートしているすべてのモデル（機能サポートを参照）では20,000トークンであり、最小値未満の値は400エラーを返します。



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

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



機能サポート

タスクバジェットはClaude CodeやCoworkサーフェスではサポートされていません。サポートされているモデルでMessages APIを通じて直接タスクバジェットを使用してください。



次のステップ