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

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

Задание бюджета при создании сессии

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

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    budget={
        "type": "limit",
        "max_list_cost": {"amount": "125", "currency": "USD"},
    },
)
print(session.id, session.budget.max_list_cost.amount)  # sesn_01... 125

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

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

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

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

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

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

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

Для применения лимита используется точная, неокруглённая прейскурантная стоимость. Значения 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.

Если открыты запуски рабочих процессов, каждый из них, который ещё не находится в простое, также получает событие workflow_run.status_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, отправленное, пока сессия приостановлена на уровне бюджета (все потоки приостановлены на лимите), принимается, и оно не появляется в списке событий. Оно не останавливает ни один поток, потому что каждый поток уже приостановлен. Чтобы продолжить, измените или удалите бюджет.

Если у сеанса есть открытые запуски рабочих процессов, прерывание может приостановить их, как и прерывание в любое другое время. Запуск, приостановленный прерыванием, не возобновляется при изменении или удалении бюджета. Чтобы продолжить его, измените или удалите бюджет, а затем отправьте user.message с просьбой к агенту продолжить его запуски. См. Прерывание сеанса с открытыми запусками.

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

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

Каждый запуск рабочего процесса, приостановленный бюджетом, также получает событие workflow_run.status_running. Запуск, приостановленный прерыванием, даже если оно было отправлено, пока сессия находилась на уровне бюджета, остаётся приостановленным и не получает события workflow_run.status_running в результате обновления. Чтобы продолжить его, отправьте user.message с просьбой к агенту продолжить свои запуски. См. Прерывание сессии с открытыми запусками.

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

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

updated_session = client.beta.sessions.update(
    session.id,
    budget={
        "type": "limit",
        "max_list_cost": {"amount": "500", "currency": "USD"},
    },
)
print(updated_session.budget.max_list_cost.amount)  # 500

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

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

unbudgeted_session = client.beta.sessions.update(session.id, budget=None)
print(unbudgeted_session.budget)  # None

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

Объект сеанса содержит его 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 сессии, если он у неё есть. Оно появляется в списке событий и в потоке сессии. Сессия отправляет его непосредственно перед переходом в состояние idle, какой бы ни была причина остановки, поэтому сессия, достигшая своего бюджета, всегда отправляет его непосредственно перед событием idle, связанным с достижением бюджета.

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

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

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

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

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

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

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

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

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

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

• Агент сеанса
• Любой агент, указанный в списке predefined_agents в subagents или workflows
• Советник, заданный в многоагентной конфигурации агента

В ошибке указывается, что для модели нет прейскурантной цены.

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

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

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

Доступность