Зачем агентам трассировка
Агенты выполняют несколько вызовов LLM и инструментов на один запрос — без трассировки вы работаете вслепую.
«Зачем агентам трассировка» — бесплатный урок AI Agents на CoddyKit. Это урок 1 из 4. Ты можешь прочитать весь урок бесплатно ниже — а потом практиковать его прямо в браузере с встроенным редактором кода и ИИ-репетитором 24/7. Это часть пути обучения AI Agents, и твой прогресс синхронизируется между веб-версией и приложением CoddyKit. Курс AI Agents содержит 4 уроков всего.
Части этого урока еще не переведены и отображаются на английском.
Агентов сложно отлаживать
Одно пользовательское сообщение может вызвать 10 вызовов LLM, 5 вызовов инструментов и задержку в 30 секунд. Когда что-то идёт не так, фраза «агент выдал странный ответ» ничего не объясняет.
Трассировка показывает, что произошло на самом деле.
Что фиксирует трассировка
Для одного пользовательского запроса:
- Каждый вызов LLM: модель, входящие сообщения, исходящий ответ, токены, задержка
- Каждый вызов инструмента: название, аргументы, результат, ошибка
- Порядок и время выполнения всех шагов
- Итоговый ответ, видимый пользователю
Одних журналов недостаточно
Обычные журналы (сообщения о выводе) теряют структуру трассировки — невозможно понять, какой вызов LLM относится к какому пользовательскому запросу и как шаги образуют дерево.
Инструменты структурированной трассировки решают эту проблему.
span и трассировка
Термины заимствованы из OpenTelemetry:
- Трассировка — весь запуск агента (один пользовательский запрос)
- span — один шаг внутри трассировки (вызов LLM, вызов инструмента, извлечение)
- У span есть родительские элементы — так формируется дерево
A Concrete Trace Tree
Trace: user asks 'What is our return policy?'
|-- Span: retrieve_docs (12 ms)
|-- Span: llm_call_planner (820 ms)
| |-- tool_call: search_kb
|-- Span: tool_call: search_kb (340 ms)
|-- Span: llm_call_synthesise (1100 ms)
Total: 2.3 s, 8400 tokens, $0.012Почему трассировка лучше журналов
- Древовидная структура показывает связи родительских и дочерних элементов
- Временная диаграмма показывает медленные шаги
- Токены и стоимость суммируются для каждой трассировки
- Повторное воспроизведение: запустите трассировку снова с новым запросом, чтобы проверить изменения
Когда добавлять трассировку
С первого дня. Трассировка во время разработки выявляет ошибки, которые вы не заметили бы при отладке только через чат. Добавлять её после инцидента в рабочей среде уже слишком поздно.
Конфиденциальность и трассировка
Трассировки содержат пользовательские данные. Обращайтесь с ними как с журналами:
- Маскируйте PII перед экспортом
- Шифруйте данные при хранении
- Соблюдайте правила хранения данных
Трассировка и оценивание
Трассировка — «что произошло в этом одном запуске». Оценивание — «насколько хорошо агент работает на тестовом наборе». Нужны оба подхода, но сначала трассировка — нельзя оценивать то, что нельзя проверить.
Стоимость трассировки
Трассировка добавляет 1–2% накладных расходов к задержке и увеличивает объём хранения. Для разговорчивых агентов используйте выборку (например, полностью сохраняйте 10% трассировок и 100% сбоев), а не записывайте всё.
Ручная и автоматическая инструментализация
Некоторые платформы (LangChain, LlamaIndex) автоматически выполняют инструментализацию — трассировки получаются без дополнительных усилий. В собственном коде оберните вызовы LLM и инструментов вспомогательными функциями span.
Идентификаторы трассировки в ошибках для пользователей
Когда агент завершается с ошибкой, верните пользователю идентификатор трассировки:
«Что-то пошло не так. Идентификатор обращения: trace-9c4a... Покажите его службе поддержки.»
Служба поддержки может открыть трассировку и точно увидеть, что произошло.
Зачем нужна трассировка?
Почему структурированная трассировка лучше обычных журналов вывода для агентов?
Итоги
Трассировка обязательна. Внедрите её с самого начала. В следующих уроках рассматриваются данные, которые нужно записывать, и инструменты, которые следует использовать.
Часто задаваемые вопросы
Урок «Зачем агентам трассировка» бесплатный?
Да — полный текст урока «Зачем агентам трассировка» бесплатно доступен здесь в веб-версии. Чтобы практиковать его интерактивно (встроенный редактор кода и ИИ-репетитор 24/7) и разблокировать остальной курс AI Agents, подпишись на CoddyKit PRO. Курс AI Agents содержит 4 уроков всего.
Чему я научусь в уроке «Зачем агентам трассировка»?
Агенты выполняют несколько вызовов LLM и инструментов на один запрос — без трассировки вы работаете вслепую. Ты практикуешь AI Agents с помощью реального кода, который запускаешь прямо в браузере, и ИИ-репетитор 24/7 отвечает на твои вопросы во время урока.
Нужен ли мне опыт, чтобы начать AI Agents?
Предыдущий опыт не требуется. AI Agents на CoddyKit структурирован для всех уровней — от новичков до продвинутых, поэтому ты можешь начать отсюда или с самого начала и учиться в своем темпе. Это урок 1 из 4.
Сколько времени занимает урок «Зачем агентам трассировка»?
Большинство уроков CoddyKit занимают около 5–10 минут. Каждый из них компактный и интерактивный, поэтому ты постоянно делаешь прогресс и продолжаешь с того же места в веб-версии и приложении.
Можно ли писать и запускать код в этом уроке AI Agents?
Да. Каждый урок AI Agents включает встроенный редактор кода, поэтому ты пишешь и запускаешь реальный код прямо в браузере и получаешь моментальную обратную связь от AI — локальная установка не требуется.
Все уроки этого курса
- Зачем агентам трассировка
- Журналирование вызовов инструментов и входов/выходов
- Задержка и стоимость каждого шага
- Визуализация запусков агентов (Langfuse, LangSmith)