Как вести журнал действий ИИ-агента, чтобы разобрать ошибку

Если агент ошибся, запись «ответ не понравился» почти бесполезна. Чтобы восстановить цепочку, нужно знать, какую задачу ему поставили, какие данные он видел, какой инструмент вызвал и в какой момент человек подтвердил действие. Журнал не обязан сохранять каждую скрытую мысль модели. Наоборот, он должен фиксировать наблюдаемые события, которые помогают повторить запуск и объяснить последствия. Это особенно важно для систем, которые не только пишут текст, но и работают с почтой, CRM, файлами или задачами.

Сначала определите, что будете расследовать

Начните не с выбора базы логов, а со списка типичных вопросов после сбоя. Нужно понять, почему агент выбрал неправильный файл? Кто разрешил отправить письмо? Использовалась ли устаревшая инструкция? Ответы определяют поля, которые действительно нужны. Минимальная запись обычно включает идентификатор запуска, время, инициатора, версию сценария и модели, краткую формулировку задачи, перечень доступных инструментов, события вызовов, результат каждого шага, запрос подтверждения и решение человека.

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

Записывайте действия, а не догадки модели

Представьте задачу «подготовить черновик ответа на письмо». В журнале важно видеть: агент прочитал сообщение с идентификатором, запросил заказ с номером, получил статус «доставлен», создал черновик, но не отправлял его. Не нужно записывать внутреннюю цепочку рассуждений или полный текст каждого файла. Достаточны тип события, минимальная ссылка на ресурс, результат и код ошибки. Для чувствительного действия добавьте отдельное событие «ожидало подтверждения» и «подтверждено пользователем X».

Если агент может повторять запрос, сохраняйте ключ идемпотентности и номер попытки. Тогда два одинаковых события можно отличить от двух реальных отправок. Храните также ответ инструмента в минимальном структурированном виде: например, status=delivered, а не полный пакет персональных данных. В карточке негативных тестов для почтового агента есть примеры сценариев, где особенно важно доказать, что отправка была заблокирована.

Установите правила для секретов и хранения

До включения журнала составьте перечень данных, которые запрещено писать: пароли, API-ключи, банковские реквизиты, специальные категории персональных данных и полные тексты запросов, если в них встречается закрытая информация. На границе логирования поставьте фильтр и тестируйте его не только на очевидной строке sk-..., но и на секретах в заголовках, вложениях и сообщениях об ошибке. Маскирование должно работать и при исключениях, иначе наиболее опасные значения появятся именно в аварийных логах.

Установите срок хранения по цели расследования и требованиям компании. «Пусть будет навсегда» редко оправдано: объём растёт, доступов становится больше, а старые записи могут вводить в заблуждение. Назначьте владельца, который одобряет доступ к журналам, и отдельную процедуру выгрузки для инцидента. Удаление тоже должно проверяться: если копии уходят в резервный индекс, правила для них должны быть понятны.

Проверьте журнал на сценариях отказа

Запустите тесты, где доступ запрещён, инструмент недоступен, ответ приходит дважды или человек отклоняет подтверждение. Затем попросите коллегу, не настраивавшего агента, восстановить по записям последовательность событий и ответить на три вопроса: что агент пытался сделать, что реально сделал и кто принял решение. Если для этого приходится открывать десяток разрозненных систем, связь по run_id недостаточна.

Проверьте также задержку и стоимость записи. Слишком подробный синхронный лог может тормозить каждую операцию; слишком редкий — оставлять пробелы. Можно отправлять события в очередь, но отдельно определить поведение при недоступности очереди: безопасное действие иногда должно остановиться, а не продолжить работу без аудита. Решение зависит от риска сценария, а не от удобства разработчика.

Итоговый контрольный список

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

FAQ

Нужно ли сохранять полный диалог? Обычно нет: достаточно события, краткого результата и защищённой ссылки на исходный объект.

Можно ли записывать цепочку рассуждений модели? В этом гайде речь о наблюдаемых действиях и решениях, а не о внутреннем рассуждении.

Как понять, что журнал полезен? Коллега, не участвовавший в настройке, должен восстановить ход операции и различить намерение агента от реально выполненного действия.

Как запустить журнал без отдельной платформы

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

Перед запуском определите владельца журнала. Кто вправе смотреть детали? Кто удаляет запись по истечении срока? Кто отвечает, если логгер недоступен? Для простого сценария ответы могут быть короткими, но ответственность не должна растворяться между командой модели и владельцем продукта. Раз в несколько недель проводите пробное расследование: выберите один завершённый прогон и проверьте, можно ли собрать последовательность действий без доступа к секретам и полным документам.