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

Что получится в результате

Соберем мониторинг ИИ-агента, который показывает не только "сервер жив" и "ошибка 500", а весь путь задачи: пользовательский запрос, выбранная модель, prompt, RAG-поиск, tool calls, approvals, retries, fallback, стоимость, задержку, safety flags, финальный ответ и оценку качества. Такой мониторинг нужен, чтобы понять, где агент ломается: в prompt, retrieval, модели, инструменте, данных, лимитах, правах или пользовательском сценарии.

В результате будет рабочий MVP:

1. каждый запуск агента получает `run_id`;
2. сессии пользователя пишутся в `agent_sessions`;
3. запуски задач лежат в `agent_runs`;
4. шаги агента пишутся в `agent_steps`;
5. model calls сохраняются в `model_call_log`;
6. tool calls сохраняются в `tool_call_log`;
7. RAG-поиск фиксируется в `retrieval_log`;
8. prompts и версии prompts лежат в `prompt_log`;
9. structured output проверяется в `schema_validation_log`;
10. задержки пишутся в `latency_log`;
11. стоимость пишется в `cost_log`;
12. ошибки и retries пишутся в `error_log`;
13. fallback-события пишутся в `fallback_log`;
14. safety-события пишутся в `safety_event_log`;
15. handoff человеку пишется в `handoff_log`;
16. оценки качества пишутся в `quality_score_log`;
17. пользовательская обратная связь лежит в `feedback_log`;
18. алерты лежат в `alert_rules`;
19. срабатывания алертов пишутся в `alert_events`;
20. все важные действия фиксируются в `audit_log`.

Первая версия должна отвечать на пять вопросов: что пользователь попросил, какие данные агент использовал, какие tools вызвал, сколько это стоило, почему ответ получился именно таким и где он сломался, если сломался.

Что понадобится

Минимальный набор:

1. работающий ИИ-агент или тестовый workflow;
2. backend, где можно добавить `run_id`;
3. база данных для логов: PostgreSQL, MySQL или ClickHouse;
4. LLM observability инструмент: Langfuse, LangSmith или свой trace viewer;
5. OpenTelemetry для связки с backend traces;
6. Prometheus или аналог для метрик;
7. Grafana или аналог для dashboards;
8. Sentry или аналог для exceptions;
9. список критичных сценариев агента;
10. лимиты стоимости и задержки;
11. человек, который будет разбирать алерты.

Для первого запуска достаточно одной таблицы логов `agent_runs`, одной таблицы `model_call_log`, одной `tool_call_log` и простого dashboard по latency, cost, errors и fallback rate.

Шаг 1. Определите, что именно мониторим

Обычный backend monitoring не видит агентную логику. Нужно мониторить весь цикл.

События:

1. пользователь начал задачу;
2. агент выбрал сценарий;
3. агент выбрал модель;
4. prompt собран;
5. retrieval выполнен;
6. tool вызван;
7. tool вернул ошибку;
8. модель вернула structured output;
9. JSON прошел или не прошел validation;
10. действие ушло на approval;
11. сработал fallback;
12. задача передана человеку;
13. ответ отправлен пользователю;
14. пользователь поставил оценку;
15. задача завершилась ошибкой.

Проверка: по одному `run_id` можно увидеть все события цепочки.

Шаг 2. Создайте `agent_sessions`

Сессия связывает несколько запусков одного пользователя.

Колонки:

id
session_id
user_id
channel
started_at
last_seen_at
status
metadata_json

`channel`:

1. `web`;
2. `telegram`;
3. `whatsapp`;
4. `email`;
5. `slack`;
6. `api`;
7. `admin`.

Проверка: несколько вопросов пользователя в одном чате связаны одной `session_id`.

Шаг 3. Создайте `agent_runs`

`agent_runs` - главная таблица мониторинга.

Колонки:

id
run_id
session_id
user_id
agent_name
task_type
input_hash
status
started_at
finished_at
total_latency_ms
total_cost
model_route
fallback_used
human_handoff
quality_score

Статусы:

1. `started`;
2. `running`;
3. `waiting_tool`;
4. `waiting_approval`;
5. `completed`;
6. `failed`;
7. `cancelled`;
8. `handoff`.

