任務預算

任務預算讓你告訴 Claude 它在完整代理迴圈中有多少代幣可用，包括思考、工具呼叫、工具結果和輸出。模型會看到一個執行中的倒數計時，並使用它來優先處理工作，並在預算消耗時優雅地完成。

何時使用任務預算

任務預算最適合用於代理工作流程，其中 Claude 在最終確定輸出以等待下一個人類回應之前進行多次工具呼叫和決策。在以下情況下使用它們：

• 你希望 Claude 在長期任務上自我調節代幣支出。
• 你有可預測的每任務成本或延遲上限需要強制執行。
• 你希望模型在接近預算時優雅地完成（總結發現、報告進度），而不是在中途中斷。

任務預算補充了 effort 參數：effort 控制 Claude 對每一步的推理深度，而任務預算則限制 Claude 在代理迴圈中可以執行的總工作量。

設定任務預算

將 task_budget 新增到 output_config 並包含測試版標頭：

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 物件有三個欄位：

• 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 在思考和第二個工具呼叫（grep -rn "eval(" src/）上花費另外 4,000 個代幣。倒數計時結束時接近 remaining ≈ 88,200。

轉換 3。 完整歷史記錄再次重新傳送，並附加第二個工具結果（1,200 個代幣的 grep 輸出）。Claude 撰寫一份 6,000 代幣的最終發現報告並停止，stop_reason: "end_turn"。remaining ≈ 81,000。

將三個轉換並排放置會明確區分有效負載大小和預算支出：

你的用戶端傳送了轉換 1 使用者訊息三次和轉換 1 助手訊息兩次，但每次都只計數一次。預算花費了 100,000 個代幣中的 19,000 個，儘管你的用戶端傳送的累積有效負載更大，轉換 2 和 3 上的提示快取輸入也更大。

使用 remaining 跨壓縮結轉預算

如果你的代理迴圈在請求之間壓縮或重寫上下文（例如，透過總結較早的轉換），伺服器沒有壓縮前花費多少預算的記憶。在下一個請求上傳遞 remaining，以便倒數計時從你停止的地方繼續，而不是重設為 total：

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

對於在每個轉換上重新傳送完整未壓縮歷史記錄的迴圈，省略 remaining 並讓伺服器追蹤倒數計時。

任務預算是建議性的，不是強制性的

任務預算是一個軟提示，而不是硬上限。如果 Claude 在中途進行一個動作，而中斷它比完成它更具破壞性，Claude 可能偶爾會超過預算。總輸出代幣的強制限制仍然是 max_tokens，當達到時會以 stop_reason: "max_tokens" 截斷回應。

對於成本或延遲的硬上限，將任務預算與合理的 max_tokens 值結合：

• 使用 task_budget 給 Claude 一個步調目標。
• 使用 max_tokens 作為防止失控生成的絕對上限。

因為 task_budget 跨越完整代理迴圈（可能是許多請求），而 max_tokens 限制每個單獨的請求，這兩個值是獨立的；一個不需要在或低於另一個。

選擇預算

正確的預算取決於你的代理迴圈目前執行多少工作。與其猜測，不如先測量你現有的代幣使用情況，然後從那裡進行調整。

測量你目前的使用情況

執行一個代表性的任務樣本不設定 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:
        response = client.beta.messages.create(
            model="claude-opus-4-7",
            max_tokens=128000,
            messages=messages,
            tools=tools,
            betas=["task-budgets-2026-03-13"],
        )
        # Count what Claude generated this turn (output covers text + thinking + tool calls).
        # Tool-result tokens also count against the budget; add the token count of the
        # tool_result blocks you append below if you want client-side tracking to match
        # the server-side countdown.
        total_spend += response.usage.output_tokens
        if response.stop_reason == "end_turn":
            return total_spend
        # Append the assistant turn and your tool results, then continue the loop.
        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 時，將 max_tokens 設定為至少 64k，以便給 Claude 在每個請求上思考和行動的空間。
• Effort： Effort 控制 Claude 每一步的推理深度。任務預算控制 Claude 在代理迴圈中執行的總工作量。這兩者是互補的：effort 調整深度，任務預算調整廣度。
• 自適應思考： 任務預算在計數中包括思考代幣，所以自適應思考自然會在預算耗盡時縮小。
• 提示快取： 預算倒數計時標記按轉換由伺服器端注入，所以它不會跨請求匹配。如果你的用戶端在每個後續請求上遞減 task_budget.remaining，更改的值會使包含它的任何快取前綴失效。為了保留快取，在初始請求上設定預算一次，並讓模型根據伺服器端倒數計時自我調節，而不是在用戶端側變更預算。

功能支援

任務預算在啟動時不支援 Claude Code 或 Cowork 表面。在 Claude Opus 4.7 上直接透過 Messages API 使用任務預算。