Архитектура ИИ-агента - это способ собрать LLM, данные, инструменты и правила в систему, которая не просто отвечает текстом, а выполняет задачу. Хороший агент умеет понять запрос, взять нужный контекст, выбрать действие, вызвать инструмент, проверить результат и остановиться там, где нужен человек.
В простом виде агент похож на сотрудника с инструкцией, рабочим столом и набором доступов. У него есть цель, память, документы, инструменты, ограничения, журнал действий и руководитель, который проверяет важные решения.
Коротко: надежный ИИ-агент состоит из LLM, системных инструкций, контекста, памяти, RAG, инструментов, оркестрации, guardrails, логов, оценки качества и human-in-the-loop. Если убрать хотя бы контроль действий и логи, агент может выглядеть умно в демо, но быть опасным в реальной работе.
Базовая схема
Самая понятная схема агента выглядит так:
- пользователь или система ставит задачу;
- слой входной обработки проверяет запрос и права;
- агент получает инструкции и контекст;
- RAG ищет нужные знания;
- LLM решает, что делать дальше;
- planner строит шаг или план;
- executor вызывает инструменты;
- memory сохраняет состояние;
- guardrails проверяют действия и ответы;
- observability записывает логи, стоимость и ошибки;
- человек подтверждает рискованные действия;
- агент возвращает результат или передает задачу дальше.
В маленьком проекте часть этих модулей может быть очень простой. Например, памятью будет история чата, а guardrails - список запрещенных действий. Но сама логика все равно нужна. Без нее агент превращается в чат с доступом к кнопкам.
LLM как ядро, но не вся система
LLM - это мозг агента, но не весь агент. Модель понимает текст, рассуждает, выбирает действия, генерирует ответ и может решать, какой инструмент вызвать. Но сама по себе модель не знает ваши правила, не имеет постоянной памяти, не видит базу данных и не умеет безопасно выполнять операции.
Поэтому вокруг модели строят архитектуру:
- системные инструкции задают роль и правила;
- контекст дает факты для текущей задачи;
- инструменты дают возможность действовать;
- память хранит важное состояние;
- guardrails ограничивают опасное поведение;
- evals проверяют качество;
- логи помогают понять, что произошло.
Если агент ошибся, виновата не только модель. Часто ошибка возникает из-за плохого контекста, слишком широких инструментов, отсутствия проверки или неясной постановки задачи.
Инструкции и системный промпт
Системный промпт - это конституция агента. Он объясняет, кто агент, что он должен делать, чего не должен делать, как обращаться с данными и когда останавливать действие.
В хороший системный промпт входят:
- роль агента;
- цель;
- границы ответственности;
- формат ответа;
- правила работы с источниками и данными;
- запрет на опасные действия;
- условия передачи человеку;
- правила вызова инструментов;
- тон общения;
- критерии завершения задачи.
Плохой системный промпт звучит как “ты полезный ассистент, делай все хорошо”. Хороший промпт похож на рабочую инструкцию: что делать, как проверять, когда не действовать и кому передать задачу.
Контекст
Контекст - это то, что агент знает прямо сейчас. В него входят запрос пользователя, история диалога, выбранные документы, данные из CRM, результаты поиска, ответы инструментов и временное состояние задачи.
Контекст нельзя бесконечно расширять. У моделей есть context window, стоимость запросов и ограничение внимания. Если положить в контекст слишком много мусора, агент начнет хуже видеть главное.
Поэтому важны три правила:
- давать агенту только релевантные данные;
- отделять факты от инструкций;
- регулярно чистить или сжимать историю.
Контекстная инженерия часто важнее красивого промпта. Агент с хорошим контекстом и простыми инструкциями обычно надежнее, чем агент с длинным промптом и случайной пачкой документов.
Память
Память нужна, чтобы агент не начинал с нуля на каждом шаге. Но память бывает разной.
- Краткосрочная память: что произошло в текущем диалоге или workflow.
- Долгосрочная память: устойчивые факты о пользователе, проекте, компании или задаче.
- Рабочее состояние: текущий шаг, выбранный план, результаты инструментов.
- Эпизодическая память: прошлые задачи и решения.
- Семантическая память: знания, найденные через embeddings и RAG.
Не все нужно помнить. Чем больше память, тем выше риск сохранить ошибку, устаревший факт или приватные данные. Поэтому память должна быть управляемой: что сохраняем, на сколько, кто может видеть, как удалить и как проверить.
Для бизнес-агента память особенно чувствительна. Нельзя случайно сохранить персональные данные, коммерческую тайну или временный вывод инструмента как постоянный факт.
RAG и база знаний
RAG нужен, когда агент должен опираться на внешние знания: документы, инструкции, базы, статьи, регламенты, карточки клиентов, техническую документацию.
Обычно RAG работает так:
- документ режется на фрагменты;
- фрагменты превращаются в embeddings;
- embeddings сохраняются в векторную базу;
- по запросу находится похожий контент;
- найденные фрагменты добавляются в контекст;
- модель отвечает с учетом этих данных.
Главная ошибка - думать, что RAG автоматически делает ответы правильными. На практике важны качество документов, chunking, фильтры, метаданные, свежесть индекса, права доступа и проверка найденных фрагментов.
Для агента RAG - это не украшение, а способ привязать рассуждение к реальности. Без RAG агент часто отвечает уверенно, но по памяти модели, а не по вашим данным.
Инструменты и tool calling
Инструменты превращают агента из советчика в исполнителя. Это могут быть API, поиск, CRM, календарь, почта, таблицы, база данных, файловая система, браузер, терминал, платежная система или внутренний сервис.
У каждого инструмента должны быть:
- понятное имя;
- описание, когда его использовать;
- схема входных параметров;
- ограничения;
- проверка прав;
- обработка ошибок;
- логирование вызова;
- безопасный режим для опасных действий.
Самая опасная архитектура - дать агенту широкий инструмент вроде “выполни любой SQL” или “запусти любую shell-команду”. Гораздо лучше делать маленькие безопасные инструменты: “найди клиента по email”, “создай черновик задачи”, “получи статус заказа”, “подготовь письмо без отправки”.
Planner и executor
В простом агенте модель сразу решает, какой инструмент вызвать. В более сложной архитектуре полезно разделять planner и executor.
Planner отвечает за план:
- понять цель;
- разбить задачу на шаги;
- выбрать порядок действий;
- определить, где нужна проверка;
- остановиться, если данных не хватает.
Executor отвечает за выполнение:
- вызвать инструмент;
- обработать результат;
- повторить попытку при безопасной ошибке;
- вернуть результат planner;
- записать логи.
Такое разделение делает систему понятнее. Если агент ошибся, легче понять: он плохо спланировал, выбрал не тот инструмент, получил неверные данные или неправильно обработал результат.
Оркестрация
Оркестрация управляет тем, как агент проходит шаги. Это может быть простой цикл “подумал - вызвал инструмент - получил результат - ответил”, а может быть граф состояний с ветвлениями и проверками.
Оркестрация нужна, когда:
- задача состоит из нескольких шагов;
- есть разные сценарии;
- требуется human-in-the-loop;
- нужно сохранять состояние;
- агент может ждать внешнее событие;
- важно восстановиться после ошибки;
- несколько агентов передают задачу друг другу.
В frameworks вроде LangGraph оркестрация часто строится как stateful workflow. В low-code платформах ее рисуют на канвасе. В своем backend ее можно сделать обычным кодом, очередями и state machine.
Главная идея: агенту не нужно отдавать полную свободу там, где процесс можно описать явно. Чем рискованнее задача, тем больше структуры должно быть вокруг модели.
Router и handoffs
Router выбирает, куда отправить задачу. Например, один запрос идет в RAG, другой в CRM, третий к агенту поддержки, четвертый к агенту по коду, пятый к человеку.
Handoff - это передача задачи другому агенту или человеку с контекстом. Хороший handoff содержит:
- что хотел пользователь;
- что уже сделано;
- какие данные найдены;
- какие инструменты вызывались;
- какие риски есть;
- что нужно сделать дальше.
Без нормального handoff multi-agent система быстро превращается в шум: агенты повторяют работу, теряют контекст и спорят с результатами друг друга.
Guardrails
Guardrails - это правила безопасности и качества. Они могут работать до модели, после модели, перед инструментом или после инструмента.
Примеры guardrails:
- не выполнять платеж без подтверждения;
- не показывать данные чужого клиента;
- не отправлять письмо без preview;
- не удалять файл автоматически;
- не вызывать инструмент, если пользователь не авторизован;
- фильтровать prompt injection;
- проверять формат JSON;
- останавливать ответ с медицинским или юридическим риском;
- требовать ссылку на документ для ответа по базе знаний.
Guardrails не должны быть только текстом в промпте. Для важных действий они должны быть кодом, правами доступа, проверками и audit log.
Human-in-the-loop
Human-in-the-loop нужен там, где ошибка дорогая. Человек не обязан проверять каждый ответ агента, но должен быть в ключевых точках.
Подтверждение человека нужно для:
- отправки писем клиентам;
- изменения CRM;
- финансовых операций;
- удаления данных;
- публикации контента;
- доступа к приватным документам;
- изменения кода в production;
- юридически значимых решений;
- спорных или неуверенных ответов.
Хорошая архитектура не спрашивает человека постоянно. Она спрашивает там, где риск превышает допустимый уровень.
Observability и логи
Если агент сделал странный вывод, нужно видеть путь. Без логов вы не поймете, что произошло: плохой prompt, неправильный retrieval, не тот инструмент, ошибка API или галлюцинация модели.
Нужно логировать:
- входной запрос;
- выбранный контекст;
- найденные документы;
- вызовы инструментов;
- параметры инструментов;
- ошибки;
- стоимость;
- время выполнения;
- финальный ответ;
- решение человека;
- версию промпта и модели.
Для продакшена также нужны traces: цепочка событий одного запуска. Тогда можно открыть конкретный run и увидеть весь путь агента.
Evals
Evals - это проверки качества агента. Без них улучшения будут на уровне ощущения: “вроде стало лучше”. Для агента этого мало.
Оценивать можно:
- точность ответа;
- groundedness: опирается ли ответ на документы;
- правильность выбора инструмента;
- успешность выполнения задачи;
- количество лишних шагов;
- стоимость;
- скорость;
- частоту handoff человеку;
- количество ошибок после релиза;
- удовлетворенность пользователей.
Лучше начинать с маленького набора тестовых сценариев. Например, 30 типовых запросов и 10 рискованных. После каждого изменения промпта, модели или RAG прогонять их снова.
Безопасность доступа
Агент должен иметь минимальные права. Если ему нужно читать статусы заказов, не давайте ему право удалять заказы. Если он должен готовить черновики писем, не давайте автоматическую отправку без подтверждения.
Практичные правила:
- отдельный сервисный аккаунт;
- минимальные scopes;
- read-only доступ по умолчанию;
- отдельные инструменты для опасных действий;
- подтверждение перед записью;
- маскирование секретов;
- аудит всех действий;
- лимиты стоимости и частоты;
- sandbox для кода и файлов;
- запрет на прямой доступ к ключам.
Для внутреннего агента безопасность важна не меньше, чем для публичного. Иногда внутренний агент видит больше чувствительных данных, чем пользовательский чат на сайте.
Архитектура простого агента
Для первого рабочего агента не нужна сложная multi-agent система. Достаточно такой архитектуры:
- frontend или чат;
- backend endpoint;
- системный промпт;
- RAG по базе знаний;
- 2-5 безопасных инструментов;
- журнал запусков;
- human approval для действий записи;
- набор evals;
- мониторинг ошибок.
Например, агент поддержки может искать ответ в базе знаний, подготовить ответ оператору, показать источники, создать черновик тикета и попросить человека подтвердить отправку. Это уже полезно, но еще управляемо.
Архитектура сложного агента
Сложный агент добавляет больше контуров:
- router для классификации запросов;
- несколько специализированных агентов;
- shared memory;
- state machine или graph workflow;
- очереди для долгих задач;
- retry policy;
- sandbox;
- policy engine;
- tracing;
- eval pipeline;
- A/B тесты промптов;
- управление версиями инструментов;
- отдельный контур безопасности.
Такой уровень нужен не сразу. Он оправдан, когда агент выполняет дорогие задачи, работает с большим числом пользователей или становится частью продукта.
Где чаще всего ломается агент
Типичные проблемы повторяются почти в каждом проекте.
- Неясная цель агента.
- Слишком широкие инструменты.
- Нет прав доступа.
- RAG возвращает нерелевантные документы.
- Память хранит мусор.
- Нет логов.
- Нет тестовых сценариев.
- Агент делает действие без подтверждения.
- Промпт пытается заменить архитектуру.
- Все построено как один огромный workflow.
- Нет владельца, который поддерживает агента после запуска.
Почти все эти проблемы решаются не “более умной моделью”, а нормальной инженерной дисциплиной.
Минимальный чек-лист
Перед запуском агента проверьте:
- какая у агента одна главная задача;
- какие данные он видит;
- какие инструменты доступны;
- какие действия запрещены;
- где нужен человек;
- что пишется в логи;
- как откатить ошибку;
- какие тесты прогоняются перед релизом;
- кто отвечает за обновления;
- что делать, если модель не уверена.
Если на эти вопросы нет ответов, агент пока не готов к реальным пользователям.
Итог
Архитектура ИИ-агента - это не про модное слово “автономность”. Это про управляемость. Агент должен понимать задачу, получать правильный контекст, использовать ограниченные инструменты, помнить важное, проходить проверки, логировать действия и вовремя звать человека.
Для первого проекта достаточно простой схемы: LLM, RAG, несколько безопасных tools, логи, evals и подтверждение рискованных действий. Для сложных проектов добавляют orchestration, router, handoffs, multi-agent систему, sandbox и enterprise governance.
Чем больше агент может сделать, тем важнее архитектура вокруг него. Умная модель без ограничений - это риск. Умная модель в понятном процессе - уже рабочий инструмент.
Частые вопросы
Коротко: о чем эта статья?
Разбираем архитектуру ИИ-агента простым языком: модель и контекст плюс инструменты память RAG планировщик оркестрация guardrails логи evals и human-in-the-loop.
Кому полезен этот материал?
Материал полезен тем, кто разбирается в теме "Архитектура AI-агентов" и хочет перейти от терминов к практическим решениям.
С чего начать на практике?
Начните с одной конкретной задачи, опишите ожидаемый результат, проверьте ограничения и только после теста расширяйте решение.
Нужно ли сразу внедрять это в работу?
Нет. Сначала проверьте идею на небольшом примере, оцените качество ответа, риски и пользу для процесса.
