任務預算

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



何時使用任務預算

任務預算最適合用於代理工作流程，在這類流程中，Claude 會進行多次工具呼叫和決策，然後才完成輸出以等待下一個人類回應。請在以下情況使用：

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

任務預算與 effort 參數相輔相成：effort 控制 Claude 對每個步驟推理的徹底程度，而任務預算則限制 Claude 在整個代理迴圈中可執行的總工作量。



設定任務預算

將 task_budget 加入 output_config 並包含 beta 標頭：

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

• 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：

# 壓縮前消耗的 token 數，由用戶端追蹤
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 正在執行某個動作，而中斷該動作比完成它更具破壞性，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 數：

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)

在一組具代表性的任務上執行此測量並記錄分佈。從您每任務 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 使用任務預算。



後續步驟