Запуск сеанса

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

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

Для сеанса требуются ID agent и ID environment. Агенты — это версионируемые ресурсы; передача ID 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 проверяется и сохраняется до возврата ответа на создание, в порядке списка, с назначенным сервером ID — точно так же, как если бы вы отправили его на эндпоинт отправки событий сразу после создания. Правила содержимого для каждого события также совпадают с правилами этого эндпоинта. Пустой список эквивалентен отсутствию поля. Проверка выполняется по принципу «всё или ничего»: если какое-либо событие не проходит проверку, весь запрос отклоняется и сеанс не создаётся.

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

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

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

Вы можете передать agent в трёх формах: строка с ID агента, объект с закреплённой версией (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 по-прежнему идентифицируют агента и версию, к которым применены переопределения. Это позволяет проследить сеанс до его базового агента.

В следующем примере запускается сеанс, который переопределяет модель и очищает системную подсказку:

override_session = client.beta.sessions.create(
    agent={
        "type": "agent_with_overrides",
        "id": agent.id,
        "model": {"id": "claude-sonnet-5-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,
        # Полностью заменяет `model` агента: укажите `id` заново, добавьте `inference_geo` для привязки.
        "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 — это целое число центов США, записанное в виде строки, например "125" для $1,25. API принимает строку, а не число, чтобы никогда не применялось округление с плавающей запятой. USD — единственная поддерживаемая в настоящее время валюта. Когда сеанс достигает лимита, он приостанавливается и переходит в состояние простоя с причиной остановки budget_reached. Лимит применяется между запросами к модели, поэтому запрос, который его превышает, сначала завершается, и итоговая прейскурантная стоимость сеанса может оказаться немного выше лимита. Бюджет можно прикрепить только при создании: позже вы можете изменить или удалить его, но не можете добавить бюджет к сеансу, созданному без него.

В следующем примере создаётся сеанс с бюджетом $1,25:

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    budget={
        "type": "limit",
        "max_list_cost": {"amount": "125", "currency": "USD"},
    },
)
print(session.id, session.budget.max_list_cost.amount)  # sesn_01... 125

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

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

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

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

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

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

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

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

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

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