Дебаггинг AI-агентов: как flight recorder помогает найти место сбоя
AI-агент сломался — но где именно? Flight recorder записывает полный контекст каждого шага, показывает структурированный diff между прогонами и помогает найти точку отказа за минуты, а не часы.
Проблема, которую все знают, но мало кто решает
AI-агент работал. Потом перестал. Что сломалось?
Классический ответ — «где-то между вторым и пятым tool call». Это не ответ. Это капитуляция.
Агенты — не обычный код. У них нет стек-трейса в привычном смысле. Промежуточные решения зависят от контекста, который меняется на каждом шаге. Один и тот же агент с одним и тем же промптом может пойти разными путями — и один из путей окажется тупиковым. Найти, почему именно этот путь оказался тупиковым, — задача нетривиальная.
Традиционные инструменты мониторинга (LangSmith, Langfuse, Arize) показывают трейсы. Это полезно, но это уровень «что произошло». А нужен уровень «почему здесь пошло не так, а вчера шло нормально».
Flight recorder: что это и зачем
Flight recorder — инструмент, который записывает полный контекст каждого шага агента. Не просто «вызвал такой-то тул с такими-то параметрами», а весь snapshot: состояние памяти, промт на входе, ответ модели, результат tool call, временну́ю метку.
Название — прямая аналогия с авиацией. Чёрный ящик самолёта не предотвращает катастрофу. Он позволяет понять, что к ней привело. Здесь та же логика: flight recorder не делает агента умнее. Он делает его отказы понятными.
Что записывается на каждом шаге
- Входной контекст — полный промт, включая системное сообщение и историю
- Решение модели — какой tool call выбран и с какими аргументами
- Результат вызова — что вернул инструмент (или ошибка)
- Временна́я метка — с точностью до миллисекунд
- Метаданные — модель, температура, количество токенов
Всё это сохраняется как единый прогон (run), который потом можно анализировать.
Что нового в v2.8.5
Три ключевых изменения, каждое из которых решает конкретную боль.
1. Структурированный diff между прогонами
Это главная фича обновления. Берёшь успешный прогон и неуспешный — flight recorder показывает структурированный diff. Не текстовый diff в духе git, а семантический: на каком шаге поведение разошлось, какие аргументы отличались, какой контекст привёл к другому решению.
Практический сценарий: агент по обработке заявок работал неделю. В понедельник начал пропускать заявки определённого типа. Берёшь пятничный успешный прогон, берёшь понедельничный неуспешный — diff показывает, что на третьем шаге агент стал получать другой формат ответа от API. Не агент сломался — API изменил контракт.
Без diff ты бы копал в промтах. С diff — видишь проблему за три минуты.
2. Временны́е метки на каждый tool call
Каждый вызов инструмента теперь снабжён точной временно́й меткой. Во-первых, видно, где агент «зависает». Если между вторым и третьим tool call проходит 45 секунд вместо обычных 2 — это сигнал. Может быть таймаут внешнего API, может быть слишком длинный контекст, заставляющий модель думать дольше.
Во-вторых, это критично для агентов, работающих с time-sensitive данными. Если агент берёт курс валюты в 14:00:01 и принимает решение в 14:00:47, а за эти 46 секунд курс изменился — ты теперь это видишь.
3. Экспорт в JSON
Прогоны экспортируются в структурированный JSON. Это открывает серьёзные возможности:
- Автоматический анализ — можно натравить скрипт на сотни прогонов и найти паттерны отказов
- Интеграция с дашбордами — Grafana, Datadog, что угодно
- Регрессионное тестирование — сохраняешь эталонный прогон в JSON, после изменения промта сравниваешь с новым
- Шаринг — отправить JSON коллеге проще, чем объяснять словами «на четвёртом шаге он почему-то решил вызвать не тот тул»
Как это встраивается в рабочий процесс
Flight recorder не требует менять архитектуру агента. Он работает как обёртка (wrapper): оборачиваешь вызовы агента — и всё записывается.
Типичный цикл: агент ломается в продакшне → находишь неуспешный прогон в flight recorder → находишь последний успешный прогон с похожим входом → запускаешь diff → видишь точку расхождения → фиксишь (промт, тул, данные) → прогоняешь заново, сохраняешь как новый эталон.
Шаги поиска и анализа занимают минуты. Без flight recorder те же шаги — это часы чтения логов и попытки воспроизвести проблему «на глаз».
Когда flight recorder избыточен
Не каждому агенту нужен чёрный ящик. Избыточен для: простого агента с одним tool call, прототипа на ранней стадии, агентов без внешних вызовов, где обычного логирования достаточно.
Flight recorder нужен, когда агент делает больше 3 шагов, вызывает внешние API или инструменты, работает в продакшне, где важна стабильность, или ломается «иногда» — и проблему невозможно воспроизвести.
Сравнение с существующими инструментами
LangSmith и Langfuse — отличные инструменты для мониторинга: показывают трейсы, поддерживают JSON-экспорт. Но структурированный семантический diff между прогонами — уникальная фича flight recorder. LangSmith не поддерживает self-hosted и не имеет семантического сравнения прогонов. Langfuse поддерживает self-hosted, но тоже не имеет diff.
LangSmith и Langfuse — инструменты для мониторинга. Flight recorder — инструмент для расследования. Они не взаимозаменяемы, они комплементарны.
Практические выводы
Первое. Если ваши агенты работают в продакшне и периодически ломаются — вам нужен инструмент уровня flight recorder. Не обязательно именно этот — но что-то, что записывает полный контекст и позволяет сравнивать прогоны.
Второе. Структурированный diff между прогонами — это та фича, которой не хватало всей экосистеме. Трейсы без сравнения — это как иметь логи без grep.
Третье. Временны́е метки на каждый tool call — мелочь, но в продакшне именно такие мелочи превращают «я не знаю, почему сломалось» в «сломалось из-за таймаута внешнего API на третьем шаге».
Дебаггинг AI-агентов — дисциплина, которая ещё формируется. Flight recorder — один из инструментов, который двигает её в правильном направлении: от «перечитать логи и надеяться» к «найти точку отказа и починить».