Для агентных систем это особенно важно, потому что агент редко делает один вызов модели. Он может сначала классифицировать задачу, затем найти документы, вызвать CRM, проверить результат, попросить подтверждение у человека и только потом ответить. Без trace видно только финальный симптом: "ответ плохой". С trace можно открыть конкретный run и увидеть, на каком шаге все сломалось.
Хороший agent trace обычно строится как дерево или цепочка spans. Верхний уровень - один agent run с run_id. Внутри - model calls, RAG retrieval, tool calls, guardrails, handoff, retries, validation, финальный ответ и оценки качества. Каждый span содержит время начала и конца, вход, выход, статус, ошибку, версию промпта, модель, стоимость и технические метаданные.
Trace не должен превращаться в склад секретов и персональных данных. В production нужно маскировать токены, ключи, телефоны, платежные данные и лишние фрагменты документов. Часто используют sampling, разные уровни детализации для dev/staging/production, ограниченный срок хранения и доступ по ролям.
Agent trace связан с observability, evals и incident response. Из неудачного trace можно сделать тест-кейс, добавить его в dataset, исправить prompt, tool schema или RAG, а потом проверить, что регрессия больше не повторяется.
Примеры
- Пользователь спрашивает о статусе заказа. Trace показывает: агент распознал намерение, вызвал order_status_tool, получил ошибку 403, сделал fallback и передал обращение оператору.
- RAG-агент дал неверный ответ. В trace видно, что retriever нашел старую инструкцию, а новая версия документа не попала в индекс.
- ИИ-агент по продажам отправил странное письмо. Trace показывает, какая версия system prompt использовалась, какие поля CRM попали в контекст и какой tool подготовил черновик.
- После обновления модели выросла стоимость. Trace показывает, что агент стал делать больше retries и лишний раз вызывать поиск по базе знаний.
- Multi-agent система зависла. Run trace показывает, что supervisor несколько раз передавал задачу между двумя агентами без условия остановки.
- Guardrail отклонил действие. В trace видно, какой action candidate был предложен, какое правило сработало и почему требовалось human approval.
Где используется
- отладка плохих ответов AI-агента
- разбор ошибок RAG и retrieved chunks
- анализ tool calls, аргументов и результатов tools
- поиск причин высокой стоимости и долгой задержки
- сравнение версий prompts, моделей и workflow
- подготовка dataset для evals из реальных инцидентов
- incident response и расследование жалоб пользователей
- проверка guardrails, retries, fallback и human-in-the-loop
- наблюдаемость multi-agent систем и agent handoff
- контроль production-качества перед масштабированием агента
Связанные термины
Частые вопросы
Чем agent trace отличается от обычного лога?
Лог часто хранит отдельные события, а agent trace связывает их в путь одного запуска. По trace видно, какой запрос пришел, какие шаги сделал агент, какие tools вызвал, где возникла ошибка и какой ответ ушел пользователю.
Что обязательно писать в agent trace?
Минимум: run_id, user request, версии prompt и модели, model calls, tool calls, RAG retrieval, ошибки, retries, latency, cost, итоговый ответ и статус выполнения. Для production полезны scores, feedback и ссылка на пользователя или задачу без раскрытия лишних персональных данных.
Можно ли хранить в trace все промпты и документы?
Технически можно, но это рискованно. В trace могут попасть персональные данные, коммерческая тайна, API-ключи или внутренние инструкции. Лучше маскировать чувствительные поля, ограничивать доступ, задавать срок хранения и отдельно решать, какие данные нужны для диагностики.
Нужен ли agent trace маленькому проекту?
Да, хотя формат может быть простым. Даже таблица с run_id, steps, tool calls, ошибками и финальным ответом уже сильно помогает. Специализированные инструменты вроде Langfuse или LangSmith становятся особенно полезны, когда запусков много и нужна визуальная отладка.
Как trace помогает улучшать качество агента?
Trace показывает причину ошибки: плохой prompt, неправильный tool, слабый retrieval, лишний context, проблема модели или сбой интеграции. Такие случаи можно переносить в eval dataset и проверять после каждого изменения.
Что опасно в agent traces?
Главные риски - утечка секретов, персональных данных и внутренних инструкций, слишком долгий срок хранения, доступ без ролей и отсутствие маскирования. Trace должен помогать диагностике, но не становиться открытым архивом всего, что видел агент.
