任务预算

为 Claude 提供一个针对完整智能体循环的建议性令牌预算,帮助模型在长时间运行的智能体任务中进行自我调节。

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

何时使用任务预算

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

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

任务预算与 effort 参数相辅相成:effort 控制 Claude 对每个步骤推理的深入程度,而任务预算则限制 Claude 在整个智能体循环中可以完成的总工作量。

设置任务预算

将 task_budget 添加到 output_config 中,并包含 beta 请求头:

示例代码
curl https://api.anthropic.com/v1/messages \
  -N \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2026-10-21" \
  -H "anthropic-beta: task-budgets-2026-03-13" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-5-5",
    "max_tokens": 128000,
    "stream": true,
    "messages": [{
      "role": "user",
      "content": "Review the codebase and propose a refactor plan."
    }],
    "output_config": {
      "effort": "high",
      "task_budget": {"type": "tokens", "total": 64000}
    }
  }'
示例代码
ant beta:messages create --beta task-budgets-2026-03-13 --stream <<'YAML'
model: claude-opus-5-5
max_tokens: 128000
messages:
  - role: user
    content: Review the codebase and propose a refactor plan.
output_config:
  effort: high
  task_budget:
    type: tokens
    total: 64000
YAML
示例代码
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)
示例代码
const client = new Anthropic();

const stream = 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"]
});

const response = await stream.finalMessage();
console.log(response.usage);
示例代码

var client = new AnthropicClient();

var responseUpdates = client.Beta.Messages.CreateStreaming(new MessageCreateParams
{
    Model = Messages::Model.ClaudeOpus5_5,
    MaxTokens = 128000,
    Messages = [new BetaUserMessageParam { Content = "Review the codebase and propose a refactor plan." }],
    OutputConfig = new BetaOutputConfig
    {
        Effort = Effort.High,
        TaskBudget = new BetaTokenTaskBudget { Total = 64000 },
    },
    Betas = ["task-budgets-2026-03-13"],
});

var response = await responseUpdates.Aggregate();
Console.WriteLine(response.Usage);
示例代码
client := anthropic.NewClient()

stream := client.Beta.Messages.NewStreaming(context.TODO(), anthropic.BetaMessageNewParams{
	Model:     anthropic.ModelClaudeOpus5_5,
	MaxTokens: 128000,
	Betas:     []anthropic.AnthropicBeta{"task-budgets-2026-03-13"},
	Messages: []anthropic.BetaMessageParam{
		anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Review the codebase and propose a refactor plan.")),
	},
	OutputConfig: anthropic.BetaOutputConfigParam{
		Effort: anthropic.BetaOutputConfigEffortHigh,
		TaskBudget: anthropic.BetaTokenTaskBudgetParam{
			Total: 64000,
		},
	},
})

message := anthropic.BetaMessage{}
for stream.Next() {
	event := stream.Current()
	if err := message.Accumulate(event); err != nil {
		panic(err)
	}
}
if stream.Err() != nil {
	panic(stream.Err())
}

fmt.Printf("Usage: input_tokens=%d, output_tokens=%d\n", message.Usage.InputTokens, message.Usage.OutputTokens)
示例代码
AnthropicClient client = AnthropicOkHttpClient.fromEnv();

MessageCreateParams params = MessageCreateParams.builder()
    .model(Model.CLAUDE_OPUS_5_5)
    .maxTokens(128000L)
    .addUserMessage("Review the codebase and propose a refactor plan.")
    .outputConfig(BetaOutputConfig.builder()
        .effort(BetaOutputConfig.Effort.HIGH)
        .taskBudget(BetaTokenTaskBudget.builder()
            .total(64000L)
            .build())
        .build())
    .addBeta("task-budgets-2026-03-13")
    .build();

BetaMessageAccumulator accumulator = BetaMessageAccumulator.create();
try (StreamResponse<BetaRawMessageStreamEvent> stream =
        client.beta().messages().createStreaming(params)) {
    stream.stream().forEach(accumulator::accumulate);
}

BetaMessage response = accumulator.message();
IO.println(response.usage());
示例代码
use Anthropic\Beta\Messages\BetaRawMessageDeltaEvent;
use Anthropic\Messages\Model;

$client = new Client();

