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

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



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

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



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

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

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

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

Сессия должна быть в статусе idle для обновления агента. Прервите сессию, если вам нужно обновить агента, пока она выполняется.

ant beta:sessions update --session-id "$SESSION_ID" <<'YAML'
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
YAML



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

ant beta:sessions retrieve --session-id "$SESSION_ID"



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

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

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

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

# --format raw возвращает один конверт страницы с курсорами prev_page и next_page;
# вывод по умолчанию автоматически перебирает страницы и выдаёт только сессии.
cursors=$(ant beta:sessions list \
  --agent-id "$AGENT_ID" \
  --limit 1 \
  --format raw \
  --transform '{prev_page,next_page}')
printf '%s\n' "$cursors"

# Передайте курсор next_page обратно как --page, чтобы получить следующую страницу.
NEXT_PAGE=$(jq -r '.next_page' <<< "$cursors")
ant beta:sessions list \
  --agent-id "$AGENT_ID" \
  --limit 1 \
  --page "$NEXT_PAGE" \
  --format raw \
  --transform '{prev_page,next_page}'
# Передайте prev_page из этого ответа как --page, чтобы вернуться назад тем же способом.



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

Архивируйте сессию, чтобы предотвратить отправку новых событий, сохраняя при этом её историю. Сессия в статусе running не может быть заархивирована; отправьте событие прерывания, если вам нужно заархивировать её немедленно.

ant beta:sessions archive \
  --session-id "$SESSION_ID"



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

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

Файлы, хранилища памяти, хранилища секретов (vaults), навыки, окружения и агенты являются независимыми ресурсами и не затрагиваются удалением сессии.

ant beta:sessions delete \
  --session-id "$SESSION_ID"