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

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

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

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

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
)

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

pinned_session = client.beta.sessions.create(
    agent={"type": "agent", "id": agent.id, "version": 1},
    environment_id=environment.id,
)

Инициализация сессии начальными событиями

Вы можете создать сессию и начать её работу одним вызовом. initial_events — это необязательный массив начальных событий, отправляемых в сессию при создании и обрабатываемых по порядку. Он поддерживает события user.message и user.define_outcome и принимает максимум 50 событий. Непустой список запускает цикл агента в том же вызове: сессия создаётся сразу в статусе running, без дополнительного запроса.

Следующий пример создаёт сессию с одним событием user.message в initial_events:

seeded_session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    initial_events=[
        {
            "type": "user.message",
            "content": [
                {"type": "text", "text": "List the files in the working directory."}
            ],
        },
    ],
)
# initial_events не возвращаются в ответе на создание; читаем их
# из списка событий сессии.
for event in client.beta.sessions.events.list(seeded_session.id):
    if event.type == "user.message":
        for block in event.content:
            if block.type == "text":
                print(f"Seeded event: {block.text}")

Никакие другие типы событий не принимаются. События, отвечающие на ход агента (user.tool_confirmation, user.tool_result и user.custom_tool_result), не принимаются, поскольку ход агента ещё не существует, а user.interrupt не принимается, поскольку нет хода, который можно было бы остановить. В отличие от initial_events в запланированном развёртывании, initial_events сессии не принимают system.message.

Каждое событие в initial_events проверяется и сохраняется до возврата ответа на создание, в порядке списка, с идентификатором, назначенным сервером, — точно так же, как если бы вы отправили его на конечную точку отправки событий сразу после создания. Правила для содержимого каждого события также совпадают с правилами этой конечной точки. Пустой список эквивалентен отсутствию поля. Проверка выполняется по принципу «всё или ничего»: если какое-либо событие не проходит проверку, весь запрос отклоняется и сессия не создаётся.

Запрос на создание отклоняется в следующих случаях:

Событие user.define_outcome в initial_events принимается при тех же условиях, что и при отправке его в существующую сессию; см. Определение результатов.

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

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

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

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

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

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

Следующий пример запускает сессию, которая переопределяет модель и очищает «system prompt» (системную подсказку):

override_session = client.beta.sessions.create(
    agent={
        "type": "agent_with_overrides",
        "id": agent.id,
        "model": {"id": "claude-sonnet-5"},
        "system": None,  # clear the agent's system prompt for this session
    },
    environment_id=environment.id,
)
# Агент в ответе — это разрешённый снимок с применёнными переопределениями.
print(f"Model: {override_session.agent.model.id}")
print(f"System: {override_session.agent.system}")

Закрепление географии инференса для сессии

Поскольку переопределение model полностью заменяет объект model агента, оно также устанавливает или снимает закрепление inference_geo модели для сессии: переопределение, включающее inference_geo, закрепляет географию, обслуживающую запросы сессии к модели, а переопределение, в котором оно опущено, снимает закрепление агента, так что сессия следует default_inference_geo рабочего пространства. Переопределённое значение проверяется на соответствие allowed_inference_geos рабочего пространства при создании сессии.

Следующий пример запускает сессию от агента, модель которого не имеет географического закрепления, закрепляет запросы сессии к модели за инференсом в США, включая inference_geo в переопределение model, и выводит значение, возвращённое в agent.model ответа:

session = client.beta.sessions.create(
    agent={
        "type": "agent_with_overrides",
        "id": agent.id,
        # Replaces the agent's `model` in full: restate `id`, add `inference_geo` to pin.
        "model": {"id": "claude-opus-5-5", "inference_geo": "us"},
    },
    environment_id=environment.id,
)
print(f"Inference geo: {session.agent.model.inference_geo}")

Установка бюджета сессии

Чтобы ограничить расходы сессии, передайте необязательный объект budget при её создании. Бюджет — это жёсткий потолок стоимости сессии по прейскуранту: платформа оценивает всё, что потребляет сессия, по публичным прейскурантным тарифам, и сессия прекращает отправлять новые запросы к модели, как только эта нарастающая сумма достигает max_list_cost. Установите type в limit и задайте для max_list_cost значения amount и currency. amount — это целое число центов США, записанное в виде строки, например "2500" для $25,00; API принимает строку, а не число, чтобы никогда не применялось округление с плавающей запятой. USD — единственная поддерживаемая в настоящее время валюта. Когда сессия достигает лимита, она приостанавливается и переходит в состояние ожидания с причиной остановки budget_reached. Лимит применяется между запросами к модели, поэтому запрос, который его пересекает, сначала завершается, и итоговая стоимость сессии по прейскуранту может оказаться немного выше лимита. Бюджет можно прикрепить только при создании: вы можете изменить или удалить его позже, но не можете добавить его к сессии, созданной без него.

Следующий пример создаёт сессию с бюджетом $25,00; ответ возвращает budget в ресурсе сессии:

curl -fsSL https://api.anthropic.com/v1/sessions \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d @- <<EOF
{
  "agent": "$AGENT_ID",
  "environment_id": "$ENVIRONMENT_ID",
  "budget": {
    "type": "limit",
    "max_list_cost": {"amount": "2500", "currency": "USD"}
  }
}
EOF

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

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

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

vault_session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    vault_ids=[vault.id],
)

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

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

client.beta.sessions.events.send(
    session.id,
    events=[
        {
            "type": "user.message",
            "content": [
                {"type": "text", "text": "List the files in the working directory."}
            ],
        },
    ],
)

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

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

Следующие шаги