$stream = $client->beta->messages->createStream(
    model: Model::CLAUDE_OPUS_5_5,
    maxTokens: 128000,
    messages: [
        ['role' => 'user', 'content' => 'Review the codebase and propose a refactor plan.'],
    ],
    outputConfig: [
        'effort' => 'high',
        'taskBudget' => ['type' => 'tokens', 'total' => 64000],
    ],
    betas: ['task-budgets-2026-03-13'],
);

// 最后一个 message_delta 事件包含该请求的累计令牌用量。
$usage = null;
foreach ($stream as $event) {
    if ($event instanceof BetaRawMessageDeltaEvent) {
        $usage = $event->usage;
    }
}

echo $usage;
示例代码
client = Anthropic::Client.new

stream = client.beta.messages.stream(
  model: Anthropic::Model::CLAUDE_OPUS_5_5,
  max_tokens: 128_000,
  messages: [
    { role: "user", content: "Review the codebase and propose a refactor plan." }
  ],
  output_config: {
    effort: :high,
    task_budget: { type: :tokens, total: 64_000 }
  },
  betas: ["task-budgets-2026-03-13"]
)

response = stream.accumulated_message

puts 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。

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

请求请求负载(您发送的大致输入令牌数)本次请求计入预算的令牌数之后的预算 remaining
1~205,000(思考 + tool_use)~95,000
2~7,800(请求 1 的消息 + 工具结果)6,800(2,800 工具结果 + 4,000 思考和 tool_use)~88,200
3~13,000(完整历史 + 第二个工具结果)7,200(1,200 工具结果 + 6,000 text)~81,000
总计各请求共发送约 20,820计入预算 19,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,
    },
}
示例代码
// 压缩前消耗的令牌数,在客户端跟踪
const tokensSpentSoFar = 45000;

const outputConfig = {
  effort: "high",
  task_budget: {
    type: "tokens",
    total: 128000,
    remaining: 128000 - tokensSpentSoFar
  }
};
示例代码
// 压缩前消耗的令牌数,在客户端跟踪
var tokensSpentSoFar = 45000;

var outputConfig = new BetaOutputConfig
{
    Effort = Effort.High,
    TaskBudget = new BetaTokenTaskBudget
    {
        Total = 128000,
        Remaining = 128000 - tokensSpentSoFar,
    },
};
示例代码
// 压缩前消耗的令牌数,在客户端跟踪
tokensSpentSoFar := int64(45000)

outputConfig := anthropic.BetaOutputConfigParam{
	Effort: anthropic.BetaOutputConfigEffortHigh,
	TaskBudget: anthropic.BetaTokenTaskBudgetParam{
		Total:     128000,
		Remaining: anthropic.Int(128000 - tokensSpentSoFar),
	},
}
示例代码
// 压缩前消耗的令牌数,在客户端跟踪
long tokensSpentSoFar = 45000;

BetaOutputConfig outputConfig = BetaOutputConfig.builder()
    .effort(BetaOutputConfig.Effort.HIGH)
    .taskBudget(BetaTokenTaskBudget.builder()
        .total(128000L)
        .remaining(128000L - tokensSpentSoFar)
        .build())
    .build();
示例代码
// 压缩前消耗的令牌数,在客户端跟踪
$tokensSpentSoFar = 45000;

$outputConfig = [
    'effort' => 'high',
    'taskBudget' => [
        'type' => 'tokens',
        'total' => 128000,
        'remaining' => 128000 - $tokensSpentSoFar,
    ],
];
示例代码
# 压缩前消耗的令牌数,在客户端跟踪
tokens_spent_so_far = 45_000

output_config = {
  effort: :high,
  task_budget: {
    type: :tokens,
    total: 128_000,
    remaining: 128_000 - 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,再加上您在请求之间附加的工具结果的令牌数:

示例代码
curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2026-10-21" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-5-5",
    "max_tokens": 4096,
    "messages": [{
      "role": "user",
      "content": "Review the codebase and propose a refactor plan."
    }]
  }'
示例代码
ant messages create <<'YAML'
model: claude-opus-5-5
max_tokens: 4096
messages:
  - role: user
    content: Review the codebase and propose a refactor plan.
YAML
示例代码
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)
示例代码
const client = new Anthropic();

const response = await 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(文本 + 思考 + 工具调用)求和。
console.log(response.usage.output_tokens);
示例代码

var client = new AnthropicClient();

