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

«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 на поддерживаемой модели.

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

Compatibility