Что такое управляемые агенты
До сих пор агентный цикл жил в вашем коде: вы вызывали API, выполняли инструменты, следили за контекстом, хостили всё это. Managed Agents (управляемые агенты) переносят цикл и рабочее окружение агента к Anthropic. В этом уроке разберём, что это такое, из каких понятий состоит и когда этот путь лучше собственного цикла. На момент написания курса Managed Agents в бете: интерфейс может уточняться, сверяйтесь с документацией.
Четыре способа собрать агента
Полезно сначала увидеть, где Managed Agents стоят среди других вариантов. Два независимых вопроса: кто крутит цикл и кто хостит.
| Способ | Что пишете вы | Цикл | Хостинг |
|---|---|---|---|
| Ручной цикл на Messages API | Весь цикл и инструменты | Вы | Вы |
| Tool runner из SDK | Только функции инструментов | SDK | Вы |
| Managed Agents | Конфигурацию агента и обработку событий | Anthropic | Anthropic (контейнер на сессию) |
| Claude Agent SDK | Промпт и настройки | Библиотека Claude Code | Вы |
Первые два мы уже прошли. Четвёртый — отдельный продукт: Claude Code, упакованный в библиотеку со встроенными инструментами для файлов и bash; про него есть курс по Claude Code. Managed Agents — единственный вариант, где вы не хостите ничего: ни цикл, ни песочницу, где агент выполняет команды.
Как это устроено
В Managed Agents четыре понятия, и порядок их создания строгий.
Агент (/v1/agents) — сохранённая, версионированная конфигурация: модель, системный промпт, инструменты, MCP-серверы, навыки. Создаётся один раз. Каждое изменение создаёт новую версию, старые остаются доступными.
Среда (/v1/environments) — шаблон контейнера: тип (облачный у Anthropic или самостоятельно размещённый), сетевые правила.
Сессия (/v1/sessions) — один запуск агента в среде. Ссылается на агента по идентификатору (можно закрепить версию), получает ресурсы (файлы, репозиторий) и живёт, пока идёт работа.
События — то, чем вы обмениваетесь с сессией. Вы отправляете user.message (сообщение), user.custom_tool_result (результат вашего инструмента), user.tool_confirmation (подтверждение опасного действия), user.interrupt (остановить). Сессия отдаёт поток: agent.message (текст), agent.tool_use и agent.tool_result (встроенные инструменты), agent.custom_tool_use (вызов вашего инструмента), session.status_idle (агент ждёт вас), session.status_terminated (сессия завершена).
Цикл при этом крутится на оркестраторе Anthropic, а в контейнере выполняются инструменты: bash, файлы, код. Вы подключаетесь к потоку событий и реагируете.
Что агент умеет из коробки
Набор встроенных инструментов agent_toolset_20260401 включает bash, read, write, edit, glob, grep, web_search и web_fetch. Это примерно тот же набор, что у Claude Code, и его достаточно, чтобы агент клонировал репозиторий, прочитал код, запустил тесты и написал отчёт. Инструменты включаются все сразу или выборочно, а для каждого можно задать политику: always_allow (выполнять сразу) или always_ask (остановиться и ждать вашего user.tool_confirmation).
К этому добавляются MCP-серверы (те же mcp_servers и mcp_toolset, что в уроке про MCP, только учётные данные хранятся отдельно, в хранилищах, которые Anthropic сама обновляет), навыки и ваши собственные инструменты. Свой инструмент работает через события: агент отправляет agent.custom_tool_use, сессия переходит в idle, ваш код выполняет действие и отвечает user.custom_tool_result.
Сессия сама заботится о контексте: компакция и кэширование включены по умолчанию, режим рассуждения тоже. Всё, чем мы управляли вручную в прошлом уроке, здесь происходит без вашего участия.
Чем это отличается от своего цикла
Главное отличие — состояние. В Messages API каждый запрос начинается с чистого листа, и историю храните вы. В Managed Agents история живёт в сессии: вы отправляете новое сообщение, и агент помнит всё предыдущее. Можно отправить три сообщения подряд, не дожидаясь ответа, — они встанут в очередь и будут обработаны по порядку.
Второе — рабочее место. У сессии есть контейнер с файловой системой. Можно примонтировать репозиторий по адресу или загруженный файл, и агент будет работать с ними как с локальными. Файлы, которые агент создал, потом скачиваются.
Третье — версионирование. Агент — объект с историей версий. Вы улучшили системный промпт ревьюера — сессии, которые уже идут, продолжают работать на старой версии, новые получают новую. Регрессия — закрепляете предыдущую версию, пока разбираетесь.
Четвёртое — наблюдаемость. У каждой сессии есть страница в консоли на platform.claude.com с полной трассой: сообщения, вызовы инструментов с параметрами и результатами, расход. Для отладки агента это удобнее любых логов.
Когда выбирать Managed Agents
Managed Agents оправданы, когда нужен агент с рабочим окружением (файлы, репозиторий, bash), а хостить песочницу самим не хочется; когда важны версионирование и трасса; когда агент должен работать долго и многоходово; когда его нужно запускать по расписанию (для этого есть отдельный механизм развёртываний). Ревьюер PR из нашего курса — типичный кандидат: ему нужен клон репозитория и запуск тестов.
Собственный цикл на Messages API лучше, когда инструменты — это ваши сервисы и никакой песочницы не нужно (классификатор, бот портала с MCP), когда вы хотите полностью контролировать, что попадает в контекст, когда работаете через облачного провайдера, где Managed Agents недоступны, или когда просто не хотите бета-зависимость в проде.
Есть и цена вопроса: помимо токенов оплачивается время работы сессии. Актуальные условия — в документации и консоли; в курсе цифры не приводим.
Два правила, которые чаще всего нарушают
Агент создаётся один раз. Вызов agents.create в обработчике каждого запроса плодит осиротевшие объекты и ломает версионирование. Создайте агента в скрипте настройки, сохраните идентификатор в конфигурации, а в рабочем коде создавайте только сессии. Менять поведение — через обновление существующего агента, не через создание нового.
Модель, промпт и инструменты живут на агенте, не на сессии. Сессия принимает только ссылку на агента, среду и ресурсы. Если вы пишете sessions.create с полем system, это ошибка проектирования. (Есть форма с переопределениями для одной сессии, но это исключение для экспериментов, а не основной путь.)
В следующем уроке соберём ревьюера PR как управляемого агента и увидим всё это в коде.
Попробуйте сами
10–15 мин на рабочем месте- Возьмите таблицу четырёх способов и отнесите к одному из них каждую из четырёх задач курса: классификатор, помощник аналитика, ревьюер PR, бот портала. Аргументируйте.
- Откройте в консоли на platform.claude.com раздел Managed Agents (если он доступен вашей организации) и посмотрите, как выглядит страница сессии. Пока ничего создавать не нужно.
- Для ревьюера PR составьте список: какие встроенные инструменты ему нужны, какие поставить на
always_ask, какой свой инструмент понадобится.
Коротко
- Managed Agents: Anthropic крутит агентный цикл и хостит контейнер, где выполняются инструменты. На момент написания — бета.
- Четыре понятия: агент (версионированная конфигурация), среда (шаблон контейнера), сессия (запуск), события (обмен).
- Встроенный набор
agent_toolset_20260401: bash, файлы, поиск, веб; политикиalways_allow/always_ask. - Сессия хранит историю, имеет файловую систему, сама делает компакцию и кэширование.
- Агент создаётся один раз; модель, промпт и инструменты живут на агенте, не на сессии.
- Свой цикл лучше, когда песочница не нужна или нужен полный контроль над контекстом.
Видеоверсия
Сценарий озвучки · 475 слов, ≈ 4 мин
До сих пор агентный цикл жил в вашем коде: вы вызывали API, выполняли инструменты, следили за контекстом и хостили всё это сами. Управляемые агенты переносят цикл и рабочее окружение к Anthropic. В этом уроке разберём, что это такое и когда это нужно. Сразу оговорка: на момент записи это бета, детали могут уточняться.
Сначала место среди других вариантов. Агента можно собрать четырьмя способами, и различаются они двумя вопросами: кто крутит цикл и кто хостит. Ручной цикл — всё делаете вы. Tool runner из SDK — цикл крутит библиотека, хостите вы. Claude Agent SDK — это Claude Code, упакованный в библиотеку, цикл его, хостинг ваш. И управляемые агенты — единственный вариант, где вы не хостите ничего: ни цикл, ни песочницу.
Как это устроено. Четыре понятия. Агент — сохранённая версионированная конфигурация: модель, системный промпт, инструменты, MCP-серверы, навыки. Создаётся один раз, каждое изменение — новая версия. Среда — шаблон контейнера: облачный или на вашей инфраструктуре, сетевые правила. Сессия — один запуск агента в среде: ссылка на агента, ресурсы вроде репозитория или файлов. И события — то, чем вы обмениваетесь с сессией. Вы отправляете сообщение, результат своего инструмента, подтверждение опасного действия или команду остановиться. Сессия отдаёт поток: текст агента, вызовы инструментов и их результаты, запрос на ваш инструмент, статус «жду вас» и статус «завершено».
Из коробки агент умеет примерно то же, что Claude Code: bash, чтение и правка файлов, поиск по файлам, поиск в интернете. Этого достаточно, чтобы клонировать репозиторий, прочитать код, запустить тесты и написать отчёт. Для каждого инструмента задаётся политика: выполнять сразу или остановиться и ждать вашего подтверждения. К этому добавляются MCP-серверы, навыки и ваши собственные инструменты, которые работают через события: агент просит, сессия останавливается, вы выполняете и отвечаете.
Чем это отличается от своего цикла. Первое — состояние: история живёт в сессии, вы просто отправляете следующее сообщение. Можно отправить три подряд, они встанут в очередь. Второе — рабочее место: у сессии есть файловая система, куда монтируются репозиторий и файлы. Третье — версионирование: улучшили промпт ревьюера — текущие сессии продолжают на старой версии, новые получают новую; регрессия — закрепили предыдущую. Четвёртое — наблюдаемость: у каждой сессии есть страница в консоли с полной трассой вызовов и расходом. Контекстом сессия управляет сама: компакция и кэширование включены по умолчанию.
Когда это выбирать. Когда агенту нужно рабочее окружение — файлы, репозиторий, bash, — а хостить песочницу не хочется. Когда важны версии и трасса. Когда агент работает долго или по расписанию. Ревьюер пул-реквестов — типичный кандидат. Свой цикл лучше, когда инструменты — это ваши сервисы и песочница не нужна, как у классификатора или бота портала, когда нужен полный контроль над контекстом, или когда бета-зависимость в проде нежелательна. И помните, что помимо токенов оплачивается время работы сессии — условия смотрите в документации.
Два правила, которые нарушают чаще всего. Агент создаётся один раз: не вызывайте создание в обработчике каждого запроса, сохраните идентификатор в конфигурации и в рабочем коде создавайте только сессии. И модель, промпт, инструменты живут на агенте, а не на сессии: сессия принимает только ссылку. В следующем уроке соберём ревьюера как управляемого агента в коде.