Бюджеты сессий

Бюджет сессии — это необязательный жёсткий потолок расходов, который вы задаёте при создании сессии. Платформа непрерывно оценивает всё, что потребляет сессия, по публичным прейскурантным ценам (это прейскурантная стоимость сессии) и прекращает выдавать новые запросы к модели, как только эта стоимость достигает бюджета. Запрос, выполняющийся в момент превышения лимита, всё равно завершается, поэтому итоговая прейскурантная стоимость может оказаться немного выше бюджета. Сессия, достигшая своего бюджета, приостанавливается и переходит в состояние простоя, а не завершается; изменение или удаление бюджета автоматически возобновляет её работу. Развёртывания принимают такой же бюджет и применяют его к каждой запускаемой ими сессии; см. Бюджеты в развёртываниях.



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

Передайте необязательное поле budget при создании сессии:

session=$(curl -fsSL https://api.anthropic.com/v1/sessions \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d @- <<EOF
{
  "agent": "$AGENT_ID",
  "environment_id": "$ENVIRONMENT_ID",
  "budget": {
    "type": "limit",
    "max_list_cost": {"amount": "2500", "currency": "USD"}
  }
}
EOF
)
SESSION_ID=$(jq -r '.id' <<< "$session")

Объект budget содержит два поля:

• type всегда равен "limit".
• max_list_cost — это сам лимит: amount — целое число центов США, записанное строкой без ведущих нулей ("2500" — это $25,00, а "50" — 50 центов), и оно должно быть больше нуля. Десятичные формы, такие как "25.00", отклоняются. Сумма представлена строкой, а не числом, чтобы к ней никогда не применялось округление чисел с плавающей точкой. currency — код валюты по ISO-4217 в верхнем регистре; USD — единственная поддерживаемая валюта.

Бюджет можно прикрепить только при создании сессии. Добавление бюджета к существующей сессии, у которой его нет, отклоняется с ошибкой 400. Лимит сессии с бюджетом можно изменить или удалить в любой момент.



Как измеряется прейскурантная стоимость

Платформа непрерывно оценивает то, что потребляет сессия, по публичным прейскурантным ценам:

• Токены модели — по прейскурантной цене каждой используемой модели
• Веб-поиски — по $10 за 1 000 поисков
• Время работы сессии — по $0,08 в час

Эта накапливаемая долларовая сумма и есть прейскурантная стоимость сессии, и именно с ней сравнивается бюджет. Прейскурантная стоимость — это не ваша договорная цена: если ваша организация договорилась о скидках, сессия достигает своего лимита, когда его достигает сумма по прейскурантным ценам, а выставленная вам сумма может оказаться ниже лимита.

При применении лимита используется точная, неокруглённая прейскурантная стоимость. Значения list_cost, отображаемые для сессии и её событий, — это целые центы, округлённые до ближайшего цента, поэтому отображаемое значение может отличаться до половины цента в любую сторону от точной суммы, используемой при проверке лимита.



Когда сессия достигает своего бюджета

Лимит применяется между запросами к модели, а не посреди запроса. Перед каждым запросом к модели платформа проверяет потреблённую прейскурантную стоимость сессии, и как только эта сумма достигает лимита, каждый поток приостанавливается перед своим следующим запросом. Запрос, который вывел сумму за пределы лимита, был допущен, пока сессия ещё находилась под лимитом, и выполняется до завершения, поэтому зафиксированное значение list_cost приостановленной сессии равно max_list_cost или немного превышает его: сессия с лимитом "50" (50 центов) может приостановиться с list_cost, равным "53". Это ожидаемое поведение, а не ошибка биллинга, и превышение ограничено одним запросом к модели на поток. Рассматривайте бюджет как ограничение на новую работу, а не как точную точку остановки, и задавайте лимит с учётом этого запаса в один запрос.

Сессия, достигшая своего бюджета, переходит в состояние простоя со stop_reason, равным budget_reached; она не завершается, а её история и песочница сохраняются, как и у любой другой простаивающей сессии. В потоке событий вы увидите, по порядку:

1. Событие session.thread_status_idle со stop_reason, равным budget_reached, по мере приостановки каждого потока.
2. Событие session.usage с накопленным использованием и прейскурантной стоимостью сессии.
3. Событие session.status_idle со stop_reason, равным budget_reached. Событие использования всегда непосредственно предшествует этому событию простоя.

Поток, чей последний запрос одновременно пересекает лимит и завершает свой ход, сообщает end_turn в собственном событии session.thread_status_idle, тогда как сессия по-прежнему сообщает budget_reached; рассматривайте stop_reason уровня сессии как сигнал о том, что сессия приостановилась на своём бюджете.



События, принимаемые при достижении лимита

Пока сессия находится на уровне бюджета или превысила его, она принимает только события, завершающие уже выполняющуюся работу:

• user.tool_confirmation
• user.tool_result
• user.custom_tool_result
• user.interrupt

