Операции с сессиями

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

Статусы сессий

Сессии проходят через следующие статусы. Жизненный цикл сессии описан в разделе Запуск сессии.

Обновление конфигурации агента

Вы можете обновить agent.tools и agent.mcp_servers сессии, включая политики разрешений и веб-настройки отдельных инструментов, такие как фильтры доменов, прямо во время сессии без создания новой версии агента. Обновления действуют только в пределах сессии и не распространяются обратно на базовый агент. Обновлённые allowed_domains и blocked_domains применяются до конца сессии.

После создания сессии можно изменить только tools и mcp_servers агента. Чтобы запустить сессию со значениями model, system или skills, отличными от значений агента, используйте переопределения конфигурации агента при создании сессии. Конфигурацию модели агента, включая закрепление inference_geo, также нельзя изменить во время сессии: задайте закрепление при сохранении агента либо задайте или сбросьте его для отдельной сессии с помощью переопределения model при её создании. Настроенное поле system агента остаётся неизменным на протяжении всего времени жизни сессии. На моделях, которые это поддерживают, вы всё же можете добавлять указания системного уровня во время сессии, отправляя событие system.message.

Обновление tools или mcp_servers работает как полная замена: переданный массив становится новым значением. Чтобы сохранить существующие записи, выполните GET для сессии, измените массив и отправьте его обратно через POST.

Для обновления агента сессия должна находиться в статусе idle. Чтобы обновить агента, пока сессия выполняется, отправьте отдельно событие user.interrupt и дождитесь, пока сессия перейдёт в статус idle. Если открыт запуск рабочего процесса — выполняется он или приостановлен, — обновление возвращает ошибку 400, даже если сессия находится в статусе idle. Прерывание не завершает запуск, поэтому обновление по-прежнему завершается ошибкой после прерывания сессии. Отправьте user.message, в котором попросите агента остановить его запуски, или дождитесь завершения всех запусков.

client.beta.sessions.update(
    session.id,
    agent={
        "tools": [
            {"type": "agent_toolset_20260401"},
            {"type": "mcp_toolset", "mcp_server_name": "linear"},
        ],
        "mcp_servers": [
            {"type": "url", "name": "linear", "url": "https://mcp.linear.app/sse"}
        ],
    },
)

Обновление бюджета сессии

Сессия, созданная с бюджетом, принимает два вида обновления бюджета: замену лимита новым значением max_list_cost и его удаление путём передачи budget=None. Оба варианта автоматически возобновляют работу, приостановленную, когда сессия достигла своего лимита. Новый лимит может быть выше или ниже текущего, но он должен быть строго больше уже израсходованной сессией прейскурантной стоимости, а удаление необратимо: ненулевое значение budget принимается только для сессии, у которой в данный момент есть бюджет, поэтому нельзя повторно добавить удалённый бюджет или добавить его сессии, созданной без бюджета. Примеры запросов, поведение при ошибках и то, что учитывается в прейскурантной стоимости, см. в разделе Бюджеты сессий.

Получение сессии

retrieved = client.beta.sessions.retrieve(session.id)
print(f"Status: {retrieved.status}")

Перечисление сессий

Результаты GET /v1/sessions разбиваются на страницы. Используйте параметр запроса limit, чтобы управлять размером страницы. Каждый ответ содержит курсор next_page; передайте его в качестве параметра page в следующем запросе, чтобы получить следующую страницу. next_page равен null, когда результатов больше нет.

Чтобы вернуться на страницу назад, передайте prev_page в качестве параметра page. prev_page равен null, когда вы находитесь на первой странице.

Курсор page непрозрачен и кодирует order запроса, который его создал. Параметр запроса order задаёт направление сортировки результатов — asc или desc по времени создания; по умолчанию используется desc (сначала самые новые). Повторное использование курсора с другим значением order возвращает ошибку 400, как и изменение фильтра created_at таким образом, что он исключает позицию курсора. Другие параметры запроса, включая остальные фильтры и limit, могут меняться между постраничными запросами. Поля пагинации, общие для всех эндпоинтов списков, описаны в разделе Пагинация.

# Задаём небольшой `limit`, чтобы результаты заняли больше одной страницы.
first_page = client.beta.sessions.list(limit=1, agent_id=agent.id)
# `prev_page` равен None на первой странице; `next_page` равен None на последней.
print(f"prev_page: {first_page.prev_page}")
print(f"next_page: {first_page.next_page}")

# Передайте `next_page` обратно как `page`, чтобы получить следующую страницу.
second_page = client.beta.sessions.list(
    limit=1, agent_id=agent.id, page=first_page.next_page
)
for listed_session in second_page.data:
    print(f"{listed_session.id}: {listed_session.status}")

# Передайте `prev_page` обратно как `page`, чтобы вернуться на предыдущую страницу.
previous_page = client.beta.sessions.list(
    limit=1, agent_id=agent.id, page=second_page.prev_page
)
for listed_session in previous_page.data:
    print(f"{listed_session.id}: {listed_session.status}")
# Для итерации только вперёд объект страницы также можно перебирать напрямую.

Архивирование сессии

Архивируйте сессию, чтобы запретить отправку новых событий, сохранив при этом её историю. Сессию в статусе running нельзя архивировать; чтобы архивировать её, отправьте отдельно событие user.interrupt и дождитесь, пока сессия перейдёт в статус idle. Если открыт запуск рабочего процесса, архивирование может вернуть ошибку 400, даже если сессия находится в статусе idle, либо может завершиться успешно и завершить запуск. Перед архивированием отправьте user.message, в котором попросите агента остановить его запуски, или дождитесь завершения каждого запуска. Затем архивируйте сессию, когда она перейдёт в статус idle.

client.beta.sessions.archive(session.id)

Удаление сессии

Удалите сессию, чтобы безвозвратно удалить её запись, события и связанную с ней песочницу. Сессию в статусе running нельзя удалить; чтобы удалить её, отправьте отдельно событие user.interrupt и дождитесь, пока сессия перейдёт в статус idle. Если открыт запуск рабочего процесса, удаление может вернуть ошибку 400, даже если сессия находится в статусе idle, либо может завершиться успешно. После успешного удаления никакое событие workflow_run не сообщает о завершении запусков сессии. Перед удалением отправьте user.message, в котором попросите агента остановить его запуски, или дождитесь завершения каждого запуска. Затем удалите сессию, когда она перейдёт в статус idle.

Хранилища памяти, хранилища секретов (vaults), навыки, окружения и агенты являются независимыми ресурсами и не затрагиваются удалением сессии. Файлы, загруженные вами через Files API, также не затрагиваются, однако файлы, созданные самой сессией, привязаны к ней и безвозвратно удаляются вместе с её файловой системой. Скачайте всё, что вам нужно сохранить, перед удалением сессии. Выходной файл, записанный в конце последнего хода, может появиться в списке файлов сессии лишь через несколько секунд после перехода сессии в статус idle, поэтому сначала убедитесь, что ожидаемые файлы присутствуют в списке.

client.beta.sessions.delete(session.id)