任务预算

"Task budgets"（任务预算）让您可以告诉 Claude 在整个代理循环中有多少令牌可用，包括思考、工具调用、工具结果和输出。模型会看到一个实时倒计时，并利用它来确定工作优先级，并在预算消耗时优雅地完成任务。



何时使用任务预算

任务预算最适合用于 Claude 在最终确定输出以等待下一次人工响应之前进行多次工具调用和决策的代理工作流。在以下情况下使用它们：

• 您希望 Claude 在长周期任务中自我调节令牌消耗。
• 您有可预测的每任务成本或延迟上限需要执行。
• 您希望模型在接近预算时优雅地完成（总结发现、报告进度），而不是在操作中途被切断。

任务预算与 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 在整个代理循环中可以消耗的令牌数量，包括思考、工具调用、工具结果和输出。
• 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 又花费了 4,000 个令牌用于思考和第二次工具调用（grep -rn "eval(" src/）。倒计时最终接近 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 正处于一个中断比完成更具破坏性的操作中，它可能偶尔会超出预算。对总输出令牌的强制限制仍然是 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:
        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 在本轮生成的内容（输出涵盖文本 + 思考 + 工具调用）。
        # 工具结果令牌也会计入预算；如果您希望客户端的统计
        # 与服务器端的倒计数一致，请加上您在下方追加的
        # tool_result 块的令牌数。
        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)},
        ]

在一组有代表性的任务上运行此操作并记录分布。从您每任务令牌消耗的 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 界面不支持任务预算。请在支持的模型上直接通过 Messages API 使用任务预算。