任務預算

任務預算（task budgets）讓您告訴 Claude 在完整的代理迴圈中有多少 token 可用，包括思考、工具呼叫、工具結果和輸出。模型會看到一個持續倒數的計數，並利用它來安排工作的優先順序，並在預算消耗時優雅地完成任務。



何時使用任務預算

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

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

任務預算與 effort 參數互補：effort 控制 Claude 對每個步驟推理的深入程度，而任務預算則限制 Claude 在整個代理迴圈中可以完成的總工作量。



設定任務預算

將 task_budget 加入 output_config 並包含測試版標頭：

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

• type：永遠為 "tokens"。
• total：Claude 在整個代理迴圈中可以花費的 token 數量，包括思考、工具呼叫、工具結果和輸出。
• remaining（選填）：從先前請求延續下來的預算餘額。省略時預設為 total。



預算倒數如何運作

Claude 會在整個對話過程中看到由伺服器端注入的預算倒數標記。該標記顯示目前代理迴圈中還剩多少 token，並隨著模型生成思考、工具呼叫和輸出，以及處理工具結果時更新。Claude 利用這個訊號來調整自己的節奏，並在預算消耗時優雅地完成任務。



實例演練：跨回合的預算計算

任務預算計算的是 Claude 看到的內容（思考、工具呼叫和結果，以及文字），而不是您請求酬載中的內容。在代理迴圈中，您的客戶端在每次請求時都會重新傳送完整的對話，因此酬載會逐回合增長，但預算只會根據 Claude 在本回合看到的 token 遞減。

考慮一個使用 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 個 token。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 個 token 的工具結果是 Claude 在本回合看到的新內容，會計入預算。Claude 又花費了 4,000 個 token 進行思考和第二次工具呼叫（grep -rn "eval(" src/）。倒數計數最終接近 remaining ≈ 88,200。

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

將三個回合並排比較，可以清楚看出酬載大小與預算支出之間的區別：

您的客戶端傳送了回合 1 的使用者訊息三次，以及回合 1 的助理訊息兩次，但每個都只計算一次。預算花費了 100,000 個 token 中的 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 正在進行一個中斷比完成更具破壞性的動作，它偶爾可能會超出預算。對總輸出 token 的強制限制仍然是 max_tokens，達到時會以 stop_reason: "max_tokens" 截斷回應。

若要對成本或延遲設定硬性上限，請將任務預算與合理的 max_tokens 值結合使用：

• 使用 task_budget 給 Claude 一個可以據以調整節奏的目標。
• 使用 max_tokens 作為防止失控生成的絕對上限。

由於 task_budget 涵蓋整個代理迴圈（可能包含多個請求），而 max_tokens 限制每個單獨的請求，這兩個值是獨立的；其中一個不需要等於或低於另一個。



選擇預算

合適的預算取決於您的代理迴圈目前完成多少工作。與其猜測，不如先測量您現有的 token 使用量，然後再從那裡調整。



測量您目前的使用量

在不設定 task_budget 的情況下執行具代表性的任務樣本，並記錄 Claude 每個任務花費的總 token 數。對於代理迴圈，請加總迴圈中每個請求的 usage.output_tokens 加上思考和工具結果的 token：

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 在此回合產生的內容（輸出涵蓋文字 + 思考 + 工具呼叫）。
        # 工具結果的 token 也會計入預算；若您希望用戶端的追蹤
        # 與伺服器端的倒數一致，請加上您在下方附加的
        # tool_result 區塊的 token 數量。
        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)},
        ]

在一組具代表性的任務上執行此操作並記錄分佈。從您每任務 token 支出的 p99 開始，以了解為模型提供任務預算可能如何改變模型的行為，然後視需要向上或向下測試。

task_budget.total 接受的最小值為 20,000 個 token；低於最小值的值會回傳 400 錯誤。



與其他參數的互動

• max_tokens： 與任務預算正交。max_tokens 是對生成 token 的每請求硬性上限，而 task_budget 是跨整個代理迴圈（可能涵蓋多個請求）的建議性上限。在 xhigh 或 max effort 下，請將 max_tokens 設定為至少 64k，讓 Claude 在每個請求中有足夠的空間思考和行動。
• Effort： Effort 控制 Claude 每個步驟推理的深度。任務預算控制 Claude 在整個代理迴圈中完成的總工作量。兩者互補：effort 調整深度，任務預算調整廣度。
• 自適應思考： 任務預算將思考 token 計入計數，因此自適應思考會隨著預算耗盡而自然縮減。
• 提示快取： 預算倒數標記是由伺服器端在每個回合注入的，因此在不同請求之間不會相符。如果您的客戶端在每次後續請求中遞減 task_budget.remaining，變更的值會使任何包含它的快取前綴失效。為了保留快取，請在初始請求中設定一次預算，讓模型根據伺服器端的倒數計數自我調節，而不是在客戶端變更預算。



功能支援

Claude Code 或 Cowork 介面不支援任務預算。請在支援的模型上直接透過 Messages API 使用任務預算。