Последние
Разработка

Наблюдаемость ИИ-агента: как читать трассу выполнения

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

В этом материале8 разделов
Трасса ИИ-агента связывает входное состояние, фактический вызов инструмента, его результат и следующий переход. Схема показывает порядок событий для поиска ошибки.
Редакционная схема PENROUZ NEWS. Предложение действия и его выполнение — разные события.PENROUZ NEWS

Сообщить об ошибке или предложить уточнение

Короткий ответ: записывайте решения и переходы, а не только финальный текст

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

Трасса полезна прежде всего как средство диагностики. Она не делает результат правильным сама по себе и не раскрывает скрытые рассуждения модели. В журнале достаточно фиксировать наблюдаемые решения системы: тип действия, проверенные параметры, идентификатор результата, изменение состояния, правило остановки и контроль доступа. Секреты, персональные данные и полный внутренний запрос не следует копировать в журнал без необходимости.

Сначала определите границу системы. Материал о том, чем ИИ-агент отличается от чат-бота, помогает отделить динамический выбор шага от обычного ответа или заранее заданного workflow. Трассировка нужна именно там, где система сама выбирает между несколькими разрешёнными действиями и результат одного шага влияет на следующий.

Трасса, лог и метрика решают разные задачи

Лог — отдельная запись о событии: например, инструмент вернул ошибку проверки параметров. Трасса связывает события одной логической операции общим идентификатором и отношениями между шагами. Метрика агрегирует множество запусков и отвечает на общий вопрос, например как часто процесс завершается эскалацией. Для разбора конкретной неудачи нужна трасса; для поиска повторяющейся проблемы — метрики, построенные из однородных событий.

В спецификации OpenTelemetry распределённая трасса описана как набор событий одной логической операции, представленных spans. Span содержит имя операции, время, атрибуты, события и контекст связи. Для агентного процесса этот механизм можно использовать как транспортную модель: отдельный span для цикла задачи, дочерние spans для обращений к инструментам, а события — для перехода состояния и решения остановиться. Это техническая опора; конкретная схема полей ниже — учебный пример, а не требование спецификации.

Какие события должны попасть в журнал

Минимальная трасса агентного шага

СобытиеЧто записатьЧто можно проверить
Старт задачиtrace_id, тип цели, версия входного состоянияНе смешаны ли два запуска; получены ли обязательные данные
Выбор действияstep, выбранное действие, код основания, список допустимых действийВходило ли действие в разрешённый набор; не повторяется ли цикл
Проверка параметровимя схемы, результат валидации, отклонённые поля без секретных значенийСоответствуют ли параметры контракту до вызова
Вызов инструментаtool_call_id, имя инструмента, разрешение, безопасные параметры или их хешБыл ли вызов разрешён и однозначно связан с результатом
Результат инструментаtool_call_id, статус, идентификатор результата, класс ошибкиПолучен ли реальный результат; корректно ли обработана ошибка
Переход состояниястарая и новая версии состояния, причина переходаНе потерян ли результат и не перезаписано ли подтверждённое состояние
Остановка или эскалацияпричина, достигнутый критерий, адресат передачиЗавершена ли цель; не выдан ли неполный результат за готовый
Учебная схема полей. Она показывает структуру проверки и не является записью реального запуска модели.

Единый trace_id связывает весь запуск, а отдельный tool_call_id — запрос к инструменту с его ответом. Номер шага сам по себе недостаточен: при параллельных действиях или повторе нужно хранить связь родителя и потомка. Причину выбора лучше кодировать небольшим контролируемым набором значений — например, «нужны данные», «требуется проверка», «условие готовности выполнено» — и при необходимости добавлять короткое безопасное пояснение.

Не записывайте как факт то, чего приложение не наблюдало. Если модель предложила вызвать инструмент, это ещё не означает, что инструмент был выполнен. Сохраняйте отдельно предложение действия, результат проверки полномочий, фактический вызов и фактический ответ. Такое разделение позволяет отличить ошибку выбора от отказа доступа, ошибки интеграции и неправильной интерпретации корректного результата.

Шаблон одного события

Шаблон записи события трассы
trace_id: task-example-17
event: tool_result
step: 2
parent_event: tool_call-example-2
tool: read_order_status
permission_check: allowed
parameter_validation: passed
result_status: success
result_reference: result-example-2
state_before: state-example-3
state_after: state-example-4
next_transition: prepare_draft
stop_reason: not_reached

