Автодиагностика агентных сбоев: как читать LangChain-трейсы и находить корень проблемы

Проблема, которую все знают, но мало кто решает

Пользователь спрашивает агента: «Перенеси мой рейс на завтра утром». Агент отвечает: «Я нашёл несколько отелей рядом с аэропортом». Уверенно. Вежливо. Абсолютно не то.

Открываешь трейс. Видишь цепочку шагов — retrieval, обработка, генерация. Каждый шаг по отдельности выглядит разумно. Но результат ошибочен. Где именно сломалось? Retrieval подтянул не те документы? Кеш подмешал чужой intent? Модель слишком рано зафиксировалась на неверной интерпретации?

Ручной разбор трейса на длинных цепочках — это часы работы. И чем сложнее агент, тем больше промежуточных шагов, тем труднее проследить каузальную связь от симптома к причине.

Эта проблема — тихие, правдоподобные ошибки — ключевой барьер для вывода агентов в продакшн. Если ты не можешь объяснить, почему агент ошибся, ты не можешь гарантировать, что он не ошибётся снова.

Что делает инструмент

Два open-source репозитория, работающих в связке:

llm-failure-atlas — каузальный граф из 12 паттернов отказа LLM-агентов. Каждый паттерн — узел графа, рёбра — причинно-следственные связи. Граф включает matcher, который по сигналам из трейса определяет, какие паттерны сработали.

agent-failure-debugger — берёт выход matcher'а, обходит каузальный граф, ранжирует корневые причины, генерирует патчи для исправления и применяет их автоматически, если уровень уверенности достаточно высок.

Для LangChain есть адаптер, который конвертирует JSON-трейс напрямую во входной формат matcher'а. Никакой предобработки.

12 паттернов отказа: каузальная модель

Инструмент опирается не на эвристики, а на формальный граф причинно-следственных связей. Ключевые паттерны из атласа:

1. premature_model_commitment — модель слишком рано фиксируется на одной интерпретации запроса и игнорирует альтернативы
2. semantic_cache_intent_bleeding — семантический кеш возвращает результат для похожего, но другого intent'а
3. rag_retrieval_drift — retrieval подтягивает документы, семантически близкие к запросу, но нерелевантные по смыслу задачи
4. incorrect_output — финальный симптом: агент вернул неверный ответ

Эти паттерны связаны каузально: premature_model_commitment → semantic_cache_intent_bleeding → rag_retrieval_drift → incorrect_output. Один неверный ответ на поверхности, три узла отказа в цепочке, одна исправимая корневая причина.

Два уровня диагностики

Глубина анализа напрямую зависит от качества телеметрии в трейсе.

Уровень 1: базовый LangChain-трейс

Когда retrieval-телеметрия минимальна, matcher ловит поверхностный симптом: обнаружено incorrect_output с confidence 0.7, корневая причина не раскрыта, уровень proposal_only. Ты знаешь, что что-то сломалось. Но ещё не знаешь — что именно.

Уровень 2: расширенная телеметрия

Когда в трейсе есть сигналы кеша, intent-скоры, счётчики повторных вызовов инструментов — каузальная цепочка раскрывается полностью: обнаружены premature_model_commitment (0.85), semantic_cache_intent_bleeding (0.81), rag_retrieval_drift (0.74). Каузальный путь прослеживается до корня. Корневая причина: premature_model_commitment. Уровень: staged_review — патч записан в patches/.

Тот же неверный ответ на поверхности. Но теперь видно: модель зафиксировалась на интерпретации «поездка» вместо «перелёт», кеш подтвердил ошибочный intent, retrieval подтянул документы про отели. Три звена цепи. Одно исправимое место.

Ключевое архитектурное решение

Инструмент масштабируется без изменений кода. Чем больше сигналов адаптер захватывает из трейса, тем глубже автоматически становится диагностика. Добавил логирование cache-hit'ов — появились паттерны кеш-блидинга. Добавил intent-скоры — появился premature commitment.

Внедрение постепенное: начинаешь с базового LangChain-трейса, получаешь поверхностную диагностику, затем обогащаешь телеметрию и получаешь каузальный анализ — без переписывания пайплайна.

Практическое применение

Когда это нужно

• Продакшн-агенты с обращениями пользователей, где ошибка стоит денег или репутации
• Отладка RAG-пайплайнов, где retrieval «выглядит нормально», но результат неверен
• CI/CD для агентов: запуск диагностики на тестовом наборе перед деплоем
• Post-mortem анализ: вместо ручного разбора трейса — автоматический каузальный отчёт

Как начать

Установка — одна зависимость (pyyaml), Python 3.12+. Подключаешь LangChain-адаптер, скармливаешь трейс JSON, получаешь диагностику. Для глубокой диагностики нужно обогатить телеметрию: логировать cache-hit'ы с intent-скорами, фиксировать retrieval-метрики, считать повторные вызовы инструментов.

Ограничения

Валидационный набор пока синтетический — 30 сценариев. Инструменту нужны реальные трейсы с неочевидными сбоями для калибровки. Автопатчинг работает только при высокой уверенности (staged_review). При низкой — выдаёт рекомендации, но не применяет исправления автоматически.

Почему это важно

Индустрия научилась строить агентов. Но не научилась их отлаживать. Текущий подход — «смотрим в трейс глазами» — не масштабируется. Каузальный граф паттернов отказа — шаг к тому, чтобы отладка агентов стала инженерной дисциплиной, а не искусством.

12 паттернов — не финальный список. Но сам подход — формализация каузальных связей между типами отказов — меняет парадигму. Вместо «агент ошибся, давайте подправим промпт» — «вот корневая причина, вот патч, вот уровень уверенности».

Для тех, кто выводит агентов в продакшн, это не просто инструмент. Это необходимый слой инфраструктуры.