Debugging AI Agent в n8n: как разбирать ошибки tools, prompt и RAG ¶

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

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

AI Agent нельзя дебажить как обычный IF node: один и тот же симптом может быть вызван prompt, плохим retrieval, неверной schema, отсутствующим permission, rate limit, ошибкой tool или недетерминированным ответом модели. Начинайте не с переписывания prompt, а с фиксации входа, версии prompt/schema, списка tools, retrieved chunks, tool calls и финального JSON. Если эти данные не логируются, вы не дебажите агента — вы гадаете.

Диагностическая карта ¶

Что логировать до первого инцидента ¶

Минимальный debug payload:

{
  "execution_id": "...",
  "external_id": "ticket_4821",
  "input_hash": "sha256:...",
  "prompt_version": "2026-05-29",
  "schema_version": "reply_draft_v3",
  "model": "provider/model",
  "available_tools": ["search_kb", "create_reply_draft"],
  "retrieved_sources": ["kb_12", "kb_18"],
  "tool_calls": [
    {"tool": "search_kb", "status": "success"},
    {"tool": "create_reply_draft", "status": "validation_failed"}
  ],
  "final_status": "needs_human_review"
}

Не надо логировать секреты и полные персональные данные. Хеши, внутренние ID и короткие excerpts обычно достаточны.

Шаг 1: воспроизведите input ¶

Сохраните фактический input, который получил Agent: не только текст пользователя, но и нормализованные поля, язык, customer_id, retrieved context, system prompt version и tool list. Ошибка часто живёт в transform-node до агента: пустой customer_id, неправильный язык, обрезанный текст, неверный статус заказа.

Проверка:

• trigger payload сохранён;
• expressions не дают undefined;
• дата/часовой пояс корректны;
• нужные fields не потерялись после Set/Edit Fields;
• replay использует тот же input, а не свежие данные из CRM;
• prompt version совпадает с production.

Шаг 2: отделите prompt от tool ¶

Если агент вызвал неправильный tool, сначала проверьте tool name и description. Модель выбирает инструмент не по вашим намерениям, а по доступным описаниям.

Плохие описания:

• CRM tool;
• Use this to work with customer;
• Universal API request.

Хорошие описания:

• find_crm_contact: read-only lookup by email or customer_id;
• create_reply_draft: creates a draft, does not send email;
• update_ticket_priority: changes priority, requires human approval.

Если description расплывчатое, prompt не спасёт.

Шаг 3: проверьте retrieval ¶

Для RAG-сценариев агент может “ошибиться”, потому что получил плохой context. Проверяйте отдельно:

• был ли retrieval вообще;
• сколько chunks вернулось;
• совпадает ли язык;
• не попали ли устаревшие документы;
• есть ли metadata-фильтр по продукту/региону;
• содержит ли top-1 chunk ответ;
• не конфликтуют ли источники.

Если top chunks нерелевантны, менять system prompt бесполезно. Сначала чините ingestion, chunking, embeddings или metadata.

Шаг 4: проверьте schema и validation ¶

Ошибки structured output часто выглядят как “модель тупит”, но причина в контракте:

• слишком много обязательных полей;
• enum не совпадает с реальными категориями;
• поле reason требует длинный текст, но max length мал;
• tool schema просит source IDs, хотя retrieval их не передал;
• JSON example отличается от JSON Schema;
• downstream node ожидает другое имя поля.

Сохраняйте raw output модели отдельно от validated output. Это помогает понять, где сломалось: на генерации, парсинге или business validation.

Шаг 5: права и credentials ¶

Если tool возвращает 401/403, не переписывайте prompt. Проверьте:

• credential выбран правильный;
• service account активен;
• scopes позволяют действие;
• token не истёк;
• provider не требует reauth;
• tool запускается из того же окружения, что production;
• agent не передал ID другого клиента.

Для write-tools добавьте отдельный лог provider response: status, error code, request ID.

Мини-eval для debugging ¶

Соберите 20–50 кейсов:

• 10 обычных;
• 5 edge cases;
• 5 prompt injection;
• 5 пустой/конфликтный context;
• 5 низкий confidence или unknown answer.

Для каждого кейса задайте expected outcome: category, tool, action, source IDs, review flag. После каждой правки prompt/schema прогоняйте набор заново.

FAQ ¶

Что первым менять при плохом ответе: prompt или RAG?
Сначала посмотрите retrieved chunks. Если источники плохие, prompt только маскирует проблему.

Нужно ли хранить raw model output?
Да, но без секретов и лишней PII. Raw output помогает отличить ошибку генерации от ошибки validation.

Как дебажить редкие ошибки?
Сохраняйте input hash, prompt version, model, retrieved sources и tool trace. Тогда редкий кейс можно воспроизвести без полного доступа к production.