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

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



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

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



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

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

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



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

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



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

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, как и изменение фильтра created_at таким образом, что он исключает позицию курсора. Другие параметры запроса, включая остальные фильтры и 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), навыки, окружения и агенты являются независимыми ресурсами и не затрагиваются удалением сессии. Файлы, загруженные вами через Files API, также не затрагиваются, однако файлы, созданные самой сессией, привязаны к ней и безвозвратно удаляются вместе с её файловой системой. Скачайте всё, что вам нужно сохранить, перед удалением сессии.

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