Проверка: каждый запрос пользователя создает ровно один `agent_runs.run_id`.

Шаг 4. Добавьте `run_id` во все логи

Без общего id расследование превращается в ручной поиск.

Передавайте `run_id` в:

1. model calls;
2. tool calls;
3. retrieval;
4. structured logs;
5. queue jobs;
6. HTTP requests;
7. approval records;
8. error logs;
9. audit events;
10. alerts.

Проверка: если tool упал, в ошибке есть тот же `run_id`, что и в пользовательском запросе.

Шаг 5. Создайте `agent_steps`

Шаги показывают внутренний план агента.

Колонки:

id
run_id
step_index
step_type
step_name
status
started_at
finished_at
latency_ms
summary

`step_type`:

1. `intent_detection`;
2. `retrieval`;
3. `model_call`;
4. `tool_call`;
5. `validation`;
6. `approval`;
7. `fallback`;
8. `final_answer`;
9. `handoff`.

Проверка: в trace видно, что агент сначала сделал retrieval, потом вызвал tool, потом сформировал ответ.

Шаг 6. Логируйте model calls

Создайте `model_call_log`.

Колонки:

id
run_id
step_id
provider
model_id
prompt_version
input_tokens
output_tokens
cached_tokens
temperature
status
latency_ms
estimated_cost
finish_reason
created_at

Не храните полный prompt с персональными данными в открытом виде. Для sensitive-полей храните hash, summary и ссылку на безопасное хранилище.

Проверка: по каждому run видно, какая модель отвечала, сколько токенов потрачено и сколько это стоило.

Шаг 7. Логируйте prompts

Создайте `prompt_log`.

Колонки:

id
run_id
prompt_version
prompt_role
prompt_hash
prompt_summary
contains_pii
storage_ref
created_at

Логируйте отдельно:

1. system prompt;
2. developer prompt;
3. user input summary;
4. retrieved context summary;
5. tool result summary;
6. final answer prompt.

Проверка: можно сравнить, какой prompt version дал плохой ответ.

Шаг 8. Логируйте retrieval

Создайте `retrieval_log`.

Колонки:

id
run_id
query
collection_name
top_k
filters_json
chunk_id
score
document_id
source_ref
used_in_answer
created_at

Проверяйте:

1. был ли retrieval;
2. какой запрос ушел в поиск;
3. какие фильтры применились;
4. какие chunks пришли;
5. какой score;
6. использовались ли chunks в ответе;
7. были ли документы недоступны пользователю.

Проверка: плохой ответ можно объяснить: retrieval не нашел нужный chunk или модель проигнорировала найденный chunk.

Шаг 9. Логируйте tool calls

Создайте `tool_call_log`.

Колонки:

id
run_id
step_id
tool_name
tool_action
arguments_hash
arguments_summary
status
latency_ms
external_request_id
error_code
error_message
requires_approval
created_at

Логируйте:

1. какой tool выбран;
2. какие аргументы переданы;
3. прошла ли schema validation;
4. был ли approval;
5. что вернул внешний API;
6. была ли повторная попытка;
7. было ли опасное действие заблокировано.

Проверка: если агент создал дубль в CRM, видно, какой tool и с какими аргументами это сделал.

Шаг 10. Логируйте structured output

Создайте `schema_validation_log`.

Колонки:

id
run_id
model_call_id
schema_name
is_valid
errors_json
raw_output_hash
created_at

Проверяйте:

1. валидный JSON;
2. обязательные поля;
3. enum values;
4. типы данных;
5. лишние поля;
6. пустые значения;
7. risk level;
8. action name.

Проверка: invalid JSON не идет в tool call, а создает retry или handoff.

Шаг 11. Считайте latency

Создайте `latency_log`.

Колонки:

id
run_id
component
operation
latency_ms
status
created_at

Компоненты:

1. `frontend`;
2. `backend`;
3. `queue`;
4. `model`;
5. `retrieval`;
6. `tool`;
7. `approval`;
8. `fallback`;
9. `final_answer`.

Считайте p50, p90, p95 и p99. Среднее значение почти всегда прячет проблемы.

