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

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

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

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

# Оставьте сумму в кавычках, чтобы она отправлялась как строка, а не число.
SESSION_ID=$(ant beta:sessions create \
  --agent "$AGENT_ID" \
  --environment-id "$ENVIRONMENT_ID" \
  --budget '{type: limit, max_list_cost: {amount: "125", currency: USD}}' \
  --transform id --raw-output)

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

• type всегда равен "limit".
• max_list_cost — это сам лимит: amount — целое число центов США, записанное строкой без ведущих нулей ("125" — это $1,25, а "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". Это ожидаемо и не является ошибкой биллинга, а превышение ограничено одним запросом к модели на поток. Рассматривайте бюджет как ограничение на новую работу, а не как точную точку остановки, и выбирайте размер лимита с учётом этого запаса в один запрос.

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

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

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

ant beta:sessions update \
  --session-id "$SESSION_ID" \
  --budget '{type: limit, max_list_cost: {amount: "500", currency: USD}}'

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

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

ant beta:sessions update --session-id "$SESSION_ID" --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, поскольку запросы web fetch не имеют платы за запрос и не учитываются), а также копию budget сессии или null, если у сессии его нет. Оно появляется в списке событий и в потоке сессии. Сессия отправляет одно такое событие непосредственно перед переходом в состояние idle, независимо от причины остановки, поэтому сессия, достигшая бюджета, всегда отправляет его непосредственно перед событием idle о достижении бюджета.

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

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

Мультиагентная сессия имеет единый бюджет, общий для всех её потоков; лимитов на отдельные потоки нет. Потребление каждого потока оценивается по его собственной обслуживающей модели, и потоки приостанавливаются независимо по мере достижения общего лимита. Консультации советника учитываются в том же бюджете и оцениваются по тарифам модели советника. Один поток может приостановиться с 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, а изменение бюджета отклоняется. Удалите бюджет, чтобы возобновить сессию.

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

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