任務預算

「Task budgets」（任務預算）讓您告訴 Claude 在一個完整的「agentic loop」（代理迴圈）中有多少 token 可用，包括思考、工具呼叫、工具結果與輸出。模型會看到一個持續更新的倒數計數，並據此安排工作的優先順序，在預算逐漸耗盡時優雅地收尾。

何時使用任務預算

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

• 您希望 Claude 在長時程任務中自我調節 token 花費。
• 您需要強制執行可預測的每項任務成本或「latency」（延遲）上限。
• 您希望模型在接近預算時優雅地收尾（總結發現、回報進度），而非在動作進行到一半時中斷。

任務預算與 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 使用任務預算。

後續步驟

Compatibility