Запуск сессии

Сессия — это экземпляр агента внутри окружения. Каждая сессия ссылается на агента и окружение (оба создаются отдельно) и сохраняет историю разговора на протяжении нескольких взаимодействий. Сессии следуют двухэтапному жизненному циклу: сначала создайте сессию, чтобы подготовить её песочницу, затем отправьте пользовательское событие, чтобы начать работу.



Создание сессии

Для сессии требуются идентификатор agent и идентификатор environment. Агенты — это версионируемые ресурсы; передача идентификатора agent в виде строки запускает сессию с последней версией агента.

ant beta:sessions create \
  --agent "$AGENT_ID" \
  --environment-id "$ENVIRONMENT_ID"

Чтобы закрепить сессию за определённой версией агента, передайте объект. Это позволяет вам точно контролировать, какая версия запускается, и независимо планировать развёртывание новых версий.

ant beta:sessions create <<YAML
agent:
  type: agent
  id: $AGENT_ID
  version: 1
environment_id: $ENVIRONMENT_ID
YAML



Переопределение конфигурации агента для сессии

Вы можете передать agent в трёх формах: строка с идентификатором агента, объект с закреплённой версией (type: "agent") или объект переопределений. Форма с переопределениями изменяет части конфигурации агента для одной сессии. Используйте её, чтобы попробовать другую модель или предоставить дополнительный инструмент в одной сессии без создания новой версии агента. Для формы с переопределениями установите type в значение agent_with_overrides и передайте id агента и, при необходимости, version (опустите version, чтобы использовать последнюю версию агента). Затем включите любые из полей model, system, tools, mcp_servers или skills со значениями, которые должна использовать сессия.

Каждое переопределяемое поле подчиняется одним и тем же трём правилам:

• Опустите поле: сессия наследует значение из версии агента, на которую она ссылается.
• Установите поле в null или в пустой массив для полей-списков: сессия запускается с очищенным значением этого поля. Это правило полностью применяется к system, mcp_servers и skills. Есть два исключения:
  • model никогда нельзя очистить. Сессии всегда нужна модель, поэтому model: null возвращает ошибку 400 agent_model_required.
  • Очистка tools возвращает ошибку 400, если итоговое значение skills для сессии непустое, поскольку навыкам требуется инструмент read. В остальных случаях tools: null и tools: [] очищают поле.
• Установите поле в значение: значение полностью заменяет значение агента. Переопределения никогда не объединяются с конфигурацией агента, поэтому переопределение tools должно перечислять все инструменты, которые должны быть у сессии.

Переопределения применяются только к создаваемой вами сессии. Они не изменяют ресурс агента и не создают новую версию агента, поэтому другие сессии, ссылающиеся на того же агента, не затрагиваются.

В ответе объект agent отражает конфигурацию, с которой запускается сессия после применения переопределений. Его id и version по-прежнему идентифицируют агента и версию, к которым применены переопределения. Это позволяет вам отследить сессию до её базового агента.

# Поле `agent` в ответе — это разрешённый снимок: каждое переопределение заменяет это
# поле только для данной сессии, а ресурс агента сохраняет свои id и версию.
ant beta:sessions create \
  --transform 'agent.{id,version,model,system}' \
  --format json <<YAML
agent:
  type: agent_with_overrides
  id: $AGENT_ID
  model:
    id: claude-sonnet-5
  system: null
environment_id: $ENVIRONMENT_ID
YAML



Аутентификация MCP через хранилища

Если ваш агент использует инструменты MCP, требующие аутентификации, передайте vault_ids при создании сессии, чтобы сослаться на хранилище, содержащее сохранённые учётные данные OAuth. Anthropic управляет обновлением токенов от вашего имени. См. раздел Аутентификация с помощью хранилищ, чтобы узнать, как создавать хранилища и регистрировать учётные данные.

ant beta:sessions create <<YAML
agent: $AGENT_ID
environment_id: $ENVIRONMENT_ID
vault_ids:
  - $VAULT_ID
YAML



Запуск сессии

Создание сессии подготавливает песочницу окружения, но не запускает никакую работу. Чтобы делегировать задачу, отправьте события в сессию с помощью пользовательского события. Сессия действует как конечный автомат, отслеживающий прогресс, в то время как события управляют фактическим выполнением.

ant beta:sessions:events send \
  --session-id "$SESSION_ID" <<'YAML'
events:
  - type: user.message
    content:
      - type: text
        text: List the files in the working directory.
YAML

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

См. раздел Статусы сессии, чтобы узнать о статусах, через которые проходит сессия, и раздел Операции с сессиями для получения, перечисления, обновления, архивирования и удаления сессий.

Чтобы автоматически создавать сессии по повторяющемуся расписанию, см. раздел Запланированные развёртывания.