Отладка AI-агентов: почему трассировка (traces) — это новый код

Старый мир умер. А вы этого не заметили?

Представьте классическую отладку: вы ставите брейкпоинт, смотрите на стек вызовов, проверяете переменные. Все детерминировано. Вы всегда знаете, что произойдет. Потом вы запускаете AI-агента.

И все ломается.

Сегодня, 01.02.2026, мы живем в мире, где код — это только часть уравнения. Где модель GPT-4.5-Turbo-2026 может дать три разных ответа на один промпт. Где агент на основе Claude-3.7-Sonnet решает вызвать внешний API вместо того, чтобы выполнить локальную функцию. Где ваша система — это не код, а диалог между десятками компонентов, каждый из которых сам по себе — черный ящик.

Почему print() больше не работает

Вспомните свой первый баг в AI-агенте. Вы написали промпт, запустили. Агент сделал что-то странное. Вы добавили print() для отладки. Запустили снова.

И получили другой результат.

Потому что AI-агенты — недетерминированные системы. Каждый запуск — это не выполнение кода, а разговор с вероятностной моделью. Температура, семплирование, контекстное окно — все это влияет на результат. И самое главное: агент принимает решения в реальном времени, основываясь на том, что он «видит» прямо сейчас.

Трассировка — это новый стек вызовов

Когда агент работает, он оставляет следы. Каждый вызов модели, каждый вызов инструмента, каждый шаг reasoning — все это записывается в трассировку (trace). И вот ключевой момент:

Трассировка — это не логи. Это не журнал событий. Это полная реконструкция процесса мышления агента.

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

1 Что реально происходит внутри агента

Возьмем простой пример. Агент должен ответить на вопрос пользователя о погоде. В коде это выглядит просто:

@tool
def get_weather(city: str) -> str:
    """Get current weather for a city"""
    # ... API call

agent = create_agent(
    tools=[get_weather],
    llm=GPT_4_5_TURBO_2026  # актуальная на 01.02.2026
)

Но в трассировке вы видите совсем другую картину:

• Агент получил промпт: "Какая погода в Москве?"
• Модель сгенерировала reasoning: "Пользователь спрашивает про погоду. Нужно определить город. Москва — это город в России. У меня есть инструмент get_weather. Нужно вызвать его с параметром city='Moscow'."
• Но затем модель добавила: "Хотя пользователь написал 'Москве' в предложном падеже. В инструменте ожидается именительный падеж. Нужно нормализовать: 'Москва'."
• Вызов инструмента get_weather('Moscow')
• Инструмент вернул ошибку: "City 'Moscow' not found"
• Агент задумался: "Инструмент не нашел город. Возможно, нужно использовать русское название. Попробую 'Moskva'."
• Второй вызов get_weather('Moskva') — успех

Вот этот внутренний диалог — reasoning, принятие решений, обработка ошибок — это и есть реальный «код» агента. Но его нет в ваших файлах .py. Он рождается и умирает в рантайме.

Как отлаживать через трассировку: практика 2026

Хватит теории. Давайте к практике. Сегодня, в 2026 году, у нас есть инструменты, которые делают трассировку основным инструментом отладки.

2 Настройка LangSmith для production-отладки

LangSmith от создателей LangChain — это de facto стандарт для трассировки AI-агентов в 2026. Не просто потому что модно, а потому что это работает.

Базовый пример настройки:

import os
from langsmith import Client
from langchain_openai import ChatOpenAI
from langchain.agents import AgentExecutor, create_openai_tools_agent

# Настройка трассировки — одна строка
os.environ["LANGCHAIN_TRACING_V2"] = "true"
os.environ["LANGCHAIN_PROJECT"] = "weather-agent"

# Ваш агент как обычно
llm = ChatOpenAI(
    model="gpt-4.5-turbo-2026",  # актуальная версия на 01.02.2026
    temperature=0.3
)
# ... создание агента

# При запуске автоматически создается трассировка
result = agent_executor.invoke({"input": "Какая погода в Москве?"})

Теперь зайдите в LangSmith UI. Вы увидите не просто «агент выполнился», а полное дерево выполнения:

• Корневой спан (span) — весь вызов агента
• Дочерние спаны — каждый шаг reasoning модели
• Листья — вызовы инструментов, промпты, ответы
• Тайминги каждого шага
• Токены, затраты (особенно важно с дорогими моделями 2026 года)

3 Находим реальные баги через трассировку

Вот типичные сценарии, где трассировка спасает:

Сценарий 1: Агент зацикливается

В коде все выглядит нормально. Но пользователи жалуются, что агент «зависает». Открываете трассировку и видите:

• Шаг 1: Агент вызывает инструмент поиска
• Шаг 2: Получает 10 результатов
• Шаг 3: Думает: «Это слишком много информации. Нужно уточнить запрос»
• Шаг 4: Вызывает инструмент поиска с уточненным запросом
• Шаг 5: Получает другие 10 результатов
• Шаг 6: Думает: «Все еще много. Нужно еще уточнить»
• ... и так 15 раз, пока не кончится контекстное окно

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