Проверка: dashboard показывает, где агент тормозит: модель, база, tool или очередь.

Шаг 12. Считайте стоимость

Создайте `cost_log`.

Колонки:

id
run_id
provider
model_id
cost_type
input_tokens
output_tokens
cached_tokens
estimated_cost
created_at

`cost_type`:

1. `model_input`;
2. `model_output`;
3. `embeddings`;
4. `reranking`;
5. `speech`;
6. `vision`;
7. `tool_api`;
8. `storage`.

Проверка: можно увидеть стоимость одного run, одного пользователя, одного агента и одного сценария.

Шаг 13. Логируйте ошибки

Создайте `error_log`.

Колонки:

id
run_id
component
operation
error_code
error_message
retryable
attempt
payload_hash
created_at

Типовые ошибки:

1. timeout модели;
2. rate limit;
3. invalid JSON;
4. context overflow;
5. tool API 500;
6. tool API 403;
7. retrieval empty;
8. approval rejected;
9. missing credentials;
10. safety block.

Проверка: ошибка не теряется в логах сервера, а связана с конкретным run.

Шаг 14. Логируйте fallback

Создайте `fallback_log`.

Колонки:

id
run_id
from_model
to_model
reason
attempt
success
created_at

Причины:

1. `timeout`;
2. `rate_limit`;
3. `invalid_json`;
4. `low_confidence`;
5. `safety_uncertain`;
6. `provider_error`;
7. `context_overflow`;
8. `tool_loop`.

Проверка: если fallback rate растет, видно, какая модель или какой сценарий деградирует.

Шаг 15. Логируйте safety events

Создайте `safety_event_log`.

Колонки:

id
run_id
event_type
severity
source
message
action_taken
created_at

События:

1. prompt injection;
2. попытка раскрыть system prompt;
3. запрещенный tool call;
4. PII leak risk;
5. dangerous action;
6. answer without evidence;
7. policy violation;
8. jailbreak attempt;
9. suspicious file content;
10. approval bypass attempt.

Проверка: опасный пользовательский ввод виден отдельно от обычных ошибок.

Шаг 16. Логируйте handoff человеку

Создайте `handoff_log`.

Колонки:

id
run_id
handoff_reason
assigned_to
priority
context_summary
status
created_at
resolved_at

Причины handoff:

1. низкая confidence;
2. высокорисковое действие;
3. нет данных;
4. конфликт источников;
5. tool error;
6. пользователь недоволен;
7. safety flag;
8. approval нужен;
9. модель не прошла schema validation;
10. требуется эксперт.

Проверка: оператор получает не просто "помоги", а summary, run_id и причину передачи.

Шаг 17. Добавьте feedback

Создайте `feedback_log`.

Колонки:

id
run_id
user_id
rating
feedback_type
comment
correct_answer
created_at

`feedback_type`:

1. `helpful`;
2. `wrong_answer`;
3. `too_slow`;
4. `unsafe`;
5. `missing_context`;
6. `bad_tone`;
7. `tool_error`;
8. `needs_human`.

Проверка: плохие оценки попадают в список кандидатов для eval cases.

Шаг 18. Считайте quality score

Создайте `quality_score_log`.

Колонки:

id
run_id
score_name
score_value
evaluator
reason
created_at

Оценивайте:

1. answer helpfulness;
2. factuality;
3. citation coverage;
4. tool correctness;
5. schema validity;
6. safety;
7. tone;
8. task completion;
9. human correction needed;
10. user satisfaction.

Проверка: качество агента можно сравнивать по неделям и после изменений prompt.

Шаг 19. Свяжите monitoring с evals

Мониторинг должен превращаться в тесты.

Workflow:

1. плохой run попадает в `feedback_log`;
2. run отмечается как candidate для eval;
3. из input и expected behavior создается eval case;
4. eval прогоняется на новой версии prompt или модели;
5. если регрессии нет, изменение выкатывается;
6. после выката мониторинг проверяет те же метрики.

Проверка: повторяющаяся ошибка становится тестом, а не вечной ручной правкой.

Шаг 20. Создайте `alert_rules`

Алерты должны быть по делу, иначе их перестанут читать.

Колонки:

