Декомпозиция агента: навыки вместо длинного промпта
Тема 3/4: Архитектура агента → Урок 1/5
Агент, который начинался с одной задачи, со временем обрастает возможностями: системный промпт разрастается до сотен строк, инструментов становятся десятки, и вместо прежней скорости появляются регрессии. В этом уроке разбираем на учебном примере агента StockPilot — систему управления складскими запасами. Вы увидите, как оценочный набор из 12 задач показал в этом примере 62% успеха вместо ожидаемых 83%, почему провалы объяснялись не слабостью модели, а «загрязнённым» контекстом, и как первое исправление — вынос бизнес-логики в навыки (skills) с прогрессивным раскрытием — сократил системный промпт с ~400 строк примерно до 50 (а к финальной версии архитектуры — до 15). Это первая часть разбора: выбор инструментов и субагентов ждёт вас в следующем уроке.
Этим уроком открывается модуль об архитектуре агента. Первые пять уроков были про промпт и рабочую среду, теперь масштаб больше — устройство агента целиком. Мы разберём на учебном примере, что делать, когда агент вырос и начал ломаться под собственным весом. По ходу урока пригодится материал первого урока про оценочные наборы: именно evals превращают жалобу «агент стал работать хуже» в конкретный список проблем с причинами.
Знакомый сценарий: агент растёт, качество падает
Представьте: вы построили и выпустили агента под конкретную задачу, и он работал хорошо. Настолько хорошо, что через несколько недель вас попросили добавить ему ещё одну возможность. Потом пришли новые бизнес-требования — добавили ещё. Так повторялось раз за разом, и в какой-то момент системный промпт разросся до нескольких сотен строк, у агента появились десятки инструментов и субагентов, а из-за этой сложности начались регрессии — сбои в тех областях, где агент раньше ускорял работу.
Это частый сценарий: агенты растут постепенно и в какой-то момент начинают мешать сами себе. Задача урока — навести в таком агенте порядок, каждый раз выбирая правильный строительный блок: когда нужен инструмент, когда навык (skill), а когда субагент.
Агент StockPilot: что он умеет и как устроен
Учебный агент называется StockPilot. Это агент управления складскими запасами, который средний по размеру ритейлер разработал для себя. Он умеет пять вещей: помечает позиции с низким остатком, прогнозирует спрос, выбирает поставщиков, оформляет заказы на закупку и пишет еженедельные отчёты для сотрудников. Ни одна из этих возможностей не сложна — проблема в том, что их добавляли одну за другой без пересмотра архитектуры.
Архитектура «до» выглядит так: один оркестратор, системный промпт около 400 строк и 12 инструментов, причём три из них — обёртки вокруг субагентов с полностью изолированными окнами контекста. Понадобилось прогнозирование — завели субагента-прогнозиста. Появлялась новая процедура — её тоже выносили в отдельного субагента. Каждое требование решали новым слоем поверх старых, и оценки постепенно проседали.
Оценочный набор: 12 задач и пять типов оценщиков
У StockPilot 12 задач-оценок и пять типов оценщиков. Задачи делятся на две группы по идентификаторам. Задачи на букву R — регрессионные: реалистичные одноходовые задания, где агент получает запрос, вызывает инструменты и возвращает ответ, который и оценивается. Задачи на букву F — сложные многоходовые сценарии, проверяющие известные точки отказа.
Оценщики тоже двух видов. Детерминированные измеряют то, что считается однозначно: число ходов, задержку и расход токенов на задачу. Недетерминированный оценщик — языковая модель в роли судьи — оценивает то, что числом не выразить: стиль, тон и качество вывода.
Три показательных провала
Задача F1 моделирует ежедневный проход по складу с поиском позиций с низким остатком. Агент приходит к правильному результату, но идёт к нему извилистым путём: вместо прямой линии из точки А в точку Б делает много лишних шагов. Итог верный, оценка провалена — агент не дотягивает до нужной эффективности.
Задача F2 проверяет оформление заказа по акционному пакету. Здесь работает субагент, и сам он выполняет задачу правильно, но при передаче данных между субагентом и оркестратором происходит сбой. Это одна из самых частых точек отказа в системах с большим числом субагентов.
Задача R8 — прогноз спроса в месяц с акцией. Агент вытаскивает правильные исходные данные: базовый прогноз 12 единиц в день и акционный множитель 3.1. Но в самом расчёте вместо 3.1 использует множитель 1.35. Причина в том, что две политики лежат в разных частях 400-строчного промпта и противоречат друг другу. Это не слабость модели, а «загрязнённый» контекст: модель запуталась в информации, которой её окружили.
62% вместо 83%: восхождение по метрикам
По задумке агент должен проходить оценки примерно на 83%. Звучит неплохо, но для рабочей системы 17% отказов — дорогой показатель. В этом примере прогон дал ещё меньше: 62%, то есть 7 задач из 12.
Метод работы с этим называется hill climbing — «восхождение по метрикам»: прогнать оценки и зафиксировать базовый уровень, разобрать причины провалов, переработать архитектуру, снова прогнать оценки — и повторять, пока доля успешных задач растёт. Разбор причин удобно вести в Claude Code. Темы провалов оказались связаны между собой: модель берёт на себя работу, для которой у неё нет инструментов; структура вывода субагентов не совпадает с ожидаемой; политики в длинном промпте противоречат друг другу.
Исправление первое: навыки и прогрессивное раскрытие
Первое исправление касается системного промпта. Навык (skill) — это упакованная, пригодная к сочетанию с другими информация, которую Claude сам подтягивает в контекст, когда понимает, что она нужна для текущей задачи. Правило разделения простое: в системном промпте остаётся только то, что должно быть у модели в голове всегда, независимо от задачи. Всё, что нужно лишь часть времени, — политики, процедуры, пошаговые инструкции по отдельным операциям — уходит в навыки.
Для StockPilot это означало вынести всю бизнес-логику управления запасами в навыки. Когда пользователь просит прогноз, агент сам подтягивает навык прогнозирования; пока не просит — эта информация не занимает контекст. Такой подход называется прогрессивным раскрытием: сведения раскрываются по мере надобности, а не лежат в окне контекста постоянно. Системный промпт сократился примерно с 400 строк до 50, а к финальной версии архитектуры — до 15.
Claude Managed Agents: платформа вместо самодельной инфраструктуры
Параллельно с работой над промптом агента переносят с самодельной инфраструктуры на Claude Managed Agents (CMA) — управляемую платформу агентов Anthropic, сейчас в бете, доступ по запросу. Исходный агент написан напрямую на Messages API: собственный агентный цикл и весь служебный код вокруг него. Локально такой агент собирается быстро, но как только его нужно разместить удалённо и открыть доступ сотням пользователей, встают вопросы масштабирования, хранения состояния сессий, памяти и безопасности.
CMA снимает эти заботы: платформа разделяет самого агента, детали сессии и песочницу, в которой выполняются вызовы инструментов, и берёт на себя хостинг и масштабирование. Разработчику остаётся то, ради чего всё и затевалось, — архитектурные решения: инструменты, навыки, субагенты.
Архитектура «после» и что дальше
Что получается после переработки: короткий системный промпт, простые инструменты и бизнес-логика в навыках. Полную итоговую архитектуру с цифрами разберём в следующем уроке.
Но короткий промпт — только первое из исправлений. Как агент пришёл к трём инструментам, почему большинство собственных инструментов заменили базовыми примитивами, в каком порядке выбирать между своими инструментами и MCP и каких субагентов стоит оставлять — этому посвящён следующий урок.