Наблюдаемость ИИ-агента: как читать трассу выполнения
Наблюдаемость превращает работу агента из непрозрачного ответа в последовательность проверяемых событий. Полезная трасса показывает входное состояние, решение о следующем шаге, вызов инструмента, его результат, переход состояния и причину остановки или передачи человеку.
Короткий ответ: записывайте решения и переходы, а не только финальный текст
Наблюдаемость ИИ-агента — это возможность восстановить ход одной задачи по журналу событий. Для каждого шага важно увидеть, какое состояние получил агент, какое действие выбрал, какие параметры передал разрешённому инструменту, что инструмент вернул и почему процесс продолжился, остановился либо был передан человеку. Финальный ответ без этой цепочки не объясняет, где возникла ошибка.
Трасса полезна прежде всего как средство диагностики. Она не делает результат правильным сама по себе и не раскрывает скрытые рассуждения модели. В журнале достаточно фиксировать наблюдаемые решения системы: тип действия, проверенные параметры, идентификатор результата, изменение состояния, правило остановки и контроль доступа. Секреты, персональные данные и полный внутренний запрос не следует копировать в журнал без необходимости.
Сначала определите границу системы. Материал о том, чем ИИ-агент отличается от чат-бота, помогает отделить динамический выбор шага от обычного ответа или заранее заданного workflow. Трассировка нужна именно там, где система сама выбирает между несколькими разрешёнными действиями и результат одного шага влияет на следующий.
Трасса, лог и метрика решают разные задачи
Лог — отдельная запись о событии: например, инструмент вернул ошибку проверки параметров. Трасса связывает события одной логической операции общим идентификатором и отношениями между шагами. Метрика агрегирует множество запусков и отвечает на общий вопрос, например как часто процесс завершается эскалацией. Для разбора конкретной неудачи нужна трасса; для поиска повторяющейся проблемы — метрики, построенные из однородных событий.
В спецификации OpenTelemetry распределённая трасса описана как набор событий одной логической операции, представленных spans. Span содержит имя операции, время, атрибуты, события и контекст связи. Для агентного процесса этот механизм можно использовать как транспортную модель: отдельный span для цикла задачи, дочерние spans для обращений к инструментам, а события — для перехода состояния и решения остановиться. Это техническая опора; конкретная схема полей ниже — учебный пример, а не требование спецификации.
Какие события должны попасть в журнал
Минимальная трасса агентного шага
Событие
Что записать
Что можно проверить
Старт задачи
trace_id, тип цели, версия входного состояния
Не смешаны ли два запуска; получены ли обязательные данные
Выбор действия
step, выбранное действие, код основания, список допустимых действий
Входило ли действие в разрешённый набор; не повторяется ли цикл
Проверка параметров
имя схемы, результат валидации, отклонённые поля без секретных значений
Соответствуют ли параметры контракту до вызова
Вызов инструмента
tool_call_id, имя инструмента, разрешение, безопасные параметры или их хеш
Был ли вызов разрешён и однозначно связан с результатом
Результат инструмента
tool_call_id, статус, идентификатор результата, класс ошибки
Получен ли реальный результат; корректно ли обработана ошибка
Переход состояния
старая и новая версии состояния, причина перехода
Не потерян ли результат и не перезаписано ли подтверждённое состояние
Остановка или эскалация
причина, достигнутый критерий, адресат передачи
Завершена ли цель; не выдан ли неполный результат за готовый
Учебная схема полей. Она показывает структуру проверки и не является записью реального запуска модели.
Единый trace_id связывает весь запуск, а отдельный tool_call_id — запрос к инструменту с его ответом. Номер шага сам по себе недостаточен: при параллельных действиях или повторе нужно хранить связь родителя и потомка. Причину выбора лучше кодировать небольшим контролируемым набором значений — например, «нужны данные», «требуется проверка», «условие готовности выполнено» — и при необходимости добавлять короткое безопасное пояснение.
Не записывайте как факт то, чего приложение не наблюдало. Если модель предложила вызвать инструмент, это ещё не означает, что инструмент был выполнен. Сохраняйте отдельно предложение действия, результат проверки полномочий, фактический вызов и фактический ответ. Такое разделение позволяет отличить ошибку выбора от отказа доступа, ошибки интеграции и неправильной интерпретации корректного результата.
В рабочей системе значения полей выбирают под конкретный процесс. Сохраняйте ссылку на результат или очищенный фрагмент вместо полного ответа инструмента, если ответ может содержать чувствительные данные. Статус permission_check должен формироваться доверенным слоем приложения, а не текстом модели. Для ошибки полезно сохранять устойчивый класс, например validation_failed или tool_unavailable, и отдельно — безопасное техническое сообщение.
Как прочитать трассу и найти место сбоя
Начните с причины остановки. Если она отсутствует или не соответствует критерию готовности, проблема находится в управлении циклом, даже когда финальный текст выглядит убедительно.
Идите назад по связям событий до последнего подтверждённого результата. Проверьте, был ли он получен от реального инструмента и перенесён в следующее состояние без подмены.
Сопоставьте предложенное действие с разрешённым набором и результатом проверки параметров. Так ошибка выбора отделяется от ошибки исполнения.
Проверьте повторяющиеся переходы. Одинаковая пара состояния и действия без нового результата указывает на цикл, который должен остановить лимит или правило эскалации.
Воспроизведите учебный вход на изолированном стенде и сравните только наблюдаемые события с ожидаемой последовательностью. Изменяйте одну причину за раз.
Переходы следует сверять не с длинной историей чата, а с явно сохранённым состоянием. В разборе про память ИИ-агента показано, чем рабочий контекст отличается от состояния задачи и долговременного хранилища. В трассе полезно указывать версии состояния и ссылку на запись, но не дублировать всё содержимое памяти.
Практикум: заказ не дошёл до оператора
Рассмотрим вымышленный агент поддержки. Его цель — прочитать статус заказа и подготовить черновик оператору. Разрешены только два инструмента: read_order_status и create_operator_draft. Изменять заказ и отправлять сообщение клиенту агент не может. Ожидаемая последовательность: проверить наличие идентификатора, прочитать статус, проверить результат, создать черновик и остановиться с причиной draft_prepared.
Предположим, финальный ответ сообщает, что обращение подготовлено, но оператор его не видит. В трассе есть успешный read_order_status, затем событие выбора create_operator_draft, однако нет permission_check, tool_call и tool_result для второго инструмента. Значит, текст о готовом черновике появился до фактического выполнения. Исправление относится не к формулировке ответа: приложение должно разрешать утверждение о создании только после связанного успешного результата инструмента.
Параметры вызова и результат лучше хранить в предсказуемой форме. Руководство про структурированный JSON от ИИ объясняет, почему соответствие схеме проверяет форму, но не истинность значений. В трассе отдельно отмечайте прохождение схемы и смысловую проверку по доверенной системе.
Где поставить границы наблюдаемости
Полная копия каждого промпта и ответа обычно создаёт больше риска, чем пользы. Определите минимальный набор полей для воспроизведения перехода, удаляйте секреты до записи и ограничивайте доступ к журналу. Для содержимого инструмента используйте идентификатор, контрольную сумму или очищенный фрагмент, если этого достаточно для проверки. Срок хранения должен следовать назначению журнала, а не желанию сохранить всё навсегда.
Не позволяйте недоверенному документу управлять полями трассы или скрывать события. Название инструмента, результат проверки прав и причина блокировки должны поступать от доверенного кода. Текст, прочитанный агентом, можно пометить как входные данные, но не как системное правило.
Если агент читает внешние страницы или документы, следующим шагом проверьте защиту от промпт-инъекции: журнал должен показать источник фрагмента, попытку выбрать действие и место, где ограничение остановило нежелательный вызов. Отсутствие запрещённого инструмента остаётся надёжнее одной текстовой инструкции.
Критерий готовности
Трасса пригодна для диагностики, если по ней можно однозначно связать вход, каждый разрешённый вызов, фактический результат, изменение состояния и финальную причину остановки. Для вымышленного практикума проверка проходит, когда событие «черновик подготовлен» появляется только после успешного tool_result, а отсутствие идентификатора приводит к запросу данных или эскалации, но не к догадке.
После изменения инструкции, набора инструментов или схемы состояния повторите один и тот же контрольный набор и сравните последовательности событий. Если журнал не различает предложение действия и выполнение, скрывает проверку полномочий либо не показывает, почему процесс остановился, увеличивать автономность рано. Сначала сделайте переходы наблюдаемыми и воспроизводимыми.