id
rule_code
metric_name
condition
threshold
window_minutes
severity
channel
is_active

Первые правила:

agent_error_rate_high | error_rate | > | 5% | 15 | high | telegram
fallback_rate_high | fallback_rate | > | 15% | 30 | medium | telegram
cost_spike | cost_per_hour | > | budget*1.5 | 60 | high | email
latency_p95_high | latency_p95 | > | 12000 | 15 | medium | telegram
invalid_json_high | invalid_json_rate | > | 3% | 30 | medium | telegram
safety_events_high | safety_event_count | > | 10 | 15 | high | telegram

Проверка: тестовое превышение threshold создает запись в `alert_events`.

Шаг 21. Создайте `alert_events`

Колонки:

id
rule_id
metric_value
threshold
severity
status
message
created_at
acknowledged_by
resolved_at

Статусы:

1. `open`;
2. `acknowledged`;
3. `resolved`;
4. `muted`;
5. `false_positive`.

Проверка: алерт можно подтвердить, закрыть и связать с incident или задачей.

Шаг 22. Соберите dashboard для владельца продукта

Первый dashboard должен быть понятен не только разработчику.

Блоки:

1. количество runs;
2. completion rate;
3. error rate;
4. handoff rate;
5. fallback rate;
6. средняя оценка пользователей;
7. стоимость за день;
8. стоимость на 1000 задач;
9. p95 latency;
10. топ-5 плохих сценариев.

Проверка: владелец продукта видит, улучшился агент или ухудшился.

Шаг 23. Соберите dashboard для инженера

Инженерный dashboard должен быстро вести к причине.

Блоки:

1. model error rate;
2. tool error rate;
3. invalid JSON rate;
4. retrieval empty rate;
5. rate limit;
6. timeout;
7. queue delay;
8. provider latency;
9. fallback reasons;
10. trace explorer по `run_id`.

Проверка: по алерту можно за 2-3 клика открыть конкретные traces.

Шаг 24. Соберите dashboard для безопасности

Для агентных систем safety dashboard обязателен.

Блоки:

1. prompt injection attempts;
2. blocked tool calls;
3. approval bypass attempts;
4. PII leak risks;
5. external send attempts;
6. policy violations;
7. suspicious files;
8. high-risk actions;
9. human review queue;
10. repeated offenders by user or source.

Проверка: safety events не смешаны с обычными backend errors.

Шаг 25. Настройте trace viewer

Trace должен показывать дерево выполнения.

Минимальная структура:

run
  intent_detection
  retrieval
    vector_search
    rerank
  model_call
  tool_call
    external_api
  validation
  final_answer

В каждом span храните:

1. start time;
2. end time;
3. status;
4. input summary;
5. output summary;
6. latency;
7. cost;
8. errors;
9. links to logs.

Проверка: trace одного плохого ответа показывает, какой шаг дал сбой.

Шаг 26. Подключите OpenTelemetry

OpenTelemetry связывает AI traces с обычным backend.

Добавьте span attributes:

ai.run_id
ai.agent_name
ai.task_type
ai.model_id
ai.provider
ai.tool_name
ai.cost
ai.input_tokens
ai.output_tokens
ai.safety_flag

Проверка: в общем trace видно HTTP request, queue job, model call и tool call.

Шаг 27. Подключите LLM observability платформу

Для MVP можно выбрать Langfuse или LangSmith.

Что отправлять:

1. trace id;
2. run id;
3. prompt version;
4. model id;
5. input/output summary;
6. token usage;
7. tool calls;
8. retrieval context;
9. scores;
10. user feedback.

Проверка: из платформы можно открыть конкретный run и увидеть prompt, retrieval и tool sequence.

Шаг 28. Настройте хранение персональных данных

Мониторинг не должен становиться утечкой.

Правила:

1. маскируйте email, телефон, паспорт, токены;
2. храните полный prompt только в защищенном storage;
3. в dashboard показывайте summary;
4. ограничьте доступ к traces;
5. задайте TTL для raw logs;
6. не пишите API keys;
7. не логируйте полные документы без причины;
8. разделите dev и production.

Проверка: в обычном dashboard нет сырых персональных данных.

