タスクバジェット

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

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

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

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

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

タスクバジェットの設定

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

client = anthropic.Anthropic()

with client.beta.messages.stream(
    model="claude-opus-5-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はこのシグナルを使ってペースを調整し、バジェットが消費されるにつれて適切に作業を終えます。

ターンとしてカウントされるもの

予算は1つのエージェントターン（エージェントループとも呼ばれます）を対象とします。これは、ツール結果を含まない1つのユーザーメッセージに応答してClaudeが行うすべての処理です。1つのターンは複数のリクエストにまたがることがあります。

ツール結果を含まないユーザーメッセージは、新しい予算で新しいターンを開始します。現時点では、以前のターンの履歴がコンテキストに残っている間は、カウントダウンはその履歴も引き続きカウントします。よくあるケースは、Claudeがターンを終了した後（たとえば予算が尽きたため）のフォローアップです。

{ "role": "user", "content": "Continue." }

tool_resultブロックを含むユーザーメッセージは、現在のターンを継続します。これは、クライアントがそのターンの一部であるツール呼び出しを解決しているためです。

{
  "role": "user",
  "content": [
    { "type": "tool_result", "tool_use_id": "toolu_01", "content": "<npm audit output>" }
  ]
}

これは、メッセージがツール結果と並んで新しいコンテンツを追加する場合でも同様です。

{
  "role": "user",
  "content": [
    { "type": "tool_result", "tool_use_id": "toolu_01", "content": "<npm audit output>" },
    { "type": "text", "text": "Also check the Dockerfile." }
  ]
}

ターン中のサーバー側の「compaction」（コンパクション）はバジェットをリセットしません。コンパクション前にそのターンで消費されたトークンは、引き続きバジェットに対してカウントされます。ターン開始前のトークンは、ターン開始時のコンパクションでそれらが要約された場合でもカウントされません。現時点では、この除外はサーバー側のコンパクションをまたいで引き継がれるバジェットにのみ適用されます。以前のターンの履歴は、コンテキストに残っている間は引き続きカウントされます。

具体例：リクエスト間での予算のカウント

タスク予算は、リクエストのペイロードに含まれるものではなく、Claudeが見るもの（思考、ツール呼び出しと結果、テキスト）をカウントします。エージェントループでは、クライアントがリクエストのたびに会話全体を再送信するためペイロードは増え続けますが、予算は新しい分だけ、つまりClaudeが生成するトークンと、Claudeがまだ見ていないコンテンツの分だけ減少します。次の例は、3つのリクエストで構成される1つのエージェントターンです。最初のリクエストはユーザーメッセージを含み、続く2つのリクエストはそれぞれツール結果を追加した履歴を再送信します。

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は思考と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つのリクエストを並べると、ペイロードサイズと予算消費の違いが明確になります。

クライアントは元のユーザーメッセージを3回、最初のアシスタントメッセージを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は、コンパクションを行うリクエストだけでなく、すべてのリクエストで渡してください。

リクエストのたびにコンパクションされていない履歴全体を再送信するループでは、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-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は深さを、タスク予算は幅を調整します。
• 適応型思考： タスク予算は思考トークンもカウントに含めるため、予算が減るにつれて「adaptive thinking」（適応型思考）の量も縮小されます。
• プロンプトキャッシング： 予算カウントダウンのマーカーはリクエストごとにサーバー側で挿入されるため、リクエスト間で一致しません。クライアントがフォローアップリクエストのたびにtask_budget.remainingを減算すると、変更された値によって、それを含むキャッシュプレフィックスが無効になります。キャッシングを維持するには、最初のリクエストで予算を一度だけ設定し、クライアント側で予算を変更するのではなく、サーバー側のカウントダウンに基づいてモデルに自己調整させてください。

機能サポート

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

次のステップ

Compatibility