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

Когда вы запускаете одного агента, отладка сводится к чтению логов. Когда агентов пять и они передают задачи друг другу, вызывают инструменты и спорят между собой, обычный лог превращается в стену текста, по которой невозможно понять, кто и почему принял решение. Отсюда — целый класс инструментов observability для LLM-приложений: LangSmith, Langfuse, Arize Phoenix, а также встроенная трассировка в OpenAI Agents SDK. Все они пытаются ответить на один вопрос: что именно происходило между агентами и где поток сломался.

Почему обычных логов недостаточно

Мультиагентный запуск — это дерево, а не строка. Оркестратор получает запрос, разбивает его на подзадачи, отдаёт их специализированным агентам, те дёргают инструменты (вызовы функций, поиск, код) и возвращают результаты обратно. На каждом шаге модель тратит токены, а значит — деньги и время.

В плоском логе вы видите последовательность строк, но теряете три вещи, критичные для отладки:

• Иерархию. Какой агент вызвал какого и кто вернул ответ, из-за которого всё пошло не так.
• Стоимость по шагам. Один агент может зациклиться и сжечь тысячи токенов, а в общем счёте это незаметно.
• Латентность. Где именно система ждала — на вызове модели, на внешнем API или на ретрае.

Визуализация решает это через понятие трейса: единая цепочка span-ов, где каждый span — это один шаг (вызов модели, инструмента, передача задачи). Span-ы вложены друг в друга, и вы видите дерево целиком.

Пока агентов один-два, вы держите поток в голове. На пятом агенте голова кончается — и начинается observability.

Что показывают инструменты трассировки

Стандарт де-факто здесь — OpenTelemetry с расширением для генеративного ИИ (semantic conventions для gen-ai). Большинство инструментов либо используют его напрямую, либо совместимы с ним. Это важно: если вы пишете трейсы в формате OpenTelemetry, вы не привязаны к одному вендору.

Типичный интерфейс трассировки даёт три представления одних и тех же данных:

1. Waterfall (водопад). Горизонтальные полосы во времени: видно, что выполнялось параллельно, а что последовательно, и где узкое место по латентности.
2. Дерево вызовов. Вложенная структура «агент → подагент → инструмент», удобная, чтобы понять логику передачи задач.
3. Граф. Узлы-агенты и рёбра-передачи задач. Полезен для оркестраторов, где один агент обращается к нескольким и обратно.

Сравнение инструментов

Ниже — четыре популярных варианта. Модель распространения и цены проверяйте на официальных страницах: у SaaS-продуктов тарифы меняются несколько раз в год.

Функциональность инструментов быстро меняется — перед выбором сверьтесь с документацией: то, что вчера было платной фичей, сегодня может стать бесплатным, и наоборот.

Open-source против SaaS

Если у вас чувствительные данные или требования по хранению внутри контура, self-host-варианты (Langfuse, Phoenix) закрывают этот вопрос: трейсы не уходят наружу. Плата за это — вы сами поднимаете и обслуживаете сервис. SaaS вроде LangSmith снимает эксплуатацию, но данные ваших промптов и ответов уходят на серверы вендора, что не всем подходит по compliance.

Как это выглядит в коде

Минимальный пример — трассировка через OpenTelemetry-совместимый декоратор Langfuse. Идея одна у всех: вы оборачиваете функции агентов, и вложенные вызовы сами выстраиваются в дерево.

from langfuse.decorators import observe

@observe()
def researcher(query: str) -> str:
    # вызов модели для сбора фактов
    return call_llm(f"Собери факты по теме: {query}")

@observe()
def writer(facts: str) -> str:
    return call_llm(f"Напиши черновик на основе: {facts}")

@observe()
def orchestrator(topic: str) -> str:
    facts = researcher(topic)   # вложенный span
    draft = writer(facts)       # вложенный span
    return draft

orchestrator("поток задач между агентами")

После запуска в дашборде появится трейс с корневым span-ом orchestrator и двумя вложенными — researcher и writer. Для каждого будут видны токены, латентность и вход-выход. Конкретный синтаксис декораторов и импортов сверяйте с актуальной документацией пакета: API этих библиотек меняется от версии к версии.

Кому это пригодится и кому нет

Пригодится, если:

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

Не пригодится, если:

• У вас один агент без ветвления и пары вызовов инструментов — тут хватит структурированного лога и вывода в консоль.
• Проект одноразовый, скрипт запускается раз и выбрасывается: настройка трассировки займёт больше времени, чем сэкономит.
• Данные настолько чувствительны, что даже self-host-трейс с промптами хранить нельзя — тогда логируйте только метаданные без содержимого сообщений.

С чего начать

1. Определитесь с ограничениями по данным: можно ли отправлять содержимое промптов наружу. Если нет — сразу смотрите на self-host.
2. Проверьте, пишет ли ваш фреймворк трейсы в OpenTelemetry. Если да — вы сможете сменить бэкенд без переписывания кода.
3. Подключите инструмент на одном сценарии, а не на всём приложении сразу. Убедитесь, что дерево span-ов собирается корректно.
4. Добавьте в трейсы стоимость и латентность как обязательные атрибуты — это то, ради чего всё и затевается.

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