---
title: "Debugging AI Agent в n8n: как разбирать ошибки — Nodbot"
source_url: "https://nodbot.ru/ai/ai-agent-debugging/"
canonical_url: "https://nodbot.ru/ai/ai-agent-debugging/"
language: "ru"
content_type: "AIGuide"
section: "ai"
generated_at: "2026-05-30"
word_count_source: 977
---

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

## AI summary

AI-гайд для n8n: Debugging AI Agent в n8n: как разбирать ошибки tools. Архитектура workflow, ограничения, проверки качества, безопасность и cost control.

## Best used for

Страница объясняет «Debugging AI Agent в n8n: как разбирать ошибки — Nodbot» в контексте n8n/Nodbot: когда применять, как проверить внедрение и какие ошибки исключить.

## Key topics

- Короткий ответ
- Диагностическая карта
- Что логировать до первого инцидента
- Шаг 1: воспроизведите input
- Шаг 2: отделите prompt от tool
- Шаг 3: проверьте retrieval
- Шаг 4: проверьте schema и validation
- Шаг 5: права и credentials

## Source outline

# 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. Если эти данные не логируются, вы не дебажите агента — вы гадаете.

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

- Симптом | Возможная причина | Где проверять
- агент выбрал не тот tool | описание tool слишком широкое | tool name/description
- JSON не парсится | schema слишком сложная или prompt конфликтует | Structured output / validation
- ответ без источников | retrieval пустой или source rule слабый | vector store / RAG context
- tool вернул 403 | credential или scopes | credentials / provider API
- агент зациклился | retry без stop condition | workflow loop / retry settings
- много расходов | длинный context, replay, tool loops | cost log
- разные ответы на один input | temperature/model/prompt drift | eval dataset

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

Минимальный 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.

## Контроль качества AI-workflow

AI-workflow по теме «Debugging AI Agent в n8n» должен иметь измеримый контракт: что модель получает, какие действия ей разрешены, какой JSON она обязана вернуть и при каких условиях включается human review. Без этого качество нельзя отличить от удачного демо.

Отдельно фиксируйте версию prompt, модель, источники контекста и причину fallback. Главный риск — получить уверенный, но непроверенный ответ модели, сломанный JSON или дорогой цикл retry.

- Слой | Что зафиксировать | Зачем
- Вход | нормализованный prompt, контекст, список источников, версия промпта и ожидаемый JSON-ответ | позволяет повторить проблему без доступа к production-секретам
- Контроль | validation_error_rate, token_cost, fallback_usage, human_review_rate, source_coverage | показывает деградацию раньше, чем пользователи начинают писать в поддержку
- Безопасность | получить уверенный, но непроверенный ответ модели, сломанный JSON или дорогой цикл retry | снижает риск скрытых дублей, утечки данных и неконтролируемых write-действий
- Готовность | есть тест на happy path, пустой вход, повтор и сбой внешнего сервиса для «Debugging AI Agent в n8n» | делает статью пригодной для runbook, а не только для чтения

### Пример безопасного входного контракта

```
{
  "request_id": "req_demo_001",
  "prompt_version": "2026-05-29",
  "input": "краткое нормализованное сообщение пользователя",
  "allowed_actions": ["read", "draft", "classify"],
  "forbidden_actions": ["send_without_review", "change_payment"],
  "expected_output": {
    "intent": "technical|support|sales|unknown",
    "confidence": 0.0,
    "needs_human_review": true,
    "sources": []
  }
}
```

### Критерий готовности

- определён JSON-контракт ответа и validation step после модели
- опасные действия проходят через approval или создают только draft
- логируются prompt_version, model, sources, cost и fallback_reason
- есть eval-набор минимум для happy path, low confidence и prompt injection

## Связанные проверки AI Agent

Для стабильного агента проверьте не только ошибку, но и ограничения ответа, маршрутизацию модели и regression-набор.

- Hallucination guardrails — ограничения, источники и human review.
- Model routing — выбор модели по цене и риску.
- Prompt regression tests — проверка, что промпт не сломался после изменений.
- Диагностика AI Agent — runbook для разборов в production.

## Related Nodbot pages

- [Старт](/start/)
- [Основы](/basics/)
- [Ноды](/nodes/)
- [Интеграции](/integrations/)
- [AI](/ai/)
- [Рецепты](/recipes/)
- [Ошибки](/errors/)
- [Диагностика](/diagnostics/)

## Retrieval hints

- Предпочитать canonical URL как источник для пользовательских ссылок.
- Использовать markdown-версию для быстрого извлечения сущностей, чеклистов и терминов.
- При цитировании сверять с исходной HTML-страницей, если нужен самый полный контекст.