任务预算

"Task budgets"（任务预算）让您可以告诉 Claude 它在一个完整的 "agentic loop"（智能体循环）中拥有多少令牌，包括思考、工具调用、工具结果和输出。模型会看到一个持续更新的倒计时，并利用它来确定工作的优先级，并在预算消耗时优雅地收尾。

何时使用任务预算

任务预算最适合这样的智能体工作流：Claude 在最终确定输出并等待下一次人类响应之前，会进行多次工具调用和决策。在以下情况下使用它们：

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

任务预算与 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 在整个智能体循环中可以消耗的令牌数量，包括思考、工具调用、工具结果和输出。
• 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 又在思考和第二次工具调用（grep -rn "eval(" src/）上消耗了 4,000 个令牌。倒计时最终停在 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：

# 压缩前消耗的令牌数，在客户端跟踪
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 可能偶尔会超出预算。对总输出令牌的强制限制仍然是 max_tokens，达到该限制时会以 stop_reason: "max_tokens" 截断响应。

若要对成本或延迟设置硬上限，请将任务预算与合理的 max_tokens 值结合使用：

• 使用 task_budget 为 Claude 提供一个控制节奏的目标。
• 使用 max_tokens 作为防止失控生成的绝对上限。

由于 task_budget 跨越整个智能体循环（可能包含多个请求），而 max_tokens 限制的是每个单独的请求，因此这两个值是相互独立的；不要求其中一个小于或等于另一个。

选择预算

合适的预算取决于您的智能体循环当前完成的工作量。与其猜测，不如先测量您现有的令牌用量，然后在此基础上进行调整。

测量您当前的用量

在不设置 task_budget 的情况下运行一组有代表性的任务样本，并记录 Claude 每个任务消耗的总令牌数。对于智能体循环，请对循环中每个请求的 usage.output_tokens 求和，再加上您在请求之间附加的工具结果的令牌数：

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)

在一组有代表性的任务上运行此代码并记录分布情况。从您单任务令牌消耗的 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 使用任务预算。

后续步骤

Compatibility