Сценарий 2: Агент выбирает не тот инструмент

У вас есть два инструмента: calculate_tax (считает налог) и calculate_discount (считает скидку). Пользователь спрашивает: «Сколько будет 1000 минус 20%?»

Агент вызывает calculate_tax. Почему? Трассировка показывает:

• Модель reasoning: «Пользователь спрашивает про вычитание процента. Это похоже на налоговый расчет. Вызову calculate_tax»
• Проблема: в описании инструмента calculate_tax сказано «Calculate tax amount», а calculate_discount — «Calculate price after discount». Модель перевела «минус 20%» как «налог», а не «скидка».

Решение: переписать описание инструмента calculate_discount как «Calculate percentage reduction, including discounts, tax deductions, or any 'minus X%' operation».

Трассировка в масштабе: когда агентов тысячи

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

Здесь помогает статья LangSmith Insights Agent: как отлаживать AI-агентов, когда их тысячи. Ключевые идеи:

• Автоматическая категоризация ошибок: LangSmith группирует похожие сбои. Вместо 1000 отдельных ошибок вы видите 5 паттернов.
• Поиск по трассировкам: «Показать все трассировки, где агент вызывал инструмент X больше 3 раз»
• Сравнение версий: Запустили новую версию промпта? Сравните трассировки старой и новой версий, чтобы увидеть, что реально изменилось в поведении.

Но LangSmith — не единственный игрок. В статье Как настроить observability для LLM-агентов с Langfuse показан альтернативный стек, особенно полезный для self-hosted решений.

Что записывать в трассировку? Полный чеклист

Не все данные одинаково полезны. Вот что обязательно нужно включать в трассировку в 2026:

Ошибки, которые все еще совершают в 2026

Даже с современными инструментами разработчики AI-агентов повторяют одни и те же ошибки:

Ошибка 1: Трассировка только в development

«В продакшене и так все работает». Знакомо? Пока не столкнетесь с багом, который проявляется только под нагрузкой, с реальными пользователями, с реальными данными. Трассировка в production — не опция, а необходимость.

Ошибка 2: Забывают про семплирование

Трассировать 100% трафика — дорого и бессмысленно. 1-5% достаточно для отладки. Но семплирование должно быть умным: обязательно трассировать ошибки, подозрительно долгие вызовы, первые запросы после деплоя новой версии.

Ошибка 3: Не используют трассировку для A/B тестов

Запустили новую версию промпта? Не смотрите только на агрегированные метрики. Сравните трассировки старой и новой версий. Увидите, как изменилось поведение агента на реальных примерах.

Ошибка 4: Игнорируют безопасность

Трассировки содержат промпты пользователей, которые могут включать PII данные. Нужно маскировать или хэшировать чувствительную информацию. Подробнее в статье Безопасность AI-агентов: защита данных от утечек.

Будущее уже здесь: автоотладка агентов

Самый интересный тренд 2026 года — автономная отладка. Представьте:

• Агент работает в продакшене
• Система трассировки обнаруживает аномалию: агент стал в 3 раза чаще вызывать определенный инструмент
• Другой AI-агент (debugging agent) анализирует трассировки, находит паттерн
• Предлагает исправление: «Похоже, инструмент X стал возвращать ошибки. Нужно добавить retry логику или fallback»
• Или даже: «В 40% случаев агент неправильно интерпретирует запросы про налоги. Нужно добавить few-shot пример в системный промпт»

Это не фантастика. Такие системы уже появляются. Например, Insights Agent в LangSmith или кастомные решения на основе анализа трассировок.

Что делать прямо сейчас

Если вы дочитали до этого места, у вас два варианта:

Вариант 1 (плохой): Продолжать отлаживать AI-агентов как обычный код. Ставить print(), гадать, почему вчера работало, а сегодня нет. Тратить дни на поиск багов, которые видны за 5 минут в трассировке.

Вариант 2 (правильный):

1. Подключите трассировку к своему агенту. Сегодня. Даже если это development. LangSmith, Langfuse, что угодно.
2. Запустите 10 типичных сценариев. Посмотрите на трассировки. Увидите свой агент «изнутри» впервые.
3. Настройте семплирование для production. Хотя бы 1% трафика.
4. Создайте дашборд с ключевыми метриками из трассировок: среднее время выполнения, процент успешных выполнений, самые частые инструменты.
5. Назначьте ответственного за анализ трассировок. Это новая роль в команде.

И помните: в 2026 году код AI-агента — это не только Python-файлы в вашем репозитории. Это еще и тысячи трассировок, которые показывают, как агент реально работает, думает, ошибается и учится.

Трассировка — это не просто инструмент отладки. Это окно в сознание вашего агента. И если вы до сих пор не заглянули в это окно, вы управляете слепым.