В рабочей системе значения полей выбирают под конкретный процесс. Сохраняйте ссылку на результат или очищенный фрагмент вместо полного ответа инструмента, если ответ может содержать чувствительные данные. Статус permission_check должен формироваться доверенным слоем приложения, а не текстом модели. Для ошибки полезно сохранять устойчивый класс, например validation_failed или tool_unavailable, и отдельно — безопасное техническое сообщение.

Как прочитать трассу и найти место сбоя

  1. Начните с причины остановки. Если она отсутствует или не соответствует критерию готовности, проблема находится в управлении циклом, даже когда финальный текст выглядит убедительно.
  2. Идите назад по связям событий до последнего подтверждённого результата. Проверьте, был ли он получен от реального инструмента и перенесён в следующее состояние без подмены.
  3. Сопоставьте предложенное действие с разрешённым набором и результатом проверки параметров. Так ошибка выбора отделяется от ошибки исполнения.
  4. Проверьте повторяющиеся переходы. Одинаковая пара состояния и действия без нового результата указывает на цикл, который должен остановить лимит или правило эскалации.
  5. Воспроизведите учебный вход на изолированном стенде и сравните только наблюдаемые события с ожидаемой последовательностью. Изменяйте одну причину за раз.

Переходы следует сверять не с длинной историей чата, а с явно сохранённым состоянием. В разборе про память ИИ-агента показано, чем рабочий контекст отличается от состояния задачи и долговременного хранилища. В трассе полезно указывать версии состояния и ссылку на запись, но не дублировать всё содержимое памяти.

Практикум: заказ не дошёл до оператора

Рассмотрим вымышленный агент поддержки. Его цель — прочитать статус заказа и подготовить черновик оператору. Разрешены только два инструмента: read_order_status и create_operator_draft. Изменять заказ и отправлять сообщение клиенту агент не может. Ожидаемая последовательность: проверить наличие идентификатора, прочитать статус, проверить результат, создать черновик и остановиться с причиной draft_prepared.

Предположим, финальный ответ сообщает, что обращение подготовлено, но оператор его не видит. В трассе есть успешный read_order_status, затем событие выбора create_operator_draft, однако нет permission_check, tool_call и tool_result для второго инструмента. Значит, текст о готовом черновике появился до фактического выполнения. Исправление относится не к формулировке ответа: приложение должно разрешать утверждение о создании только после связанного успешного результата инструмента.

Параметры вызова и результат лучше хранить в предсказуемой форме. Руководство про структурированный JSON от ИИ объясняет, почему соответствие схеме проверяет форму, но не истинность значений. В трассе отдельно отмечайте прохождение схемы и смысловую проверку по доверенной системе.

Где поставить границы наблюдаемости

Полная копия каждого промпта и ответа обычно создаёт больше риска, чем пользы. Определите минимальный набор полей для воспроизведения перехода, удаляйте секреты до записи и ограничивайте доступ к журналу. Для содержимого инструмента используйте идентификатор, контрольную сумму или очищенный фрагмент, если этого достаточно для проверки. Срок хранения должен следовать назначению журнала, а не желанию сохранить всё навсегда.

Не позволяйте недоверенному документу управлять полями трассы или скрывать события. Название инструмента, результат проверки прав и причина блокировки должны поступать от доверенного кода. Текст, прочитанный агентом, можно пометить как входные данные, но не как системное правило.

Если агент читает внешние страницы или документы, следующим шагом проверьте защиту от промпт-инъекции: журнал должен показать источник фрагмента, попытку выбрать действие и место, где ограничение остановило нежелательный вызов. Отсутствие запрещённого инструмента остаётся надёжнее одной текстовой инструкции.

Критерий готовности

Трасса пригодна для диагностики, если по ней можно однозначно связать вход, каждый разрешённый вызов, фактический результат, изменение состояния и финальную причину остановки. Для вымышленного практикума проверка проходит, когда событие «черновик подготовлен» появляется только после успешного tool_result, а отсутствие идентификатора приводит к запросу данных или эскалации, но не к догадке.

После изменения инструкции, набора инструментов или схемы состояния повторите один и тот же контрольный набор и сравните последовательности событий. Если журнал не различает предложение действия и выполнение, скрывает проверку полномочий либо не показывает, почему процесс остановился, увеличивать автономность рано. Сначала сделайте переходы наблюдаемыми и воспроизводимыми.

В этом материале

На этом устройстве

Сохранённые материалы