任務預算

「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-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 結束其回合之後（例如因為預算用盡）所發出的後續訊息：

{ "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」（壓縮）不會重設預算：回合在壓縮前消耗的 token 仍會計入預算。回合開始之前的 token 不會計入，即使回合開始時的壓縮對其進行了摘要也是如此。目前，此排除僅適用於跨伺服器端壓縮延續的預算；先前回合的歷史只要仍保留在上下文中，仍會被計入。

實際範例：跨請求的預算計算

任務預算計算的是 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 又花費 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。

將三個請求並列比較，可以清楚看出酬載大小與預算花費之間的差異：

您的用戶端傳送了原始使用者訊息三次、第一則助理訊息兩次，但每則訊息都只計算一次。預算花費了 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,
    },
}

在此範例中，壓縮之前花費的 token 是您到目前為止從歷史中移除的所有訊息的使用量，測量方式如測量您目前的使用量所述。請排除仍存在於您所傳送訊息中的任何內容，包括您加入的任何摘要，因為伺服器會自行計算這些 token。只有在您以這種方式取代歷史時才更新此數值；不要在每次請求時遞減它。請在每個請求中都傳遞計算出的 remaining，而不只是在進行壓縮的那個請求中傳遞。

對於每次請求都重新傳送完整未壓縮歷史的迴圈，請省略 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-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