Как настроить мониторинг ИИ-агента: traces, logs, metrics и качество

ИИ-агент в продакшене без мониторинга - это черный ящик. Пользователь получил странный ответ, CRM создала дубль, RAG нашел не ту статью, tool упал, стоимость выросла в два раза - а вы видите только “что-то пошло не так”. Мониторинг агента должен показывать не только ошибки сервера, но и цепочку рассуждения системы: input, retrieval, tools, answer, cost, latency, handoff и качество.

Короткая версия: добавьте run_id, traces, structured logs, метрики стоимости и задержки, логи tool calls, RAG diagnostics, quality dashboard, alerting и разбор неудачных сценариев. Без этого agentic production быстро превращается в гадание по жалобам пользователей.

Что мы собираем

Соберем контур наблюдаемости для ИИ-агента. Он подходит для RAG-чата, Telegram-бота, CRM-агента, multi-agent системы и внутреннего ассистента.

• Trace показывает путь одного agent run.
• Logs фиксируют события и ошибки.
• Metrics показывают тренды: latency, cost, error rate, handoff rate.
• RAG diagnostics показывает качество retrieval.
• Tool monitoring показывает внешние действия агента.
• Quality dashboard связывает пользовательские оценки, evals и реальные диалоги.
• Alerts сообщают о проблемах до того, как их заметят клиенты.

Шаг 1. Введите run_id

Каждый запуск агента должен иметь уникальный run_id. Это ниточка, по которой можно связать запрос пользователя, вызовы модели, найденные документы, tools, итоговый ответ и ошибку.

run_id = 2026-05-22T10:15:30Z_user42_a8f3

run_id должен попадать:

• в trace;
• в structured logs;
• в записи tool calls;
• в ошибки backend;
• в feedback пользователя;
• в audit log;
• в ticket или CRM note, если агент создает запись.

Без run_id вы будете искать проблему по времени, кускам текста и догадкам.

Шаг 2. Настройте traces

Trace показывает вложенные шаги одного запуска агента. Для LLM-приложений это важнее обычных текстовых логов, потому что агент делает несколько внутренних действий.

Хороший trace содержит:

• вход пользователя;
• системный промпт или его версию;
• выбранную модель;
• retrieval-запрос и найденные документы;
• tool calls и аргументы;
• результаты tools;
• финальный ответ;
• latency и стоимость каждого шага;
• ошибки и retry.

LangSmith и Langfuse дают специализированную LLM-наблюдаемость, а OpenTelemetry помогает встроить traces, logs и metrics в общую инфраструктуру.

Шаг 3. Пишите structured logs

Логи в стиле “агент что-то сделал” почти бесполезны. Используйте структурированные события с понятными полями.

{
  "event": "tool_call",
  "run_id": "run_123",
  "tool": "create_crm_lead",
  "status": "success",
  "latency_ms": 842,
  "user_id": "user_42",
  "prompt_version": "support_v7"
}

Structured logs проще фильтровать, агрегировать, связывать с traces и превращать в метрики.

Шаг 4. Не пишите секреты и лишние персональные данные

Наблюдаемость не должна становиться утечкой данных. В логах часто случайно оказываются телефоны, email, токены, документы, внутренние инструкции и tool payload.

• Маскируйте телефоны и email, если полный текст не нужен.
• Никогда не пишите API keys, OAuth tokens, webhook secrets.
• Сохраняйте ID документа вместо полного текста, если достаточно.
• Для debugging включайте полный payload временно и только в безопасном окружении.
• Ограничьте доступ к traces и logs по ролям.

Отдельно решите, сколько времени хранить production traces.

Шаг 5. Отслеживайте базовые метрики

Начните с небольшого набора метрик. Если сразу сделать 50 графиков, ими никто не будет пользоваться.

• Requests per hour/day.
• Success rate.
• Error rate.
• Average latency и p95 latency.
• Cost per run.
• Tokens per run.
• Tool call rate.
• Tool error rate.
• Handoff rate.
• User feedback score.

Для агента поддержки добавьте CSAT, FCR и долю автоматических ответов, которые не потребовали повторного обращения.

Шаг 6. Добавьте RAG diagnostics

Для RAG-агента важно понимать, проблема в модели или в поиске. Логируйте retrieval отдельно.

• query, который ушел в retriever;
• top_k документов;
• score каждого документа;
• source_id и updated_at;
• фильтры metadata;
• был ли использован источник в ответе;
• был ли ответ без источника;
• user feedback по полезности ответа.

Если агент ошибся, trace должен показать: он не нашел документ, нашел не тот документ или нашел правильный, но плохо сформулировал ответ.

Шаг 7. Отслеживайте tools

