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

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

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

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

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