Отладка кодинг-агентов с LangSmith: как найти ошибку за минуту

Андрей Отинов -

В команде разработки вы запускаете кодинг‑агент, который генерирует CSV‑экспорт для отчётного эндпоинта.
Но он создаёт неверный результат: вместо пагинации по курсору использует устаревший метод offset. Вы исправляете инструкции, запускаете снова, но агент всё равно выдаёт ошибку. В итоге тратится время, токены и вы ничего не понимаете из того, что выводится в терминале.

Источник: langchain.com

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

Что проверить сейчас?
Откройте трассировку в LangSmith, найдите вызов подагента и убедитесь, что он использует правильный метод пагинации.

Что такое трассировка кода и зачем она нужна

Трассировка – это запись всех шагов, которые выполняет кодинг‑агент: запросы к модели, вызовы инструментов, команды оболочки, ошибки и время выполнения.
Когда вы видите эти данные в одном месте, вы можете быстро понять, где возникла ошибка, а не гадать по финальному дельту. Это экономит время и токены, а также позволяет фиксировать ошибки для будущих запусков.

Как включить трассировку в LangSmith

  1. Установите SDK LangSmith
    bash pip install langsmith
  2. Инициализируйте клиент
    python from langsmith import LangSmith client = LangSmith(api_key="YOUR_API_KEY")
  3. Оберните ваш кодинг‑агент
    python from langsmith import trace @trace def my_agent(...): ...
  4. Настройте переменные окружения
    bash export LANGSMITH_API_KEY=YOUR_API_KEY
  5. Запустите агент – все шаги автоматически попадают в LangSmith как «трассы».
Важно: LangSmith поддерживает трассировку для Claude Code, Codex, Cursor, GitHub Copilot Chat, Pi, OpenCode и DeepAgents Code. Если ваш агент не в списке, проверьте официальную документацию: Документация LangSmith по интеграции кодинг‑агентов.

Как читать и анализировать трассы

  1. Фильтруйте по thread_id – это покажет весь поток работы в порядке.
  2. Разберите последовательность
  3. Запрос пользователя
  4. Ответ ассистента
  5. Вызовы модели
  6. Вызовы инструментов (например, curl, git)
  7. Подагенты и их результаты
  8. Ошибки и повторные попытки
  9. Время и токены
  10. Ищите «плохие» места – например, вызов устаревшего метода пагинации.
  11. Сравните несколько сессий – если вы видите, что одна сессия завершилась ошибкой, а другая – нет, сравните их трассы, чтобы понять, что изменилось.
Совет: используйте стандартную схему метаданных трассировки LangSmith, чтобы данные от разных агентов были совместимы: LangSmith Trace Metadata Contract.

Преимущества и ограничения

Плюсы Минусы
Централизованный вид всех шагов Требует подписки и токенов
Быстрый поиск ошибок Не все агенты поддерживаются
Возможность создавать правила для повторных ошибок Не всегда доступен в России из‑за санкций
Возможность делиться результатами с секретами скрытыми Возможны задержки в обновлении данных
Интеграция с OpenTelemetry как альтернативой Нужно оценить ROI
Альтернативы: если LangSmith недоступен, можно использовать OpenTelemetry для сбора метрик, но настройка будет более сложной.

Что делать дальше: чеклист и рекомендации

Шаг Что проверить Как проверить
1 Поддерживает ли ваш агент LangSmith трассировку Посмотрите список поддерживаемых агентов в официальной документации
2 Установлен ли SDK и правильно ли настроены переменные окружения Выполните pip list и проверьте переменные LANGSMITH_API_KEY
3 Запускается ли агент с включённой трассировкой Посмотрите в терминале сообщение о подключении к LangSmith
4 Трассы появляются в интерфейсе LangSmith Откройте веб‑консоль и найдите ваш thread_id
5 Ошибки видны в трассе Найдите секцию «Errors and retries»
6 Создайте правило для повторных ошибок Сохраните трассу как «Skill» и используйте её в новых запусках
7 Оцените затраты на токены и подписку Посчитайте стоимость одного токена и сравните с бюджетом
8 Проверьте доступность сервиса в России Попробуйте подключиться из вашего региона, проверьте наличие VPN/прокси

Коротко:
1. Установите LangSmith и включите трассировку.
2. Найдите ошибку в трассе по thread_id.
3. Сохраните трассу как правило и применяйте к будущим запускам.
4. Оцените стоимость и доступность, если планируете масштабировать.

Вывод

Трассировка кода в LangSmith позволяет быстро увидеть, где и почему ваш кодинг‑агент «потерялся» в процессе генерации. Это экономит время, токены и повышает качество конечного кода. При этом важно учитывать стоимость подписки, доступность сервиса и поддерживаемые агенты. Если LangSmith не подходит, рассмотрите OpenTelemetry, но настройка будет более трудоемкой.

Источники

Темы журнала

Что почитать дальше