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

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

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

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

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

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

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 нельзя архивировать; чтобы архивировать её, отправьте событие user.interrupt отдельно и дождитесь, пока сессия перейдёт в статус idle.

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

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

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

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

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