Практический playbook по внедрению мультиагентных систем
Мультиагентные системы легко рисовать и неожиданно сложно эксплуатировать. Исследователь, проверяющий, планировщик и исполнитель на диаграмме выглядят как аккуратная модульная архитектура. В production эти прямоугольники превращаются в независимо падающие компоненты, которые передают друг другу неидеальные данные, конкурируют за состояние, повторяют внешние действия и иногда не согласны даже с тем, что уже произошло.
Поэтому внедрение мультиагентности не стоит начинать с персонажей и промптов. Начинать нужно с самого процесса, изменяемого им состояния и сбоев, которые он обязан переживать.
Этот playbook описывает практическую последовательность проектирования настоящих автоматизаций: систем, которые читают контекст, готовят решения, взаимодействуют с внешними инструментами и после первой ошибки не превращаются в распределённый детектив.
1. Сначала докажи, что тебе вообще нужны несколько агентов
По умолчанию используй одного агента с ограниченным набором инструментов и детерминированным workflow вокруг него.
Отдельный агент оправдан, если у этапа появляется хотя бы одна настоящая граница:
• ему нужен отдельный большой или специализированный контекст;
• ему требуются другие данные или права;
• его можно запускать независимо или параллельно;
• его результат необходимо независимо проверить;
• ему нужна другая модель, промпт, latency budget или набор инструментов;
• его можно повторять, отключать или заменять без перезапуска всего процесса;
• его результат образует естественный проверяемый контракт для следующего этапа.
Не создавай нового агента только потому, что роли «исследователь», «критик» и «редактор» звучат как серьёзная команда. Если различие существует лишь в системном промпте, а контекст, инструменты, права и failure domain остаются общими, это могут быть режимы одного агента, а не три отдельных компонента.
Полезный тест — заменяемость. Если компонент нельзя независимо запустить, оценить и заменить, скорее всего это просто шаг.
2. Опиши workflow до проектирования агентов
Перед архитектурой заполни карточку процесса:
Название: Цель: Триггер: Входные данные: Финальный результат: Кто использует результат: Допустимое время выполнения: Допустимая стоимость: Внешние изменения: Обязательные подтверждения: Что считается успехом: Что считается частичным успехом: Что считается провалом:
Например, workflow подготовки еженедельного материала может собрать заметки, проверить источники, создать черновик и остановиться перед публикацией. Создание черновика — внутреннее и обратимое действие. Публикация — внешний побочный эффект, который должен находиться за approval gate.
Если карточку невозможно заполнить без фразы «агент сам решит», границы процесса пока не определены. Автономность должна работать внутри ясных правил, а не заменять отсутствующие продуктовые решения.
3. Явно выбери модель координации
Для сложных процессов и нормального аудита безопасным default обычно будет оркестрация.
Триггер → Orchestrator → Сбор контекста → Независимая работа агентов → Валидация контрактов → Синтез → Человеческое подтверждение → Применение
Orchestrator отвечает за порядок, состояние, параллельность, таймауты, retry policy, валидацию и остановку. Агенты получают вход, выполняют ограниченную работу и возвращают результат. Они не вызывают друг друга и не импровизируют глобальный workflow.
Choreography подходит процессам, которые действительно построены вокруг независимых событий. Завершённый импорт может отдельно запустить индексирование, аналитику и уведомление. Если уведомление упало, это не должно отменять сам импорт.
Не используй чистую choreography, если порядок меняет результат, несколько агентов участвуют в одном решении, присутствуют внешние действия, требуется полный audit trail или отсутствуют правила для повторных и пришедших не по порядку событий.
На практике часто лучше гибрид: критический путь контролирует orchestrator, а вторичные процессы запускаются событиями.
4. Проектируй агентов по ответственности, а не по персонажам
У каждого агента должна быть одна понятная зона ответственности и операционная карточка:
Имя: Назначение: Входной контракт: Выходной контракт: Разрешённые инструменты: Разрешённые данные: Разрешённые изменения: Timeout: Лимит стоимости: Условия отказа: Безопасность повтора: Fallback: Компенсирующее действие:
Исследовательский агент, например, может читать интернет и предоставленные документы, но ему не нужен доступ к публикации, отправке сообщений или изменению задач. В его output входят выводы, первичные источники, даты сбора, уровень уверенности и неразрешённые противоречия. Если важное утверждение подтвердить не удалось, агент возвращает явный отказ, а не красивую догадку.
Права должны соответствовать минимально необходимой ответственности. Компонент, предлагающий изменение, желательно отделять от детерминированного компонента, который его применяет.
5. Не заставляй модель выполнять работу обычного кода
LLM полезны для неструктурированного текста, неоднозначной классификации, суммаризации, синтеза и подготовки черновиков. Обычный код лучше справляется с проверкой схем, фильтрацией дат, дедупликацией, расчётами, разрешениями, переходами состояния, лимитами, повторами и точными внешними действиями.
Orchestrator желательно делать детерминированным. Модель может рекомендовать ветку, но решение о пересечении границы прав или изменении внешнего состояния должен принимать код либо человек.
Это повышает надёжность и резко упрощает тестирование. Нет смысла спрашивать LLM, валиден ли JSON, когда парсер отвечает на этот вопрос идеально.
6. Считай каждый handoff контрактом
Агенты не должны передавать друг другу произвольный текст со словами «вроде всё готово». Для каждой передачи нужна версионированная схема.
{
"schema_version": "1.0",
"run_id": "weekly-2026-W34",
"producer": "research_agent",
"created_at": "2026-08-20T12:00:00Z",
"input_state_version": 3,
"status": "complete",
"findings": [],
"sources": [],
"confidence": 0.84,
"warnings": []
}Минимально сохраняй версию схемы, идентификатор запуска, производителя, timestamp, версию входного состояния, статус, confidence, warnings и использованные доказательства.
Объект валидируется до передачи следующему агенту. Отсутствующий источник, несовместимая схема или недостаточная уверенность должны остановить процесс либо выбрать заранее описанный fallback прямо на границе. Не нужно позволять ещё трём агентам строить красивый отчёт поверх сломанного состояния.
Не меняй значение существующего поля молча. Добавление необязательного поля обычно совместимо. Превращение confidence из «уверенности агента» в «процент подтверждённых утверждений» требует новой версии схемы.
7. Храни состояние workflow вне контекста модели
Контекстное окно — не база данных. Для каждого запуска нужен долговечный record с версией workflow, триггером, текущим шагом, входным snapshot, версиями состояния, попытками, статусом подтверждения, внешними действиями, финальным результатом и причиной отказа.
Предпочитай append-only transitions или immutable snapshots:
state_v0 → контекст собран state_v1 → источники классифицированы state_v2 → исследование завершено state_v3 → черновик создан state_v4 → человек подтвердил state_v5 → внешнее действие применено
Исправление создаёт новую версию, а не переписывает историю. Для каждого snapshot сохраняй агента-производителя, входную версию, модель, версию промпта, инструменты, timestamp и результат валидации.
Так появляются lineage, replay и auditability. Если финальный результат оказался плохим, можно открыть конкретный переход, который внёс ошибку, а не восстанавливать процесс по разрозненным логам.
8. Определи семантику повторов до первого сбоя
Для каждого шага заранее ответь: что произойдёт, если он выполнится дважды?
Read-only анализ обычно можно повторить безопасно. Внешние действия — нельзя. Создание задачи, отправка письма, платёж или публикация должны использовать idempotency_key:
workflow + run_id + action_type + target
Перед применением действия система проверяет, не завершался ли этот ключ успешно раньше.
Автоматический retry допустим только для временных технических ошибок: timeout, сетевого сбоя, известной кратковременной недоступности и rate limit с определённой задержкой. Не повторяй автоматически ошибки валидации, отсутствие прав, отказ пользователя, несовместимые контракты и операции с неоднозначным результатом.
Timeout не доказывает, что внешний эффект не произошёл. Сначала проверь целевую систему и только затем решай, безопасен ли новый запрос.
9. Назначь каждому сбою явный результат
У каждого шага должно быть одно заранее выбранное поведение:
• Fail closed: остановить workflow. Подходит для прав, безопасности, финансовых решений и публикации.
• Degraded mode: продолжить с явно ограниченным результатом.
• Cached fallback: использовать последний допустимый результат с ограничением по свежести.
• Human escalation: создать review artifact с объяснением проблемы и доступными действиями.
• Skip: пропустить некритический шаг и показать это в финальном результате.
Молчаливого fallback быть не должно. Пользователь обязан отличать полноценный результат от созданного в degraded mode.
Circuit breaker полезен вокруг нестабильных удалённых зависимостей. После нескольких временных ошибок система прекращает вызовы, ждёт cooldown и пропускает один контролируемый тестовый запрос. Пороги зависят от частоты workflow: три ошибки означают разные вещи для сервиса с тысячей запросов в минуту и для еженедельной автоматизации.
10. Запланируй компенсацию внешних действий
Каждое действие классифицируй как обратимое, компенсируемое или необратимое.
Создание локального черновика обратимо. Изменение задачи можно компенсировать восстановлением предыдущей версии. Публикация компенсируется лишь частично: материал уже могли скопировать. Отправка письма необратима; максимум можно отправить исправление.
Если поздний шаг упал, компенсация выполняется в обратном порядке завершённых действий, но только там, где она безопасна и осмысленна. Если точный rollback невозможен, зафиксируй инцидент и передай его человеку вместо того, чтобы называть «примерно вернули как было» чистым состоянием.
11. Сделай человеческое подтверждение настоящим состоянием
Human review — не диалог подтверждения, прикрученный в конце. Это часть state machine:
draft_ready → awaiting_review → approved / rejected / edited / expired → apply
Review artifact должен объяснять, что изменится, почему, какие данные и агенты участвовали, что было пропущено, какие есть warnings, как выглядит точный preview или diff и какие действия доступны пользователю.
Подтверждение относится к конкретной версии. Если после него изменился черновик, target или параметры, старое approval перестаёт действовать.
Разумный default: автоматически разрешать чтение, анализ и создание черновика, но требовать явного подтверждения для внешних изменений, сообщений, публикации, удаления, чувствительных данных и платных API.
12. Сделай наблюдаемым весь запуск
Один run_id должен проходить через orchestrator, агентов и инструменты. Для каждого шага сохраняй агента, номер попытки, latency, модель, версию промпта, входную и выходную версии состояния, tool calls, результат валидации, токены, примерную стоимость, тип ошибки и fallback.
Не складывай чувствительный input в обычные логи. При необходимости сохраняй редактированную версию, hash или ссылку на защищённый artifact.
Полезные метрики всего workflow: успешные и частично успешные запуски, ручные вмешательства, ошибки каждого этапа, общая и поагентная latency, количество повторов, стоимость, токены, частота fallback, отклонённые approvals, остановленные дубли и доля результата, которую переписал человек.
Последняя метрика особенно важна. Если пользователь переписывает 80 процентов работы агента, агент не экономит время только потому, что технически завершился успешно.
Детерминированные unit-тесты должны проверять контракты, переходы состояния, idempotency, retry policy, circuit breakers, права, approval gates, компенсацию и редактирование чувствительных данных.
Контрактные тесты передают каждому агенту нормальный, пустой, неполный, противоречивый, слишком большой, устаревший, вредоносный и несовместимый по схеме input. В автоматических тестах модельные вызовы мокай: тестовый набор не должен случайно создавать счета и внешние побочные эффекты.
Evals могут проверять свойства, а не один точный ответ: утверждения подтверждены источниками, сомнения не скрыты, опасные действия не выполняются, структура и стиль соблюдены, агент не вышел за разрешённые данные.
Наконец, искусственно ломай workflow. Проверь timeout, повторную доставку, рестарт orchestrator, повреждённый snapshot, несовместимую схему, отказ пользователя и падение сразу после внешнего действия. Если процесс нельзя безопасно продолжить после исчезновения orchestrator, он не готов.
14. Увеличивай автономность поэтапно
ручной прототип → shadow mode → draft mode → reversible apply → controlled automation
В ручном прототипе сохраняются inputs и outputs, но внешних действий нет. В shadow mode workflow запускается автоматически и сравнивается с существующим ручным процессом. Draft mode создаёт review artifact. Reversible apply допускает низкорисковые действия с idempotency, audit и компенсацией. Controlled automation оставляется для хорошо изученных операций небольшого риска; необратимые и чувствительные действия остаются за approval.
Не повышай автономность только потому, что система пережила одну спокойную неделю. Нужны репрезентативные запуски и специально проверенные сценарии отказа.
15. Установи production-readiness gate
Workflow готов к регулярному использованию, когда у каждого агента есть понятная причина существовать, все handoff валидируются машиной, состояние переживает рестарт, повторный запуск не создаёт дубли, для каждой зависимости определено поведение при отказе, внешние действия защищены approval, версии моделей и промптов сохраняются, чувствительные данные не попадают в обычные логи, частичные сбои проверены, неудачный запуск можно воспроизвести, а стоимость и latency укладываются в заданные бюджеты.
Продуктовая метрика не менее важна: пользователь должен принимать большую часть результатов без существенной переделки. Технически успешный workflow, создающий больше работы на проверку, чем убирающий, всё равно является провалом.
16. Удаляй агентов так же охотно, как добавляешь
Периодически и после крупных изменений моделей проверяй, какие агенты часто падают, какие результаты постоянно переписываются, какие дорогие этапы почти не влияют на итог, где постоянно срабатывает fallback, какие данные собираются без применения и какую LLM-работу можно заменить обычным кодом.
Мультиагентная система не обязана развиваться только добавлением новых ролей. Удаление агента часто сильнее улучшает надёжность, стоимость, latency и понятность всей архитектуры.
Практический default намеренно скучный: детерминированный trigger, детерминированный orchestrator, минимальный контекст, несколько read-only специалистов, валидация контрактов, один этап синтеза, review artifact, явное подтверждение, отдельный apply-компонент и audit record.
Это выглядит менее магически, чем рой автономных агентов. Зато с гораздо большей вероятностью продолжит работать после окончания демо.