Claude Managed Agents 22 июля: три дыры для поллинга закрыты одним релизом

22 июля Anthropic выпустила пять изменений для Claude Managed Agents API. Три из них устраняют одну и ту же фундаментальную проблему: операторы были вынуждены использовать поллинг или лишние сетевые запросы, чтобы узнать о готовности ресурсов. В этой статье рассмотрены именно эти три изменения и объяснено, что нужно сделать, чтобы воспользоваться ими.

Два остальных изменения — опциональность поля version при обновлении агента и добавление effort в конфигурацию модели агента — реальные, но достаточно узкие, чтобы остаться в разделе приложений.

Три дыры, которые закрывает релиз от 22 июля

До 22 июля в событийной модели Managed Agents наблюдались следующие ловушки для поллинга:

1. Холодный старт сессии требовал двух последовательных вызовов: POST /v1/sessions для создания сессии, затем отдельный POST /v1/sessions/{id}/events для отправки первого сообщения пользователя. Любой вызывающий код, которому нужно было немедленно начать работу, должен был ждать первого ответа перед вторым запросом.

2. Вывод субагента (потока) был непрозрачен до завершения: Потоковый эндпоинт уровня сессии (GET /v1/sessions/{id}/stream) позволял просматривать генерацию текста агента верхнего уровня, но если оркестратор делегировал работу субагенту, потоковая передача вывода субагента была недоступна — только финальный агрегированный результат.

3. Готовность окружений и хранилищ памяти требовала поллинга: При создании, архивировании или сбое окружения, а также при создании, обновлении или удалении хранилища памяти единственным способом реагирования был периодический опрос GET /v1/environments/{id} или GET /v1/memory_stores/{id}.

Все три дыры теперь закрыты.

initial_events: два вызова объединяются в один

POST /v1/sessions теперь принимает поле initial_events. Передайте до 50 событий — любую комбинацию user.message и user.define_outcome — и агентный цикл запустится в том же вызове. Непустого списка достаточно; отдельный вызов POST /v1/sessions/{id}/events не нужен.

До 22 июля:

