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

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

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

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

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

Вы можете обновить 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.

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

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

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

Удалите сессию, чтобы безвозвратно удалить её запись, события и связанную с ней песочницу. Сессию в статусе running нельзя удалить; чтобы удалить её, отправьте событие user.interrupt отдельно и дождитесь, пока сессия перейдёт в статус idle.

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

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