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

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



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

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

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

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



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

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

client = anthropic.Anthropic()

with client.beta.messages.stream(
    model="claude-opus-4-8",
    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:

output_config = {
    "effort": "high",
    "task_budget": {
        "type": "tokens",
        "total": 128000,
        "remaining": 128000 - tokens_spent_so_far,
    },
}

Для циклов, которые повторно отправляют полную некомпактизированную историю на каждом ходе, опустите 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 плюс токены мышления и результатов инструментов по всем запросам в цикле:

def run_task_and_count_tokens(messages: list) -> int:
    """Runs an agentic loop to completion and returns total tokens spent."""
    total_spend = 0
    while True:
        with client.beta.messages.stream(
            model="claude-opus-4-8",
            max_tokens=128000,
            messages=messages,
            tools=tools,
            betas=["task-budgets-2026-03-13"],
        ) as stream:
            response = stream.get_final_message()
        # Подсчитайте, что Claude сгенерировал за этот ход (вывод включает текст + мышление + вызовы инструментов).
        # Токены результатов инструментов тоже учитываются в бюджете; добавьте число токенов
        # блоков tool_result, которые вы добавляете ниже, если хотите, чтобы клиентский подсчёт
        # совпадал с серверным отсчётом.
        total_spend += response.usage.output_tokens
        if response.stop_reason == "end_turn":
            return total_spend
        # Добавьте ход ассистента и результаты ваших инструментов, затем продолжите цикл.
        messages += [
            {"role": "assistant", "content": response.content},
            {"role": "user", "content": run_tools(response.content)},
        ]

Выполните это на репрезентативном наборе задач и запишите распределение. Начните с 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 на поддерживаемой модели.