Диагностика AI Agent в n8n: prompts, tools и память ¶

Обновлено: 2026-05-29

Короткий ответ ¶

Если AI Agent в n8n отвечает плохо или не вызывает tools, сначала проверьте не модель, а контракт задачи: входные данные, системную инструкцию, описание tools, схему ответа и ограничения на действия. Агент не должен “угадывать”, когда вызывать инструмент: у каждого tool должно быть понятное назначение, входные параметры и критерий применения. Для стабильного production-сценария отделяйте рассуждение от действия: сначала классификация запроса, потом выбор tool, потом валидация результата и только после этого финальный ответ. Если нужен строгий JSON, используйте структурированный output и проверку схемы, а не просьбу “ответь валидным JSON” в конце prompt.

Быстрая развилка по симптомам ¶

Симптом	Вероятная причина	Что проверить первым
Агент не вызывает tool	плохое описание tool или нет явного условия вызова	tool description и system prompt
Агент вызывает не тот tool	инструменты похожи по смыслу	названия, описания и маршрутизация
JSON невалидный	нет строгой схемы или parser не подключён	Structured Output Parser / schema
Ответ “галлюцинирует”	нет источников или RAG не обязателен	retrieval, цитаты, запрет без источника
Дорого и медленно	слишком большой prompt, память, лишние tools	токены, model, max iterations
Timeout	tool долго отвечает или агент делает циклы	логи tool, retry, лимиты

Шаг 1. Упростите задачу до одного теста ¶

Не начинайте диагностику на реальном чате с десятью tools и длинной историей. Создайте минимальный тестовый execution: один входной запрос, один AI Agent, один tool, один ожидаемый результат.

Пример тестового payload:

{
  "user_message": "Найди заказ 10045 и скажи его статус",
  "expected_tool": "get_order_by_id",
  "expected_answer_contains": "status"
}

Если агент не вызывает один очевидный tool в минимальной схеме, проблема в prompt/tool description. Если минимальный тест работает, а production нет — проблема в маршрутизации, памяти, лишнем контексте или конфликте tools.

Шаг 2. Перепишите описание tools как API-контракт ¶

Слабое описание tool выглядит так: “Search orders”. Хорошее описание объясняет, когда использовать tool, какие параметры нужны и чего tool не делает.

Пример:

Tool: get_order_by_id
Use this tool only when the user provides an exact numeric order ID.
Input: { "order_id": string }
Returns: status, paid_at, delivery_status, customer_email.
Do not use this tool for searching by phone, email or vague order description.

Для похожих tools добавьте отрицательные правила. Если есть search_customer и get_order_by_id, агенту нужно явно понимать разницу. Чем похожее tools, тем выше шанс неправильного вызова.

Шаг 3. Разделите routing и agent logic ¶

В production часто лучше не давать агенту всё сразу. Сначала отдельная нода классифицирует запрос: order_status, refund, faq, human_support, unknown. После этого AI Agent получает только нужные tools.

Преимущества:

меньше токенов;
меньше случайных tool calls;
проще отлаживать;
выше безопасность;
легче строить аналитику по типам обращений.

Если агенту доступны платежи, CRM, email и база знаний одновременно, добавьте human approval для опасных действий: возврат денег, отправка письма клиенту, изменение CRM-статуса, удаление данных.

Шаг 4. Строгий JSON через схему, а не через просьбу ¶

Фраза “верни валидный JSON” не гарантирует валидный JSON. Для интеграций с CRM, Google Sheets, API или Telegram-кнопками нужен структурированный выход.

Опишите схему:

{
  "type": "object",
  "properties": {
    "intent": {"type": "string"},
    "confidence": {"type": "number"},
    "answer": {"type": "string"},
    "needs_human": {"type": "boolean"},
    "used_sources": {"type": "array", "items": {"type": "string"}}
  },
  "required": ["intent", "confidence", "answer", "needs_human"]
}

После AI-ноды добавьте проверку: если JSON невалидный, confidence низкий или нет источников для RAG-ответа, не отправляйте ответ пользователю автоматически. Переведите запрос в human review или fallback.

Шаг 5. Memory не должна загрязнять ответ ¶

Память полезна в чат-боте, но вредна в диагностике и строгих бизнес-процессах. Если пользователь в прошлом спросил про один заказ, агент не должен автоматически подставлять его в следующий запрос без явного подтверждения.

Правила для memory:

хранить только то, что действительно нужно для диалога;
не хранить секреты, токены и полные payload;
ограничивать окно истории;
очищать память при смене темы;
не использовать memory как источник истины для платежей, статусов и юридически значимых данных.

Для статуса заказа источник истины — CRM/API, а не память агента.

Шаг 6. RAG должен быть обязательным для фактических ответов ¶

Если агент отвечает на базе документов, он должен не просто “иметь vector store”, а использовать его при определённых типах вопросов. В prompt добавьте правило: если вопрос требует фактов из базы знаний, сначала вызови retrieval tool; если источников нет — скажи, что данных недостаточно.

Хороший финальный ответ содержит:

короткий ответ;
1–3 факта из источников;
ссылку/название источника;
оговорку, если уверенность низкая;
предложение передать человеку, если вопрос влияет на деньги, доступ или безопасность.

Без такого ограничения агент будет уверенно отвечать из общей модели, даже когда в базе знаний нет нужной информации.

Шаг 7. Стоимость и timeout ¶

AI Agent может стать дорогим из-за длинной истории, большого системного prompt, лишних tools, повторных попыток и больших документов в контексте. В логах фиксируйте: model, tokens, latency, number of tool calls, retries, outcome.

Оптимизация без потери качества:

уменьшить список tools по intent;
вынести правила в короткий system prompt;
резать историю диалога;
использовать RAG с top-k, а не вставлять всю базу знаний;
ограничить max iterations;
кешировать ответы на частые FAQ;
отделить “классификацию” от “генерации ответа”.

Контрольный набор тестов ¶

Сделайте 10 эталонных запросов и храните их рядом с workflow:

[
  {"input":"Где заказ 10045?","expected_intent":"order_status","expected_tool":"get_order_by_id"},
  {"input":"Верни деньги за заказ 10045","expected_intent":"refund","needs_human":true},
  {"input":"Какие документы нужны для подключения?","expected_intent":"faq","requires_rag":true}
]

После изменения prompt, model или tools прогоняйте этот набор. Так вы будете улучшать агента измеримо, а не по ощущению “стал умнее”.

Что не делать ¶

Не подключайте агенту все tools “на всякий случай”. Не разрешайте опасные действия без human review. Не используйте memory как базу данных. Не просите модель вернуть JSON без схемы и проверки. Не доверяйте ответам без источников там, где пользователь спрашивает о правилах, цене, статусе или безопасности.

FAQ ¶

Почему AI Agent не вызывает tool, хотя он подключён?
Часто tool плохо описан или prompt не требует использовать его при конкретном интенте. Сделайте описание tool более явным и добавьте тестовый запрос.

Что лучше: один большой агент или несколько маленьких workflow?
Для production обычно надёжнее несколько узких маршрутов: классификация → нужный tool/agent → проверка результата.

Как заставить агента отвечать валидным JSON?
Используйте структурированную схему и проверку результата. Одна инструкция в prompt не гарантирует валидность.

Почему агент галлюцинирует, хотя подключён RAG?
Он может не вызывать retrieval tool. Добавьте правило обязательного retrieval для фактических вопросов и fallback при отсутствии источников.

Как снизить стоимость AI Agent?
Сократите history, tools и контекст; разделите классификацию и генерацию; ограничьте iterations; кешируйте частые ответы.