任务预算

"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-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 结束其轮次之后（例如因为预算耗尽）发送的后续消息：

{ "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." }
  ]
}

轮次期间的服务器端压缩不会重置预算：该轮次在压缩之前消耗的令牌仍会计入预算。轮次开始之前的令牌不计入，即使轮次开始时的压缩对其进行了总结也是如此。目前，这一排除规则仅适用于跨服务器端压缩延续的预算；较早轮次的历史只要仍保留在上下文中，就仍会被计入。

示例详解：跨请求的预算计数

任务预算统计的是 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 又在思考和第二个工具调用（grep -rn "eval(" src/）上消耗了 4,000 个令牌。倒计时最终约为 remaining ≈ 88,200。

请求 3。 再次重新发送完整历史，并附加第二个工具结果（1,200 个令牌的 grep 输出）。Claude 撰写了一份 6,000 个令牌的最终发现报告，并以 stop_reason: "end_turn" 停止。remaining ≈ 81,000。

将三个请求并列比较，可以清楚地看出负载大小与预算消耗之间的区别：

您的客户端发送了三次原始用户消息和两次第一条助手消息，但每条消息只被计数一次。预算消耗了 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，而不仅仅是执行压缩的那个请求。

对于在每个请求中都重新发送完整未压缩历史的循环，请省略 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-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