Шаг 29. Настройте retention

Не храните все вечно.

Стартовые сроки:

1. raw prompts: 7-30 дней;
2. prompt hashes: 180 дней;
3. cost logs: 365 дней;
4. latency metrics: 365 дней;
5. audit log: по требованиям бизнеса;
6. safety events: 365 дней;
7. feedback: 365 дней;
8. traces with PII: минимально возможный срок.

Проверка: cron или job удаляет старые raw logs, но оставляет агрегаты.

Шаг 30. Проверьте мониторинг на тестовом сбое

Сымитируйте проблемы:

1. модель вернула invalid JSON;
2. tool API вернул 500;
3. retrieval ничего не нашел;
4. пользователь сделал prompt injection;
5. провайдер дал rate limit;
6. cost вырос в 2 раза;
7. p95 latency превысил лимит;
8. approval отклонили.

Проверка: каждая проблема видна в логах, dashboard и alert events.

Шаг 31. Настройте incident workflow

Если мониторинг нашел проблему, нужен порядок действий.

Workflow:

1. alert создает incident;
2. ответственный открывает trace;
3. определяет компонент;
4. ставит статус;
5. применяет mitigation;
6. добавляет run в eval dataset;
7. закрывает incident;
8. пишет короткий вывод.

Проверка: после инцидента остается не только закрытый alert, но и тест против повторения.

Шаг 32. Минимальный результат для запуска

MVP мониторинга готов, если выполнены условия:

1. у каждого запроса есть `run_id`;
2. есть `agent_runs`;
3. есть `model_call_log`;
4. есть `tool_call_log`;
5. есть `retrieval_log`;
6. есть `latency_log`;
7. есть `cost_log`;
8. есть `error_log`;
9. есть `safety_event_log`;
10. есть `feedback_log`;
11. настроены alerts по error rate, cost, latency и safety;
12. есть dashboard для продукта и инженера;
13. плохой run можно превратить в eval case;
14. сырые персональные данные не светятся в dashboard.

Проверка результата: возьмите любой плохой ответ пользователя и за минуту восстановите путь: input, prompt version, model, retrieval, tools, errors, cost, latency и final answer.

Что нельзя автоматизировать в первой версии

В первой версии не автоматизируйте:

1. автозакрытие safety incidents;
2. автоматическое повышение лимитов стоимости;
3. автоматическую замену модели без evals;
4. удаление логов без retention policy;
5. отправку raw prompts всем разработчикам;
6. игнорирование human feedback;
7. скрытие fallback от владельца продукта;
8. массовую запись персональных данных в dashboard;
9. алерты без ответственного;
10. action tools без audit log;
11. production-запуск без trace по `run_id`;
12. обновление prompt без сравнения метрик;
13. работу без error budget;
14. хранение API keys в логах;
15. оценку качества только по "ответ выглядит нормально".

Сначала добейтесь прозрачности одного агента, потом переносите схему мониторинга на остальные.

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

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

Обычный мониторинг показывает HTTP errors, CPU, память и время ответа. Мониторинг ИИ-агента должен дополнительно показывать prompt, model calls, retrieval, tool calls, cost, safety flags, fallback, handoff и качество ответа.

Нужно ли хранить полный prompt?

Не всегда. Для отладки полезно хранить полный prompt в защищенном storage с ограниченным доступом и TTL. В обычных таблицах и dashboard лучше хранить hash, summary и признаки PII.

Какие метрики самые важные на старте?

Минимум: completion rate, error rate, p95 latency, cost per run, fallback rate, invalid JSON rate, tool error rate, retrieval empty rate, safety events и user feedback.

Что делать с плохими ответами пользователей?

Сохраняйте `run_id`, feedback, правильный ответ и причину ошибки. Потом превращайте такие случаи в eval cases, чтобы новая модель или prompt не повторяли ту же ошибку.

Langfuse, LangSmith или свой мониторинг?

Для быстрого старта удобны Langfuse или LangSmith: traces, prompts, datasets, evals и dashboards уже готовы. Свой мониторинг имеет смысл, если есть строгие требования к данным, self-hosting или нужно глубоко связать AI traces с внутренней инфраструктурой.