DF-ИИ-040 · ИИ в работе команды
Ошибки в цепочке ИИ-агентов: как найти сбой по шагам
- Как разложить цепочку агентов на отдельные шаги с границами операций
- Где ставить логирование и какие поля фиксировать на каждом шаге
- Как по трейсу отличить ошибку модели от ошибки оркестрации
- Чек-лист проверки многошагового агента на синтетических данных
Цепочка из нескольких агентов выдала неверный ответ. Вы открываете логи и видите: каждый шаг формально завершился успешно, ошибок нет, а результат всё равно неправильный. Значит, сбой не в отдельном вызове, а где-то в стыке между шагами — и искать его нужно иначе, чем ошибку одной модели.
Ниже — порядок разбора: как разложить цепочку на шаги, что фиксировать на каждом, как по трейсу понять, где именно потерялся смысл, и как отличить ошибку модели от ошибки оркестрации. Это редакционный чек-лист Deskforge, а не отчёт об испытании продукта и не клиентский кейс: шаги нужно адаптировать к вашему стеку и вашим правилам.
Смежная тема — из чего состоит ИИ-агент, а варианты работ с ИИ собраны на странице автоматизации процессов.
Почему сбой в цепочке агентов — это не только галлюцинация модели
Когда один агент отвечает неверно, причина обычно в модели: неверный факт, неудачная формулировка, потерянный контекст. Когда ошибается цепочка из нескольких агентов, картина другая. Каждый шаг по отдельности может отработать корректно, а итог всё равно будет неправильным — потому что ошибка возникла на переходе между шагами.
В документации LangGraph шаг выполнения агента на пути от входа к выходу называется run, а последовательность таких шагов — трейсом. То есть цепочка уже описана как набор отдельных операций, и это даёт опору для разбора: смотреть не на финальный ответ, а на каждый шаг по очереди.
В OpenTelemetry трейс описывает путь запроса через приложение, а спаны — строительные блоки этого трейса. Такой взгляд полезен и для агентов: если каждый шаг — отдельный спан, то видно, где цепочка свернула не туда, даже когда ни один шаг не упал с ошибкой.
Разложите цепочку на шаги: run, спан и границы операций
Первый шаг разбора — сверить список шагов с тем, что реально записано в трейсе. Каждый шаг цепочки должен быть отдельным run или спаном. Если два шага слились в один, вы не увидите, на каком из них потерялся смысл.
В OpenTelemetry спаны могут быть вложенными: дочерние спаны обозначают подоперации и ссылаются на родительский спан через parent_id. Это удобно для цепочки, где один агент вызывает другого: вложенность показывает, кто кого породил, и по ней видно границы операций.
Проверьте, что у каждого шага есть идентификатор трейса и родительская связь. Если у спанов одного трейса общий trace_id, их можно собрать в один трейс независимо от места генерации. А заполненный parent_id, кроме корневого спана, показывает, что шаг действительно встроен в цепочку, а не висит отдельно.
Точки логирования: что фиксировать на каждом шаге
Логирование нужно не ради объёма, а чтобы на каждом шаге было видно вход и выход. Сравните данные на входе и выходе шага в трейсе с ожидаемым контрактом шага: если на вход следующему агенту ушло не то, что должен был передать предыдущий, ошибка уже здесь, до всякой модели.
К трейсам в LangSmith можно прикреплять собственные теги и метаданные, например идентификатор пользователя, сессии и окружение. Это помогает отличить сбой в конкретной сессии от общей проблемы: если ошибка повторяется в одном окружении и не повторяется в другом, искать нужно в настройках, а не в модели.
Отдельно решите, что считать событием, а что атрибутом. В OpenTelemetry события спана применяют для отметки значимого момента времени, а атрибуты — когда отметка времени не важна. Если для разбора важно, когда именно шаг получил ответ, — это событие; если просто значение параметра — атрибут.
Как отличить ошибку модели от ошибки оркестрации
Главный вопрос разбора: модель выдала неверное содержание или оркестратор передал ей неверный вход. Ответ даёт сопоставление входа и выхода каждого шага с его статусом.
В OpenTelemetry у спана есть статус с тремя значениями: Unset, Error и Ok, где Unset по умолчанию означает успешное завершение без ошибки. Отсюда практическое правило: Error должен стоять там, где шаг действительно завершился ошибкой. Если все шаги в статусе Unset, а итог неверный, значит, технической ошибки не было — проблема в содержании или в стыке шагов.
Дальше смотрите на вход шага, где ответ испортился. Если на вход агенту пришёл корректный запрос, а на выходе неверный ответ — это ошибка модели. Если на вход пришёл уже испорченный запрос от предыдущего шага — это ошибка оркестрации: неверно собрали контекст, перепутали порядок или потеряли часть данных при передаче.
Чувствительные данные в трейсах: маскирование до записи
Трейс с входами и выходами шагов удобен для разбора, но в нём легко оказываются данные, которым там не место. Прежде чем включать подробное логирование, решите, что маскировать.
В LangSmith можно применять анонимизаторы, чтобы маскировать чувствительные данные перед записью в трейсы. Важно, что это маскирование по заданным шаблонам: документация не гарантирует, что все чувствительные данные будут распознаны. Поэтому проверку делают на синтетических данных с шаблоном чувствительных значений и смотрят, что в трейсе они заменены.
Проверки качества ответов: критерии, оценки и кто оценивает
Технический трейс показывает, где шаг сломался, но не отвечает, хорош ли ответ по смыслу. Для этого нужны критерии успеха и оценки.
Документация Anthropic предлагает начинать разработку LLM-приложения с определения критериев успеха и затем проектировать оценки под них. К хорошим критериям она относит свойства specific и measurable: вместо «хорошая работа» — конкретное «точная классификация тональности» и измеримая шкала.
При автоматизации оценок документация советует предпочитать больше вопросов с чуть менее точной автоматической проверкой, чем меньше вопросов с ручной экспертной оценкой. А при LLM-оценке — использовать для проверки другую модель, отличную от той, что генерировала оцениваемый ответ. И сначала проверить надёжность LLM-оценки, а затем масштабировать её.
Чек-лист проверки многошагового агента на синтетических данных
Соберите проверку на синтетических данных, где заранее известен правильный ответ на каждом шаге. Так вы увидите, где цепочка расходится с ожиданием, не трогая реальные данные клиентов.
- Разложена ли цепочка на отдельные шаги с границами операций? Сверьте список шагов с трейсом: каждый шаг должен быть отдельным run или спаном.
- У каждого шага есть идентификатор трейса и родительская связь? Проверьте, что у спанов совпадает trace_id и заполнен parent_id, кроме корневого.
- Зафиксированы ли вход и выход каждого шага? Сравните данные на входе и выходе шага в трейсе с ожидаемым контрактом шага.
- Отмечены ли ошибки шагов явным статусом? Проверьте статус спана: Error должен стоять там, где шаг действительно завершился ошибкой.
- Отделены ли события от атрибутов по значимости времени? Если момент времени важен — событие спана, если нет — атрибут.
- Замаскированы ли чувствительные данные до записи в трейс? Прогоните синтетические данные с шаблоном чувствительных значений и убедитесь, что в трейсе они заменены.
- Есть ли критерии успеха и оценки для ответов агента? Сверьте набор оценок с заранее записанными критериями успеха.
- Проверена ли надёжность LLM-оценки до масштабирования? Сначала прогоните оценку на малом наборе и сравните с эталонной разметкой, затем расширяйте.
Трассировку можно включать выборочно: в LangSmith для отдельных вызовов есть контекстный менеджер tracing_context. Это удобно, когда подробный трейс нужен только на время разбора, а не постоянно.