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

«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, а "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 и позже установить снова. См. Установка бюджета для каждого запуска.

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

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

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

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

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