Агенты, сессии и окружения

Модель данных Managed Agents стоит на трёх сущностях: Agent, Session и Environment. Правильное распределение ролей между ними — обязательный первый шаг: агент создаётся один раз и версионируется, сессия — это один запуск, окружение — шаблон контейнера. Смешивание ролей (например, попытка задать модель на уровне сессии) — самый частый источник ошибок при работе с этим API.

Как это работает

Agent (/v1/agents) — персистентная, версионируемая конфигурация: модель, системный промпт, инструменты, MCP-серверы и skills. Каждое обновление создаёт неизменяемую версию; сессия может закрепиться за конкретной версией — это даёт воспроизводимость и безопасный откат при регрессиях промпта. Session (/v1/sessions) — один stateful-запуск: ссылается на агента по ID и на environment_id, подключает ресурсы — файлы, GitHub-репозитории, memory stores — и vault_ids с учётными данными MCP. Environment (/v1/environments) — переиспользуемый шаблон контейнера. Тип cloud означает контейнер в инфраструктуре Anthropic с настройкой сети: unrestricted либо limited со списком allowed_hosts. Тип self_hosted переносит выполнение инструментов в вашу инфраструктуру через воркер с исходящим polling — цикл агента при этом остаётся на стороне Anthropic, наружу ничего не «дозванивается». Жизненный цикл сессии: rescheduling → running ↔ idle → terminated. Кэширование промптов, автоматическая компактизация контекста и extended thinking включены на уровне платформы — отдельно настраивать их не нужно.

Когда применять

Создавайте отдельного агента на каждую роль и меняйте его поведение обновлениями, а не созданием новых объектов: правило простое — «создать один раз, ссылаться по ID». В продакшн-сессиях закрепляйте версию агента, чтобы обновление конфигурации не ломало уже идущие запуски. Окружение cloud — вариант по умолчанию; self_hosted — когда код и данные не должны покидать вашу инфраструктуру. Для мультиагентных задач настройте координатора с ростером до 20 агентов: сабагенты выполняются как потоки (до 25 одновременно), разделяют файловую систему, но не историю разговора, и допускается только один уровень делегирования — глубже иерархия не строится.

Типичные ошибки

Вызов agents.create() при каждом запуске — анти-паттерн: накапливаются осиротевшие объекты и теряется смысл версионирования. Модель, системный промпт и инструменты принадлежат агенту, а не сессии — сессия принимает только ссылку. При сети limited не забывайте перечислить нужные внешние хосты в allowed_hosts, иначе инструменты не смогут до них достучаться. В мультиагентных сценариях не рассчитывайте, что сабагенты видят историю разговора друг друга — общая у них только файловая система. Наконец, Managed Agents доступен в first-party API и на Claude Platform on AWS, но не на Amazon Bedrock, Google Vertex или Microsoft Foundry.

Как это работает

Когда применять

Типичные ошибки

Связанные понятия

Полезные ресурсы