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

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

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

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

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

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

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

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

Объект 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:

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

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

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