任务预算

任务预算让你告诉 Claude 它在完整代理循环中有多少令牌可用，包括思考、工具调用、工具结果和输出。模型会看到一个运行中的倒计时，并使用它来优先处理工作，并在预算消耗时优雅地完成。

何时使用任务预算

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

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

任务预算补充了努力参数：努力控制 Claude 对每一步的推理深度，而任务预算限制了 Claude 在代理循环中可以执行的总工作量。

设置任务预算

将 task_budget 添加到 output_config 并包含测试版标头：

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-4-7",
    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"],
)

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：

对于在每个轮次上重新发送完整未压缩历史的循环，省略 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 加上思考和工具结果令牌求和：

在一个代表性的任务集合中运行此操作并记录分布。从你的每任务令牌支出的 p99 开始，以了解向模型提供任务预算如何可能修改模型的行为，然后根据需要测试上升或下降。

最小接受的 task_budget.total 是20,000 令牌；低于最小值的值返回 400 错误。

与其他参数的交互

• max_tokens： 与任务预算正交。max_tokens 是对生成令牌的硬每请求上限，而 task_budget 是跨完整代理循环（可能跨越许多请求）的建议性上限。在 xhigh 或 max 努力下，将 max_tokens 设置为至少 64k，以给 Claude 在每个请求上思考和行动的空间。
• 努力： 努力控制 Claude 每一步的推理深度。任务预算控制 Claude 在代理循环中执行的总工作量。这两者是互补的：努力调整深度，任务预算调整广度。
• 自适应思考： 任务预算在计数中包括思考令牌，所以自适应思考自然会随着预算耗尽而缩小。
• 提示缓存： 预算倒计时标记是每轮服务器端注入的，所以它不跨请求匹配。如果你的客户端在每个后续请求上递减 task_budget.remaining，更改的值会使包含它的任何缓存前缀失效。为了保留缓存，在初始请求上设置预算一次，让模型根据服务器端倒计时自我调节，而不是在客户端改变预算。

功能支持

任务预算在启动时不支持 Claude Code 或 Cowork 表面。在 Claude Opus 4.7 上直接通过 Messages API 使用任务预算。