Любое событие, которое запустило бы новую работу, например user.message, отклоняется с ошибкой 400, в которой перечислен этот список. Завершающие результаты записываются без запуска нового запроса к модели; сессия остаётся приостановленной на своём бюджете.

Событие user.interrupt, отправленное, пока сессия приостановлена на своём бюджете (все потоки приостановлены на лимите), принимается и игнорируется: оно не появляется в списке событий и ничего не меняет. Измените или удалите бюджет, чтобы продолжить.



Возобновление сессии, достигшей бюджета

Измените или удалите бюджет с помощью обновления сессии. Принятое обновление автоматически возобновляет приостановленную работу сессии; никаких дополнительных действий со стороны клиента не требуется.



Изменение бюджета

Обновите сессию, указав новое значение max_list_cost. Новое значение может быть выше или ниже текущего лимита, но оно должно быть строго больше потреблённой прейскурантной стоимости сессии; в противном случае обновление отклоняется с ошибкой 400: budget.max_list_cost must be greater than the session's consumed list cost. Поскольку потреблённая стоимость обычно находится немного выше старого лимита, когда сессия приостанавливается, основывайте новое значение на отображаемом usage.list_cost сессии, а не на старом max_list_cost. Установите его на цент или более выше этого значения: отображаемое значение округлено и может быть немного ниже точной потреблённой стоимости, используемой при проверке.

curl -sS --fail-with-body "https://api.anthropic.com/v1/sessions/$SESSION_ID" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d @- <<'EOF'
{
  "budget": {
    "type": "limit",
    "max_list_cost": {"amount": "4000", "currency": "USD"}
  }
}
EOF



Удаление бюджета

Установите budget в null, чтобы полностью снять лимит. Приостановленная работа сессии возобновляется, а результирующее событие session.updated содержит budget, установленный в null.

curl -sS --fail-with-body "https://api.anthropic.com/v1/sessions/$SESSION_ID" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d '{"budget": null}'



Мониторинг расходов

Объект сессии содержит её budget и объект usage с отслеживаемыми расходами: usage.list_cost — это потреблённая прейскурантная стоимость сессии, а usage.active_seconds — время работы, на основе которого рассчитывается стоимость времени выполнения. Для сессии, приостановленной с budget_reached, ожидайте, что usage.list_cost будет равен max_list_cost или немного превышать его: запрос, пересёкший лимит, завершился до приостановки. active_seconds уровня сессии учитывает перекрывающуюся активность параллельных потоков один раз. Ответы на получение потока содержат те же два поля в собственном usage потока, рассчитанные для каждого потока отдельно. Значения по потокам округляются независимо и не включают стоимость времени работы сессии, поэтому их сумма не совпадает точно с list_cost сессии; именно значение сессии используется для применения бюджета.

Событие session.usage — это снимок накопленного использования и отслеживаемой прейскурантной стоимости сессии. Оно содержит суммарные токены сессии, list_cost, active_seconds, счётчики запросов server_tool_use (web_search_requests, включаемые в прейскурантную стоимость за каждый запрос, и web_fetch_requests, который равен 0, поскольку запросы веб-загрузки не имеют платы за запрос и не учитываются), а также копию budget сессии или null, если у сессии его нет. Оно появляется в списке событий и в потоке сессии. Сессия генерирует его непосредственно перед переходом в состояние простоя, независимо от причины остановки, поэтому сессия, достигшая своего бюджета, всегда генерирует его непосредственно перед событием простоя по достижении бюджета.

О чтении данных об использовании из потока и объекта сессии см. Отслеживание использования.



Бюджеты в мультиагентных сессиях

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

Ожидающий запрос имеет приоритет над лимитом: сессия, в которой один поток ожидает с requires_action, а другой приостановлен с budget_reached, сообщает requires_action на уровне сессии. Ожидающий запрос всё ещё требует ответа, а ответ на него — это завершающее событие, которое бюджет не блокирует.



Бюджеты в развёртываниях

Развёртывание принимает такой же объект budget при создании или обновлении:

{
  "budget": {
    "type": "limit",
    "max_list_cost": { "amount": "2000", "currency": "USD" }
  }
}

Лимит копируется в каждую сессию, которую запускает развёртывание, поэтому он ограничивает каждый запуск отдельно, а не совокупные расходы развёртывания. Изменение бюджета развёртывания применяется к сессиям, которые развёртывание запускает после этого, а не к уже работающим сессиям. В отличие от сессии, бюджет развёртывания можно очистить с помощью null и установить снова позже. См. Установка бюджета для каждого запуска.



Модели без прейскурантной цены

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

Если использование сессии с бюджетом начинает включать модель без прейскурантной цены, бюджет больше не может измерять расходы сессии: сессия может приостановиться со stop_reason, равным budget_reached, а изменение бюджета отклоняется. Удалите бюджет, чтобы возобновить сессию.



Справочник по ошибкам

Запросы, связанные с бюджетом, отклоняются в следующих случаях: