タスクバジェット

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



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

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

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

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



タスクバジェットの設定

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

client = anthropic.Anthropic()

with client.beta.messages.stream(
    model="claude-opus-4-8",
    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にリセットされるのではなく、中断したところから継続されます。

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

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



タスクバジェットは助言的であり、強制ではありません

タスクバジェットはソフトなヒントであり、ハードな上限ではありません。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に思考トークンとツール結果トークンを加えて合計します。

def run_task_and_count_tokens(messages: list) -> int:
    """Runs an agentic loop to completion and returns total tokens spent."""
    total_spend = 0
    while True:
        with client.beta.messages.stream(
            model="claude-opus-4-8",
            max_tokens=128000,
            messages=messages,
            tools=tools,
            betas=["task-budgets-2026-03-13"],
        ) as stream:
            response = stream.get_final_message()
        # このターンでClaudeが生成した分をカウントします（出力はテキスト + 思考 + ツール呼び出しを含みます）。
        # ツール結果のトークンも予算にカウントされます。クライアント側の追跡を
        # サーバー側のカウントダウンと一致させたい場合は、以下で追加する
        # tool_resultブロックのトークン数を加算してください。
        total_spend += response.usage.output_tokens
        if response.stop_reason == "end_turn":
            return total_spend
        # アシスタントのターンとツール結果を追加し、ループを続行します。
        messages += [
            {"role": "assistant", "content": response.content},
            {"role": "user", "content": run_tools(response.content)},
        ]

これを代表的なタスクセット全体で実行し、分布を記録します。タスクごとのトークン消費の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を通じて直接タスクバジェットを使用してください。