Обсервабельность ИИ-агентов: Логи, трассировка и аудиторские следы для небольших команд

Каждый развернутый вами автономный агент принимает десятки микро-решений за задачу — какой инструмент вызвать, как интерпретировать результат, стоит ли повторять попытку или эскалировать. Без структурированной обсервабельности эти решения происходят в «черном ящике». Когда что-то идет не так (а это случится), вы остаетесь в неведении.

Обсервабельность ИИ-агентов — это не роскошь для корпоративных команд с выделенными инженерами платформ. Это базовая практика для любой команды, запускающей агентов в продакшене. Хорошая новость: небольшая команда может построить действительно полезную инфраструктуру логирования, трассировки и аудита за выходные, используя лишь структурированные файлы, конвенцию корреляционных идентификаторов и привычку к еженедельному анализу.

В этом гайде мы подробно разберем, что именно захватывать, как это структурировать, где хранить и как превращать необработанные логи в полезные сеансы отладки — без покупки платформы обсервабельности, которую вы так и не настроите.

Чем обсервабельность ИИ-агентов отличается от мониторинга традиционных приложений

Традиционная обсервабельность приложений (вспомните Datadog, Grafana или даже обычный journald) предполагает детерминированный код: одинаковый вход → одинаковый выход, предсказуемые графы вызовов, четко определенные коды ошибок. LLM-агенты нарушают каждое из этих предположений.

Недетерминизм. Один и тот же промпт может давать разные результаты при разных запусках. Сбой во вторник может не воспроизвестись в среду. Вам нужно логировать *точный* вход и выход, а не просто «произошла ошибка».

Цепочки вызова инструментов. Современные агенты не просто генерируют текст — они читают файлы, запрашивают базы данных, вызывают API, просматривают веб-сайты. Одна задача может включать 8–15 вызовов инструментов за несколько ходов модели. Традиционное логирование запросов/ответов захватывает внешнюю обертку, но полностью пропускает внутреннее дерево выполнения.

Непрозрачность стоимости. Каждый токен имеет свою цену. Один запуск агента, зациклившийся неожиданно, может сжечь $2–$5 до того, как кто-то заметит. Обсервабельность для агентов должна включать отслеживание стоимости на уровне задачи, а не только в месячной сводке по счету.

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

Что логировать: практическая схема для каждого запуска агента

Не усложняйте с первого раза. Начните с одного JSONL-файла (по одному JSON-объекту на строку) для каждого агента в день. Каждая запись лога должна содержать следующие поля:

Обязательные поля для каждого события

{
  "ts": "2026-07-09T14:23:01.337Z",
  "correlation_id": "a1b2c3d4-...",
  "agent": "researcher",
  "event": "model_call | tool_call | tool_result | error | task_complete",
  "status": "ok | error | timeout | retry",
  "input_summary": "первые 200 символов промпта или входных данных инструмента",
  "output_summary": "первые 200 символов ответа или вывода инструмента",
  "model": "claude-sonnet-4-20250514",
  "tokens_in": 1240,
  "tokens_out": 830,
  "cost_usd": 0.0041,
  "latency_ms": 2340,
  "tool_name": "web_search | null",
  "error_detail": "timeout after 30s | null"
}

Почему именно эти поля

• correlation_id — это основа вашей трассировки. Сгенерируйте его один раз в начале задачи; передавайте в каждый дочерний вызов. Без него восстановить многшаговый запуск невозможно.
• input_summary и output_summary дают достаточно контекста для первичной сортировки без хранения полных нагрузок (которые могут быть огромными). Храните полные нагрузки отдельно, если вам нужна возможность воспроизведения — но сводки именно то, что вы будете просматривать ежедневно.
• cost_usd должна рассчитываться в реальном времени, используя опубликованные провайдером цены за токен. Даже приблизительная оценка лучше, чем слепые расходы.
• error_detail для событий успеха должно быть null. При сбоях захватывайте сообщение об ошибке провайдера *и* вашу внутреннюю классификацию (например, context_length_exceeded, tool_timeout, safety_filter).

Чего НЕ логировать в основном потоке