# Шаг 1: создание сессии
session=$(curl -fsSL https://api.anthropic.com/v1/sessions \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d '{"agent":"$AGENT_ID","environment_id":"$ENV_ID"}')
SESSION_ID=$(jq -r '.id' <<< "$session")

# Шаг 2: отправка первого сообщения — отдельный сетевой вызов, отдельная задержка
curl -fsSL "https://api.anthropic.com/v1/sessions/$SESSION_ID/events" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d '{"events":[{"type":"user.message","content":[{"type":"text","text":"Запустить аудит"}]}]}'

После 22 июля:

session=$(curl -fsSL https://api.anthropic.com/v1/sessions \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d '{
    "agent": "$AGENT_ID",
    "environment_id": "$ENV_ID",
    "initial_events": [
      {
        "type": "user.message",
        "content": [{"type": "text", "text": "Запустить аудит"}]
      }
    ]
  }')
# Агент уже работает. SESSION_ID находится в ответе.

Практическая экономия — один сетевой round-trip при каждом холодном старте. Если вы запускаете сессии в ответ на действия пользователей — ходы в чате, webhook-триггеры, запланированные задания — этот round-trip находится на критическом пути. При высокой нагрузке это также добавляет ещё один класс запросов в учёт параллелизма вашего шлюза.

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

Потоковая передача дельт на уровне потоков: субагенты теперь отправляют текст в реальном времени

Когда Claude Managed Agent оркестрирует субагентов, каждый субагент выполняется в отдельном потоке. Потоковый эндпоинт уровня сессии (GET /v1/sessions/{id}/stream) принимал параметр запроса event_deltas[], позволявший предварительно просматривать генерацию текста модели верхнего уровня. Потоки (threads) такой возможности не имели.

С 22 июля GET /v1/sessions/{session_id}/threads/{thread_id}/stream принимает тот же параметр event_deltas[].

curl -N "https://api.anthropic.com/v1/sessions/$SESSION_ID/threads/$THREAD_ID/stream?event_deltas[]=text_delta" \
  -H "anthropic-beta: managed-agents-2026-04-01"

Соединение потокового потока просматривает только тот поток, на который нацелено — агрегирование по потокам не происходит. Если у вас есть оркестратор с тремя субагентами, работающими параллельно, для одновременной потоковой передачи всех трёх нужно три отдельных SSE-соединения.

Значение для архитектуры маршрутизации: в мультиагентных пайплайнах поток оркестратора обычно короток — он делегирует и ждёт. Бюджет задержки определяется потоками субагентов. До этого изменения единственными способами показа постепенного прогресса downstream-пользователю были: (а) потоковая передача сессии верхнего уровня с разрозненными комментариями оркестратора; (б) периодический опрос журнала событий потока. Оба варианта неудовлетворительны. Потоковые дельты на уровне потоков позволяют в реальном времени проксировать вывод конкретного потока на фронтенд — так же, как вы бы проксировали прямой вызов API.

Полезная комбинация: webhook session.thread_created → открыть потоковое соединение потока → передавать текстовые дельты клиенту. Этот трёхшаговый паттерн теперь работает сквозно без поллинга на любом этапе.

Семь новых типов webhook-событий: прекратите поллинг окружений и хранилищ памяти

Каталог webhook-событий Managed Agents теперь охватывает полный жизненный цикл двух типов ресурсов, поллинг которых ранее был вынужденной мерой.

События окружений (4 типа):

События хранилища памяти (3 типа):

Полезные нагрузки webhook-событий следуют существующему паттерну: передают тип события и его ID, а не полный объект ресурса. При получении webhook нужно получить текущее состояние ресурса вызовом GET. Это сохраняет каждую доставку компактной и исключает устаревшие данные при повторных попытках.

Что происходило раньше: если ваша операторская инфраструктура динамически создаёт окружения (одно на тенант, одно на деплой и т.д.), у вас не было push-сигнала о готовности. Типичный обходной путь: опрашивать GET /v1/environments/{id} каждые несколько секунд, проверять status, сдаваться после N попыток. Та же проблема для хранилищ памяти в воркфлоу, которые создают их и сразу подключают к сессиям.

Что можно делать теперь: зарегистрировать webhook-эндпоинт, перехватывающий environment.created и environment.failed, при получении загружать объект окружения и маршрутизировать соответственно. Один обработчик webhook заменяет цикл поллинга и его шаблонный код обработки ошибок.

Операционная заметка: эти события подчиняются той же семантике «доставить хотя бы один раз», что и другие webhook-события Managed Agents. Ваш обработчик должен быть идемпотентным по ID события. Если вы уже обрабатываете webhook жизненного цикла сессий, это требование вы уже выполняете.

Кросс-провайдерный контекст

Realtime Agents от OpenAI и Managed Agents от Gemini оба поддерживают webhook-события жизненного цикла сессий, но ни один из них на момент написания этой статьи не предоставляет операторам события жизненного цикла окружений или хранилищ памяти. Тип события environment.failed — push-уведомление о сбое при создании облачной песочницы — не имеет аналогов в других конкурирующих фреймворках; поллинг готовности песочницы остаётся нормой в других местах.

Потоковая передача на уровне потоков также отличается: Managed Agents от Gemini транслируют вывод оркестратора, но не предоставляют потоковую передачу на уровне субагентов; у OpenAI нет SSE с областью видимости потока для текста субагентов. Если вашей архитектуре маршрутизации нужно показывать прогресс субагентов в UI — это распространённое требование для агентов написания кода и исследовательских агентов с видимыми параллельными рабочими потоками — потоковая передача потоков в Claude в настоящее время является единственным способом получить текстовые дельты отдельного субагента без собственной инфраструктуры логирования.

Дополнения: version и effort

version при обновлении агента теперь опционален: PATCH /v1/agents/{id} ранее требовал version для оптимистичного управления параллелизмом. Теперь это опционально. Опустите поле для безусловного применения обновлений; включите для получения 409 при несовпадении версий. Если ваш код передавал текущую версию как обязательное поле — изменений не требуется. Если вы обходили это требование, всегда получая данные перед обновлением, теперь можно упростить логику.

effort в конфигурации модели агента: при создании или обновлении агента теперь можно задать effort внутри объекта model. Это дополняет существующий механизм переопределения конфигурации на уровне сессии — effort можно задать на уровне определения агента и переопределить для отдельной сессии. Удобно, когда вы хотите лёгкий вариант по умолчанию и более «тяжёлое» переопределение для конкретных типов задач, маршрутизируемых к одному и тому же агенту.

{
  "model": {
    "name": "claude-sonnet-5-20261015",
    "effort": "low"
  }
}

Уровни effort (low, medium, high) ведут себя так, как описано в справочнике по уровням effort от Anthropic. Если вы уже используете переопределения effort на уровне сессии (рассмотрены в релизе от 2 июля), это даёт более чистый путь для установки значений по умолчанию на уровне определения агента, не требуя от каждого создателя сессии передавать переопределение.

Что изменить в архитектуре маршрутизации

Эти изменения обратно совместимы. Ничего не сломается. Но три вещи стоит обновить:

1. Код инициализации сессии: если вы создаёте и отправляете в два шага, объедините через initial_events. Один round-trip убирается из каждого холодного старта сессии.

2. Обработчик webhook: добавьте обработку environment.* и memory_store.*. Если у вас есть где-либо цикл поллинга, проверяющий статус окружения или хранилища памяти, его можно заменить, как только обработчик webhook покроет новые типы событий.

3. Рендеринг интерфейса мультиагента: если вы отображаете активность субагентов пользователям, добавьте отслеживание ID потоков из событий session.thread_created и открывайте потоковые соединения для каждого субагента. Прежний подход (потоковая передача уровня сессии с разрозненными комментариями оркестратора) недооценивает то, что реально происходит внутри запуска.

Опциональное изменение version и effort на уровне агента — аддитивные дополнения, не требующие изменений, если только вы не хотите упростить существующий код.