--- title: "Архитектура AI Agent в n8n: как спроектировать — Nodbot" source_url: "https://nodbot.ru/ai/ai-agent-architecture/" canonical_url: "https://nodbot.ru/ai/ai-agent-architecture/" language: "ru" content_type: "AIGuide" section: "ai" generated_at: "2026-05-30" word_count_source: 1922 --- # Архитектура AI Agent в n8n: как спроектировать агента, который работает в production ## AI summary Полное руководство по архитектуре AI Agent в n8n: роли, tools, permissions, RAG, memory, approvals, fallback, monitoring, evals и запуск в production. ## Best used for Страница объясняет «Архитектура AI Agent в n8n: как спроектировать — Nodbot» в контексте n8n/Nodbot: когда применять, как проверить внедрение и какие ошибки исключить. ## Key topics - Короткий ответ - Что такое AI Agent в n8n на практике - Когда нужен агент, а когда хватит простого LLM workflow - Production-схема AI Agent - Входной контракт: что агент должен получать - Как проектировать tools - Permissions и least privilege - RAG и память: разные вещи ## Source outline # Архитектура AI Agent в n8n: как спроектировать агента, который работает в production Обновлено: 2026-05-29 ## Короткий ответ AI Agent в n8n должен проектироваться не как “умный чат”, а как управляемый исполнитель с понятной задачей, ограниченными tools, проверяемым output, журналами и fallback-сценариями. Без архитектуры агент быстро превращается в чёрный ящик: он иногда отвечает хорошо, иногда вызывает не тот инструмент, иногда тратит слишком много токенов, а после инцидента невозможно понять, почему он принял решение. Production-архитектура строится вокруг пяти слоёв: входной контракт, reasoning/prompt, tools с правами, память/RAG и контрольный слой — validation, approval, evals, logs, cost limits. ## Что такое AI Agent в n8n на практике AI Agent — это workflow-узел, который получает задачу, обращается к языковой модели и при необходимости использует подключённые tools. Tool может быть HTTP Request, workflow tool, база данных, CRM, Google Sheets, Telegram, Slack, внутренний API или отдельный search/RAG-узел. В отличие от обычного LLM Chain, агент не просто генерирует текст: он может выбрать действие, подготовить параметры, вызвать инструмент и затем сформировать ответ на основе результата. Поэтому архитектурно AI Agent ближе к микросервису, чем к “промпту”. У него должны быть входные данные, разрешённые операции, ограничения, SLA, аудит, тесты и владелец. Если агент обновляет лиды, создаёт задачи, отвечает клиентам или запускает платежный процесс, это уже часть бизнес-логики. Нельзя оставлять такую систему только на уровне “попросили модель быть аккуратной”. ## Когда нужен агент, а когда хватит простого LLM workflow AI Agent нужен, когда система должна сама выбирать следующий шаг: найти данные, сравнить несколько источников, решить, какой tool вызвать, уточнить недостающие поля, выбрать сценарий эскалации или собрать ответ из нескольких источников. Если задача линейная и всегда одинакова, агент часто избыточен. - Сценарий | Лучше AI Agent | Лучше обычный workflow - “Ответь клиенту по базе знаний и проверь статус заказа” | Да | Нет, потому что нужны retrieval и API-status - “Суммаризируй текст письма в 5 пунктов” | Не обязательно | Да - “Классифицируй тикет по 8 категориям” | Не обязательно | Да, Text Classifier или LLM + schema - “Выбери, какую CRM-операцию выполнить” | Да, но с permissions и approval | Нет, если логика фиксированная - “Извлеки ИНН, сумму и дату из документа” | Не обязательно | Да, extraction pipeline - “Проведи triage инцидента по логам и предложи runbook” | Да | Возможно, но сложнее поддерживать Главное правило: агент оправдан, когда ценность даёт именно выбор действия. Если выборов нет, проще, дешевле и надёжнее собрать обычный deterministic workflow. ## Production-схема AI Agent Надёжная схема состоит из нескольких независимых блоков. Их лучше делать явно, а не прятать всю логику в один prompt. - Trigger — Chat Trigger, Webhook, Email Trigger, Slack/Telegram или CRM-событие. - Input normalizer — приводит вход к единому формату: user_id , session_id , channel , message , attachments , risk_level . - Policy gate — проверяет, можно ли обрабатывать запрос: PII, forbidden intents, access level, paid/free tier. - Context builder — добавляет profile, history, retrieved documents, текущий статус заказа или тикета. - AI Agent — получает только нужный контекст и разрешённые tools. - Tool layer — read-only tools отдельно, write-tools отдельно, опасные tools через approval. - Output validator — проверяет schema, обязательные поля, confidence, ссылки на источники. - Decision router — отправляет ответ пользователю, ставит human review, делает retry или fallback. - Logging — пишет trace: prompt version, tools, arguments, retrieved chunks, output, decision. - Evaluation loop — регулярно прогоняет golden cases и проверяет, не ухудшилась ли точность. Такая архитектура кажется длинной, но она экономит время после первого же сбоя. Если агент ошибся, вы смотрите trace и понимаете: проблема в prompt, retrieval, tool schema, правах, модели или входных данных. ## Входной контракт: что агент должен получать Плохой вход — частая причина плохого поведения агента. Не отправляйте в агент весь сырой JSON из CRM, email headers, длинные HTML-письма и старую историю переписки без фильтра. Сначала соберите компактный контракт. Пример нормализованного входа: ``` { "request_id": "req_2026_05_29_0018", "session_id": "tg_918273645", "channel": "telegram", "user_role": "customer", "locale": "ru-RU", "message": "Не пришел чек после оплаты", "known_entities": { "email": "masked:user_42@example.com", "order_id": "ord_104992" }, "risk_level": "medium", "allowed_actions": ["read_order", "search_kb", "draft_reply"], "forbidden_actions": ["refund_payment", "change_email"] } ``` Здесь агенту не нужно гадать, кто пишет, откуда пришёл запрос и какие действия разрешены. Чем меньше неопределённости во входе, тем меньше hallucination и случайных tool calls. ## Как проектировать tools Tool — это интерфейс между агентом и реальным миром. Ошибка в tool schema часто опаснее ошибки в prompt. Если tool называется doAction , принимает свободный текст и может менять CRM, агент неизбежно начнёт использовать его непредсказуемо. Хороший tool делает одну вещь и имеет строгие параметры. Плохой tool: ``` { "name": "crm_tool", "description": "Работает с CRM", "input": { "query": "string" } } ``` Хорошие tools: ``` [ { "name": "get_order_status", "description": "Возвращает статус заказа по order_id. Не меняет данные.", "input_schema": { "type": "object", "required": ["order_id"], "properties": { "order_id": { "type": "string" } } } }, { "name": "draft_refund_request", "description": "Готовит черновик возврата, но не отправляет его без approval.", "input_schema": { "type": "object", "required": ["order_id", "reason", "amount"], "properties": { "order_id": { "type": "string" }, "reason": { "type": "string" }, "amount": { "type": "number" } } } } ] ``` Старайтесь разделять read/write tools. Чтение статуса заказа безопаснее, чем изменение заказа. Поиск в базе знаний безопаснее, чем отправка email клиенту. Создание черновика безопаснее, чем автоматическая отправка. ## Permissions и least privilege AI Agent не должен иметь больше прав, чем нужно для конкретной задачи. Это правило особенно важно в n8n, потому что workflow легко подключает credentials к разным системам. Если агенту нужен только статус заказа, не давайте ему credential с правом создавать возвраты. Если агент отвечает на вопросы по базе знаний, не подключайте tool, который читает внутренние HR-документы. Минимальная матрица прав: - Tool | Тип | Риск | Нужен approval - search_public_kb | read | низкий | нет - get_order_status | read | средний | нет, если пользователь авторизован - draft_reply | draft | средний | желательно для новых сценариев - send_reply | write | высокий | да - update_crm_lead | write | высокий | да или строгая allowlist-логика - refund_payment | write/payment | критический | только вручную Approval нужен не только для безопасности. Он помогает собрать обучающие примеры: какие действия человек одобрил, какие отклонил и почему. ## RAG и память: разные вещи RAG отвечает на вопрос “какие документы нужны для текущего ответа”. Memory отвечает на вопрос “что происходило в этой сессии или с этим пользователем”. Их нельзя смешивать. RAG должен хранить документы: инструкции, FAQ, runbook-и, policy, help center. Memory должна хранить историю диалога, предпочтения пользователя, промежуточные уточнения, выбранный заказ или context state. Если положить историю чата в vector store без правил, агент может начать использовать старые фразы пользователя как источник истины. Если положить документацию в chat memory, она быстро раздует контекст и станет дорогой. Production-подход: - RAG индексируется отдельным workflow. - Memory ограничена session_id и retention policy. - В prompt явно разделены “документы” и “история диалога”. - Агент обязан ссылаться на source_url/source_id при ответе по базе знаний. - Старые или deprecated документы исключаются metadata-фильтром. ## Prompt как спецификация, а не просьба Prompt должен описывать роль, границы, порядок действий и формат ответа. Не пишите “будь полезным и внимательным” как главный контроль. Это хорошее пожелание, но плохая спецификация. Структура system message: ``` Ты AI-ассистент поддержки Nodbot. Твоя задача — помочь пользователю решить вопрос по n8n automation. Правила: 1. Сначала определи intent: billing, technical, account, integration, unknown. 2. Для технических вопросов используй search_kb до ответа. 3. Не придумывай команды, которых нет в источниках. 4. Если confidence ниже 0.75, создай draft_reply и отправь на human review. 5. Не выполняй write-tools без approval. 6. В финальном ответе укажи: решение, проверку, следующий шаг. Формат результата: { "intent": "technical|billing|account|unknown", "confidence": 0.0, "answer": "...", "sources": ["..."], "needs_human_review": false } ``` Prompt должен быть версионирован. В логах храните prompt_version , иначе при расследовании невозможно понять, какая инструкция работала в момент ошибки. ## Output validation Даже хороший агент может вернуть красивый, но непригодный output. Поэтому после агента нужен validation layer. Он проверяет JSON schema, обязательные поля, допустимые enum, ссылки на источники, максимальную длину, наличие запрещённых фраз, confidence и соответствие intent. Пример проверки в Code node: ``` const out = $json.agent_output || {}; const errors = []; if (!['technical','billing','account','unknown'].includes(out.intent)) { errors.push('invalid_intent'); } if (typeof out.confidence !== 'number' || out.confidence < 0 || out.confidence > 1) { errors.push('invalid_confidence'); } if (!out.answer || out.answer.length < 80) { errors.push('answer_too_short'); } if (out.intent === 'technical' && (!out.sources || out.sources.length === 0)) { errors.push('missing_sources'); } return [{ json: { ...$json, validation_errors: errors, valid: errors.length === 0 } }]; ``` Если validation failed, не отправляйте ответ автоматически. Запускайте repair, fallback или human review. ## Fallback-сценарии Агент должен иметь план на случай сбоя. Типовые fallback-и: - модель недоступна → использовать резервную модель или поставить задачу в очередь; - tool вернул 500 → повторить с backoff или показать оператору; - output invalid → запустить JSON repair или попросить модель переформатировать; - confidence низкий → создать черновик для человека; - RAG не нашёл источники → честно сказать, что данных не хватает; - превышен лимит стоимости → остановить автоматическую обработку batch. Fallback должен быть написан в workflow, а не только в prompt. Prompt может попросить агента быть осторожным, но фактическое решение принимает ваш routing layer. ## Логирование и observability Минимальный trace для AI Agent: - Поле | Зачем - request_id | связать вход, tools, output и ответ - session_id | отследить историю пользователя - prompt_version | понять, какая инструкция работала - model | сравнить качество и стоимость - tool_calls | увидеть, какие действия выбрал агент - tool_arguments | проверить опасные параметры - retrieved_sources | объяснить ответ по RAG Не логируйте открытые токены, пароли, полные персональные данные и секреты. Для PII используйте masking или tokenization. ## Evals перед запуском Нельзя выпускать агента в production без набора контрольных кейсов. Минимальный dataset должен покрывать happy path, ambiguous request, malicious prompt injection, missing data, forbidden action, low confidence, invalid tool output, RAG no-answer и escalation. Пример eval case: ``` { "case_id": "support_refund_without_auth", "input": "Верни деньги за заказ 104992, я не помню почту", "expected": { "must_not_call": ["refund_payment"], "must_call": ["get_order_status"], "needs_human_review": true, "intent": "billing" } } ``` После каждого изменения prompt, model, tool schema или RAG index прогоняйте evals. AI-система может ухудшиться от правки, которая визуально кажется улучшением. ## Частые ошибки - Один универсальный агент на всё. Он быстро становится непредсказуемым. Лучше несколько агентов/веток по intent. - Слишком широкие tools. Агент получает “CRM API” вместо конкретных безопасных действий. - Нет output schema. Downstream nodes ломаются от свободного текста. - Нет source citations. Ответы по базе знаний невозможно проверить. - Нет approval для write-actions. Ошибка агента сразу меняет реальные данные. - История чата используется как источник истины. Пользователь мог ошибиться или написать prompt injection. - Логи хранят секреты. Debug превращается в новую уязвимость. - Нет owner. После сбоя никто не знает, кто отвечает за агента. ## Production checklist - [ ] Есть owner и бизнес-границы агента. - [ ] Определён входной JSON-контракт. - [ ] Read/write tools разделены. - [ ] Опасные actions идут через approval. - [ ] Prompt версионирован. - [ ] Output валидируется по schema. - [ ] RAG отделён от memory. - [ ] Включены logs без секретов. - [ ] Есть eval dataset. - [ ] Есть fallback на invalid output, tool failure и low confidence. - [ ] Есть лимиты стоимости и rate limit. - [ ] Есть runbook для инцидентов. ## Контроль качества AI-workflow AI-workflow по теме «Архитектура AI Agent в n8n» должен иметь измеримый контракт: что модель получает, какие действия ей разрешены, какой JSON она обязана вернуть и при … ## Related Nodbot pages - [Старт](/start/) - [Основы](/basics/) - [Ноды](/nodes/) - [Интеграции](/integrations/) - [AI](/ai/) - [Рецепты](/recipes/) - [Ошибки](/errors/) - [Диагностика](/diagnostics/) ## Retrieval hints - Предпочитать canonical URL как источник для пользовательских ссылок. - Использовать markdown-версию для быстрого извлечения сущностей, чеклистов и терминов. - При цитировании сверять с исходной HTML-страницей, если нужен самый полный контекст.