На главную

DF-ИИ-040 · ИИ в работе команды

Ошибки в цепочке ИИ-агентов: как найти сбой по шагам

Редакция Deskforge · 18 ноября 2026 · 6 мин чтения
Ошибки в цепочке ИИ-агентов: как найти сбой по шагам
Из статьи вы узнаете
  • Как разложить цепочку агентов на отдельные шаги с границами операций
  • Где ставить логирование и какие поля фиксировать на каждом шаге
  • Как по трейсу отличить ошибку модели от ошибки оркестрации
  • Чек-лист проверки многошагового агента на синтетических данных

Цепочка из нескольких агентов выдала неверный ответ. Вы открываете логи и видите: каждый шаг формально завершился успешно, ошибок нет, а результат всё равно неправильный. Значит, сбой не в отдельном вызове, а где-то в стыке между шагами — и искать его нужно иначе, чем ошибку одной модели.

Ниже — порядок разбора: как разложить цепочку на шаги, что фиксировать на каждом, как по трейсу понять, где именно потерялся смысл, и как отличить ошибку модели от ошибки оркестрации. Это редакционный чек-лист 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. Это удобно, когда подробный трейс нужен только на время разбора, а не постоянно.

Источники

Назад