var response = await client.Messages.Create(new MessageCreateParams
{
    Model = Model.ClaudeOpus5_5,
    MaxTokens = 4096,
    Messages = [new UserMessageParam { Content = "Review the codebase and propose a refactor plan." }],
});

// 对循环中每个请求的 OutputTokens(文本 + 思考 + 工具调用)求和。
Console.WriteLine(response.Usage.OutputTokens);
示例代码
client := anthropic.NewClient()

response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
	Model:     anthropic.ModelClaudeOpus5_5,
	MaxTokens: 4096,
	Messages: []anthropic.MessageParam{
		anthropic.NewUserMessage(anthropic.NewTextBlock("Review the codebase and propose a refactor plan.")),
	},
})
if err != nil {
	log.Fatal(err)
}

// 对循环中每个请求的 OutputTokens(文本 + 思考 + 工具调用)求和。
fmt.Println(response.Usage.OutputTokens)
示例代码
AnthropicClient client = AnthropicOkHttpClient.fromEnv();

MessageCreateParams params = MessageCreateParams.builder()
    .model(Model.CLAUDE_OPUS_5_5)
    .maxTokens(4096L)
    .addUserMessage("Review the codebase and propose a refactor plan.")
    .build();

Message response = client.messages().create(params);
// 对循环中每个请求的 outputTokens(文本 + 思考 + 工具调用)求和。
IO.println(response.usage().outputTokens());
示例代码
$client = new Client();

$response = $client->messages->create(
    model: Model::CLAUDE_OPUS_5_5,
    maxTokens: 4096,
    messages: [
        ['role' => 'user', 'content' => 'Review the codebase and propose a refactor plan.'],
    ],
);

// 对循环中每个请求的 outputTokens(文本 + 思考 + 工具调用)求和。
echo $response->usage->outputTokens . "\n";
示例代码
client = Anthropic::Client.new

response = client.messages.create(
  model: Anthropic::Model::CLAUDE_OPUS_5_5,
  max_tokens: 4096,
  messages: [
    { role: "user", content: "Review the codebase and propose a refactor plan." }
  ]
)

# 对循环中每个请求的 output_tokens(文本 + 思考 + 工具调用)求和。
puts 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 Fable 5.2Beta(设置 task-budgets-2026-03-13 请求头)
Claude Mythos 5.2Beta(设置 task-budgets-2026-03-13 请求头)
Claude Fable 5.1Beta(设置 task-budgets-2026-03-13 请求头)
Claude Mythos 5.1Beta(设置 task-budgets-2026-03-13 请求头)
Claude Opus 5.5Beta(设置 task-budgets-2026-03-13 请求头)
Claude Opus 5Beta(设置 task-budgets-2026-03-13 请求头)
Claude Fable 5Beta(设置 task-budgets-2026-03-13 请求头)
Claude Mythos 5Beta(设置 task-budgets-2026-03-13 请求头)
Claude Sonnet 5.5Beta(设置 task-budgets-2026-03-13 请求头)
Claude Sonnet 5不支持
Claude Haiku 5.5Beta(设置 task-budgets-2026-03-13 请求头)
Claude Opus 4.8Beta(设置 task-budgets-2026-03-13 请求头)
Claude Opus 4.7Beta(设置 task-budgets-2026-03-13 请求头)
Claude Opus 4.6不支持
Claude Sonnet 4.6不支持
Claude Haiku 4.5不支持

Claude Code 或 Cowork 界面不支持任务预算。请在受支持的模型上直接通过 Messages API 使用任务预算。

后续步骤

Effort

控制 Claude 对智能体循环中每个步骤推理的深入程度。

自适应思考

让 Claude 决定何时使用扩展思考以及使用多少。

压缩概述

通过服务器端压缩管理长时间运行对话中的上下文。

提示缓存

通过缓存提示前缀,降低重复提示的成本和延迟。

可用性

任务预算在部分模型上处于 beta 阶段。

API 支持

Messages API

  • 可用性:可用
  • 用法:建议性:在 output_config.task_budget 中设置。API 不会在达到预算时停止 Claude。

Managed Agents

所需的 beta 请求头

Beta 请求头概览

Beta 请求头让您可以在实验性功能和新模型能力成为标准 API 的一部分之前访问它们。

  • task-budgets-2026-03-13
文档内容持续同步更新