Бюджеты задач

«Task budgets» (бюджеты задач) позволяют сообщить Claude, сколько токенов у него есть на полный агентный цикл, включая мышление, вызовы инструментов, результаты инструментов и вывод. Модель видит текущий обратный отсчёт и использует его, чтобы расставлять приоритеты в работе и корректно завершать её по мере расходования бюджета.



Когда использовать бюджеты задач

Бюджеты задач лучше всего подходят для агентных рабочих процессов, в которых Claude выполняет несколько вызовов инструментов и принимает решения, прежде чем сформировать окончательный вывод и дождаться следующего ответа человека. Используйте их, когда:

• Вы хотите, чтобы Claude саморегулировал расход токенов при выполнении долгосрочных задач.
• У вас есть предсказуемый потолок стоимости или задержки на задачу, который нужно соблюдать.
• Вы хотите, чтобы модель корректно завершала работу (резюмировала результаты, сообщала о прогрессе) по мере приближения к бюджету, а не обрывалась посреди действия.

Бюджеты задач дополняют параметр effort: effort управляет тем, насколько тщательно Claude рассуждает на каждом шаге, тогда как бюджеты задач ограничивают общий объём работы, который Claude может выполнить в рамках агентного цикла.



Установка бюджета задачи

Добавьте task_budget в output_config и включите бета-заголовок:

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 — дважды, но каждое было засчитано один раз. Бюджет израсходовал 19 000 из 100 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 — это настройка уровня запроса. Чтобы изменить бюджет в процессе выполнения задачи, например расширить его, когда пользователь расширяет запрос, задайте новый task_budget в output_config в следующем запросе. Учитывайте последствия для кэширования: значение бюджета участвует в отрисованной подсказке, поэтому изменённое значение не совпадает с записями кэша, созданными при старом значении (см. Поддержка функции ниже).



Бюджеты задач носят рекомендательный характер, а не принудительный

Бюджеты задач — это мягкая подсказка, а не жёсткое ограничение. 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 — рекомендательное ограничение на весь агентный цикл (потенциально охватывающий много запросов). При уровне effort xhigh или max установите max_tokens не менее 64k, чтобы дать Claude пространство для мышления и действий в каждом запросе.
• Effort: Effort управляет тем, насколько глубоко Claude рассуждает на каждом шаге. Бюджеты задач управляют тем, сколько общей работы Claude выполняет в рамках агентного цикла. Эти два параметра дополняют друг друга: effort настраивает глубину, бюджеты задач — широту.
• Адаптивное мышление: Бюджеты задач включают токены мышления в подсчёт, поэтому адаптивное мышление естественным образом сокращается по мере исчерпания бюджета.
• Кэширование подсказок: Маркер обратного отсчёта бюджета внедряется на стороне сервера на каждом ходе, поэтому он не совпадает между запросами. Если ваш клиент уменьшает task_budget.remaining при каждом последующем запросе, изменённое значение делает недействительным любой префикс кэша, который его содержит. Чтобы сохранить кэширование, установите бюджет один раз в начальном запросе и позвольте модели саморегулироваться по серверному обратному отсчёту, а не изменяйте бюджет на стороне клиента.



Поддержка функции

Бюджеты задач не поддерживаются в Claude Code и на поверхностях Cowork. Используйте бюджеты задач напрямую через Messages API на поддерживаемой модели.



Дальнейшие шаги