任务预算

"Task budgets"（任务预算）允许您告知 Claude 在一个完整的智能体循环中可以使用多少令牌，包括思考、工具调用、工具结果和输出。模型会看到一个实时倒计时，并据此对工作进行优先级排序，在预算逐渐消耗时优雅地完成任务。



何时使用任务预算

任务预算最适用于智能体工作流，即 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 又花费了 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：

# 压缩前消耗的令牌数，由客户端跟踪
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 使用任务预算。



后续步骤