Tool monitoring нужен для безопасности и надежности. Агент может ошибиться в выборе tool, передать неверные аргументы или получить ошибку от внешнего API.

• tool name;
• allowed или blocked policy gate;
• аргументы после валидации;
• статус: success, failed, skipped, pending_approval;
• external request id;
• latency;
• retry count;
• idempotency key;
• human approval id, если был.

Для CRM, платежей, email и файлов это не просто monitoring, а часть audit trail.

Шаг 8. Отслеживайте стоимость

LLM-стоимость может расти незаметно: длинные prompts, большой RAG-контекст, слишком много retries, лишние QA-проверки или multi-agent циклы.

• Стоимость по модели.
• Стоимость по пользователю, команде или каналу.
• Стоимость по типу сценария.
• Среднее число model calls на run.
• Tokens input/output.
• Доля runs с превышением лимита.

Добавьте budget alerts: например, дневной лимит, резкий рост cost per run или слишком длинный контекст.

Шаг 9. Добавьте quality dashboard

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

• Like/dislike или оценка ответа.
• Handoff reason.
• Частые темы, где агент не помог.
• Доля ответов с источниками.
• Доля ответов “не нашел подтверждения”.
• Результаты evals по версиям промпта.
• Топ ошибок RAG и tools.

Хороший dashboard отвечает на вопрос: что улучшать на этой неделе?

Шаг 10. Настройте alerts

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

• Error rate выше нормы.
• p95 latency выше UX-лимита.
• Стоимость за день близка к лимиту.
• Tool failures выросли.
• Handoff rate резко вырос.
• RAG начал возвращать мало источников.
• Safety guardrail сработал много раз подряд.
• CRM/API integration недоступна.

Для не срочных трендов лучше делать ежедневный отчет, а не тревогу в мессенджер.

Шаг 11. Свяжите мониторинг с evals

Production traces - отличный источник для новых evals. Если агент ошибся в реальном диалоге, не ограничивайтесь ручной правкой промпта.

• Найдите trace ошибки.
• Определите тип: retrieval, tool, memory, policy, prompt, model.
• Добавьте пример в dataset.
• Исправьте причину.
• Прогоните regression evals.
• Сравните новую версию с прошлой.

Так мониторинг превращается в цикл улучшения, а не в архив красивых графиков.

Шаг 12. Настройте отчет для команды

Разным людям нужны разные данные. Разработчику нужен trace, руководителю поддержки - темы и CSAT, владельцу продукта - стоимость и конверсия.

• Разработчик: traces, errors, tool failures, latency.
• Редактор базы знаний: вопросы без источника, плохой retrieval, устаревшие статьи.
• Поддержка: handoff rate, SLA, CSAT, темы обращений.
• Бизнес: cost, автоматизация, конверсия, заявки, экономия времени.
• Безопасность: guardrails, blocked actions, PII events, risky tools.

Если все смотрят одну огромную панель, скорее всего ей никто не пользуется.

Мини-чеклист

• У каждого запуска агента есть run_id.
• Включены traces для LLM, RAG и tools.
• Логи структурированы.
• Секреты и PII маскируются.
• Отслеживаются latency, error rate, cost и token usage.
• RAG diagnostics показывает source_id, score и filters.
• Tool monitoring показывает status, latency, policy и approval.
• Есть quality dashboard.
• Alerts настроены на критичные отклонения.
• Ошибки из production попадают в eval dataset.

Частые вопросы

Чем monitoring ИИ-агента отличается от обычного backend monitoring?

Обычный monitoring показывает, жив ли сервер и есть ли ошибки. Для ИИ-агента нужно видеть внутренний путь: prompt, retrieval, tool calls, model calls, cost, safety checks и финальный ответ.

Нужно ли хранить все prompts и ответы?

Не всегда. Для отладки полезно хранить traces, но нужно учитывать персональные данные, коммерческую тайну и политику хранения. Часто используют маскирование, sampling и разные режимы для dev/staging/production.

Что выбрать: LangSmith или Langfuse?

LangSmith удобен в экосистеме LangChain/LangGraph и для evals. Langfuse - open-source LLM observability платформа с tracing, prompt management, datasets и dashboards. Выбор зависит от стека, бюджета и требований к self-hosting.

Какие метрики важнее всего в начале?

Latency, error rate, cost per run, tool failure rate, handoff rate, доля ответов с источниками и пользовательская оценка ответа. Этого достаточно, чтобы увидеть первые реальные проблемы.

Как понять, что мониторинг помогает?

Если по dashboard понятно, что чинить дальше: RAG, prompt, tool, memory, guardrails или документы. Если графики красивые, но решения не меняются, monitoring пока не работает.