• Полную историю диалога при каждом событии (избыточно; логируйте один раз при событии task_complete).
• Эмбеддинг-векторы (они велики и редко полезны для отладки).
• Персональные данные конечных пользователей без отдельного этапа обезличивания.

Трассировка многшагового выполнения агента

Одна задача «написать пост для блога» может включать: планирование → генерация плана → веб-исследование (3–5 вызовов инструментов) → черновик → самопроверка → редактирование → форматирование. Это 10–20 ходов модели и 5–10 вызовов инструментов.

Для осмысленной трассировки примите модель спанов, вдохновленную распределенной трассировкой (OpenTelemetry, Jaeger):

Задача: a1b2c3d4
├── Спан 1: plan_outline          [model_call, 1.2s, $0.003]
├── Спан 2: web_research
│   ├── Спан 2.1: search("topic")  [tool_call, 0.8s]
│   ├── Спан 2.2: fetch(url_1)     [tool_call, 1.1s]
│   ├── Спан 2.3: fetch(url_2)     [tool_call, 0.9s]
│   └── Спан 2.4: summarise        [model_call, 2.3s, $0.005]
├── Спан 3: draft_sections         [model_call, 4.1s, $0.012]
├── Спан 4: self_review            [model_call, 1.8s, $0.004]
└── Спан 5: format_output          [model_call, 0.6s, $0.001]

Каждый спан — это запись лога с двумя дополнительными полями: span_id и parent_span_id. Это позволяет восстановить дерево из плоского лог-файла простым скриптом — без инфраструктуры распределенной трассировки.

Конкретный совет по реализации: Когда ваш код агента вызывает инструмент, сгенерируйте новый span_id, установите parent_span_id на текущий спан и залогируйте событие tool_call. Когда инструмент возвращает результат, залогируйте событие tool_result с тем же span_id. Эта двухсобытийная модель дает вам задержку *и* вывод инструмента в вашей трассировке.

Анализ сбоев: еженедельный аудиторский воркфлоу

Логирование бесполезно без анализа. Вот легковесный процесс, который занимает 30–60 минут в неделю и ловит большинство проблем:

Шаг 1: Фильтрация ошибок (10 минут)

Запросите свои логи на все события, где status равен error, timeout или retry. Сгруппируйте по correlation_id, чтобы видеть полные неудачные задачи, а не отдельные сломанные события. Для каждой неудачной задачи:

1. Прочитайте поле error_detail, чтобы классифицировать сбой (ошибка провайдера, таймаут инструмента, контент-фильтр, переполнение контекста). 2. Проверьте input_summary спана сбоев, чтобы увидеть, что агент пытался сделать. 3. Решите: это системная проблема (воспроизводимая, требует исправления кода) или стохастическая проблема (разовая, просто залогируйте и двигайтесь дальше)?

Шаг 2: Просмотр выбросов стоимости (10 минут)

Отсортируйте все события task_complete по убыванию cost_usd. Любая задача, стоимость которой в 5 раз превышает медианную стоимость задачи, является кандидатом на расследование. Частые причины:

• Петли повторных попыток. Агент продолжал сбой при вызове инструмента и повторял попытки без отката.
• Разбухание окна контекста. Накопленная история диалога подталкивала количество токенов к максимуму на каждом ходе.
• Застревание в планировании. Агент продолжал генерировать планы, не действуя — частый режим сбоя в автономных воркфлоу.

Шаг 3: Выборочная проверка качества (20 минут)

Возьмите 3–5 случайных событий task_complete. Прочитайте output_summary (или полный вывод, если он сохранен). Спросите:

• Вывод фактически корректен?
• Он в правильном тоне и формате?
• Агент следовал инструкциям или отклонился от сценария?

Этот шаг ловит «технически успешные, но семантически неверные» выводы, которые коды ошибок никогда не пометят. Это самая времязатратная часть анализа — и самая ценная.

Шаг 4: Обновление ваших шаблонов промптов

Каждая классификация сбоя должна возвращаться в системный промпт агента или конфигурацию инструментов. Если вы видите три ошибки tool_timeout от одного внешнего API, либо увеличьте таймаут, добавьте фоллбэк, либо скажите агенту корректно обрабатывать сбой. Обсервабельность без итерации — просто накопление данных.

