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

«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-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 использует этот сигнал, чтобы распределять усилия и корректно завершать работу по мере расходования бюджета.

Что считается ходом

Бюджет охватывает один "agentic turn" (агентный ход), также называемый агентным циклом. Это всё, что 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 тратит ещё 4 000 токенов на размышления и второй вызов инструмента (grep -rn "eval(" src/). Обратный отсчёт доходит примерно до remaining ≈ 88 200.

Запрос 3. Полная история снова отправляется повторно, теперь с добавленным вторым результатом инструмента (1 200 токенов вывода grep). Claude пишет итоговый отчёт о находках объёмом 6 000 токенов и останавливается с stop_reason: "end_turn". remaining ≈ 81 000.

Если сравнить три запроса, разница между размером полезной нагрузки и расходом бюджета становится наглядной:

Ваш клиент отправил исходное пользовательское сообщение трижды, а первое сообщение ассистента — дважды, но каждое из них было учтено один раз. Из бюджета израсходовано 19 000 из 100 000 токенов. При этом суммарная полезная нагрузка, переданная клиентом, была больше, а входные данные, закэшированные с помощью "prompt caching" (кэширования подсказок) в запросах 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 — это настройка уровня запроса. Чтобы изменить бюджет в процессе выполнения задачи, например расширить его, когда пользователь расширяет запрос, задайте новый 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-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 настраивает глубину, а бюджеты задач — широту.
• "Adaptive thinking" (адаптивные размышления): бюджеты задач учитывают токены размышлений, поэтому по мере исчерпания бюджета адаптивные размышления сокращаются.
• Кэширование подсказок: маркер обратного отсчёта бюджета внедряется на стороне сервера в каждый запрос, поэтому он различается от запроса к запросу. Если ваш клиент уменьшает task_budget.remaining в каждом последующем запросе, изменённое значение делает недействительным любой префикс кэша, который его содержит. Чтобы сохранить кэширование, задайте бюджет один раз в начальном запросе и позвольте модели ориентироваться на серверный обратный отсчёт, не изменяя бюджет на стороне клиента.

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

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

Следующие шаги

Compatibility