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

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



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

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



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

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