Аудиторские следы: комплаенс, подотчетность и доказательства

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

Минимальный аудиторский след ИИ-агента требует:

Инструменты: что вам действительно нужно (а что нет)

Вам не нужен Datadog. Вам даже не нужен Langfuse с первого дня. Вот поэтапный подход:

Уровень 0: Структурированные JSON-файлы + grep (с первого дня)

• Логируйте в /var/log/agents/{agent_name}/{date}.jsonl
• Анализируйте с помощью jq: jq 'select(.status == "error")' researcher/2026-07-09.jsonl
• Агрегируйте еженедельную стоимость: jq -s 'map(.cost_usd) | add' researcher/2026-07-*.jsonl

Этого достаточно для команды из 1–3 человек, выполняющей менее 50 задач в день.

Уровень 1: SQLite или DuckDB + простая панель мониторинга (вторая неделя)

• Загружайте JSONL в локальную базу данных с помощью ночного задания cron
• Создайте SQL-запросы для вашего еженедельного анализа (топ ошибок, выбросы стоимости, процентили задержки)
• Разверните базовую HTML-панель мониторинга с легковесным фреймворком (Streamlit, Evidence или даже статический сайт, генерируемый из запросов)

Уровень 2: Инструменты с открытым исходным кодом (второй месяц и далее)

• Langfuse — целенаправленно создан для LLM-обсервабельности; трассировки, отслеживание стоимости, версионирование промптов; возможен само-хостинг.
• Phoenix (Arize) — фокус на оценке и анализе эмбеддингов; полезно, если вам важны метрики качества вывода.
• Helicone — логирование через прокси; располагается между вашим кодом и LLM-провайдером; простое подключение.

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

Частые ошибки и как их избежать

Логирование только ошибок. Если вы захватываете только сбои, вы не можете рассчитать базовые показатели стоимости, процентили задержки или тренды качества. Логируйте каждое событие; фильтруйте на этапе запроса.

Хранение полных нагрузок в основном логе. Один ответ модели может быть 50 Кб. За неделю это быстро раздувается. Храните сводки в основном логе, полные нагрузки — в отдельном объектном хранилище или файле с ссылочным идентификатором.

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

Игнорирование стоимости до прихода счета. Рассчитывайте стоимость на событие, в реальном времени. Даже оценка с погрешностью ±20% бесконечно полезнее, чем месячный сюрприз.

Анализ логов без внесения изменений. Обсервабельность без действия — это просто наблюдение. Каждый цикл анализа должен производить хотя бы одно конкретное изменение: обновление промпта, корректировку таймаута, изменение политики повторных попыток или решение принять известное поведение как есть.

Чек-лист, который можно внедрить на этой неделе

1. Добавьте корреляционный идентификатор к каждому запуску задачи (UUID v4). 2. Оберните каждый вызов модели для логирования ts, correlation_id, model, tokens_in, tokens_out, latency_ms, cost_usd, status. 3. Оберните каждый вызов инструмента для логирования tool_name, input_summary, output_summary, latency_ms, error_detail. 4. Логируйте событие task_complete в конце каждого запуска с общей стоимостью, общим количеством токенов, финальным статусом и сводкой вывода. 5. Записывайте логи как JSONL в директорию, разделенную по датам. 6. Запланируйте 30-минутный еженедельный анализ в своем календаре. Используйте четырехшаговый воркфлоу выше. 7. Через один месяц оцените, достаточно ли болезнен ручной анализ, чтобы оправдать настройку Langfuse или панели мониторинга на базе данных.

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

Команды, которые само-хостят своих агентов — будь то через платформу вроде OfficeForge или кастомный стек — имеют здесь естественное преимущество: логи уже на их инфраструктуре, контекст выполнения локален, и между командой и доказательствами нет управляемого вендором абстрактного слоя. Какой бы подход вы ни выбрали, сделайте обсервабельность приоритетом с первого дня, а не мыслью, пришедшей после первого таинственного счета на $200.