Как отладить LangChain-агента через трассировку LangSmith

1. Заведите отдельный тестовый проект LangSmith и настройте секрет API key в окружении, не в исходном файле.
2. Запустите один безопасный запрос к агенту с известным входом и ожидаемым ответом.
3. Найдите trace в выбранном проекте и сверьте вопрос, модель, этапы инструмента и конечный вывод.
4. Для ошибки создайте негативный тест с пустым источником и выясните, выдумал ли ответ агент или источник вернул плохие данные.
5. Отключите передачу чувствительных полей или настройте их редакцию перед включением tracing на рабочем трафике.

Пример ниже предназначен для демонстрационного окружения: установите соответствующий пакет интеграции, настройте ключ через секреты сервера и убедитесь, что модель доступна вашему аккаунту. Если доступ к указанному model ID отсутствует, выберите поддерживаемую модель со сходными возможностями и заново проверьте работу именно на ней. Ни один пример не содержит действующего API-ключа и не разрешает обход ограничений провайдера.

Готовый шаблон на Python

# Задайте в секретном окружении перед запуском:
# LANGSMITH_TRACING=true
# LANGSMITH_API_KEY=<секрет LangSmith>
# LANGSMITH_PROJECT=ru-support-test
# OPENAI_API_KEY=<секрет модели>
from langchain.agents import create_agent

agent = create_agent(model="openai:gpt-5.5", tools=[],
    system_prompt="Отвечай кратко и без выдуманных фактов.")
result = agent.invoke({"messages": [{"role": "user", "content":
    "Что такое retrieval в RAG?"}]})
print(result["messages"][-1].content)
# Проверьте trace в выбранном проекте LangSmith.

Конкретные входные и ожидаемые данные

Вход: «Что такое retrieval в RAG?» и тестовый проект ru-support-test. Ожидается trace с входным вопросом, вызовом указанной модели и конечным текстом, который объясняет извлечение релевантных источников. Если trace отсутствует, проверьте имя проекта, переменные окружения и доступ ключа. Точный интерфейс и время доставки трассы не обещаются.

Оценивать стоит не красоту формулировки, а проверяемое выполнение задачи. Сохраните исходный текст, ID пользователя или теста и ожидаемое значение отдельно от ответа модели. Если пример выдаёт неверный факт, разберите данные на входе и состояние инструмента до изменения промпта: иначе можно замаскировать ошибку инфраструктуры удачной перефразировкой.

Диагностика и границы решения

Трассировка помогает отличать ошибку контекста от ошибки генерации. Если агент ответил «14 дней», а инструмент передал устаревший документ с таким сроком, проблема находится в данных источника, даже если модель аккуратно их пересказала. Если инструмент возвратил правильное исключение, а агент его проигнорировал, изучайте prompts и порядок сообщений. Для сложного агента фиксируйте последовательность tool calls, аргументы после редактирования и наличие финального ответа; один общий журнал времени не показывает, на каком этапе произошёл сбой. Не отправляйте в тестовый проект реальные медицинские, платёжные или личные сообщения без разрешения и ограничений доступа. Проект LangSmith — не замена вашей системе аудита: сохраните отдельные ID запроса и источника, чтобы связать трассу с бизнес-событием без утечки текста. Включение tracing может влиять на приватность данных; оператор должен понимать, какие поля фактически уходят в сервис. Для производственной диагностики применяйте выборочную запись, маскировку и срок хранения. Удачный trace подтверждает исполнение шагов, но не доказывает корректность политики возврата или релевантность ответа.

Контрольный эксперимент

Создайте набор из трёх трасс: правильный ответ на известный вопрос, отсутствие ответа при пустом источнике и инструмент с запланированной ошибкой. Сопоставьте ID источников на входе агента, ToolMessage и текст пользователя. Если в отрицательном тесте агент всё равно произвёл уверенный факт, это сигнал к отказной логике и предметным тестам. Если модель или инструмент вызываются повторно, trace помогает оценить причину роста времени и числа запросов; не делайте вывод о стоимости из одного trace без учёта лимитов и фактического потребления провайдера. При сравнении версий агента держите одинаковые вопросы и документы. Пользовательский текст в trace доступен тем, кому вы дали доступ к проекту: отдельный доступ администраторов, минимизация payload и удаление лишних записей столь же важны, как удобство отладки. Не включайте секреты в system_prompt, иначе они могут оказаться в диагностике.

Дополнительный проверочный сценарий

Перед запуском теста подготовьте матрицу того, что разрешено логировать. Поле order_id может быть приемлемо в закрытом проекте, а полный адрес доставки — нет; API key и токены нельзя передавать в trace ни при каких обстоятельствах. Проверьте не только основной prompt, но и аргументы tools и исключения, где часто появляется сырой ответ внешнего сервиса. Если вы обнаружили неправильный итог, фиксируйте trace ID и указывайте, на каком шаге возникло искажение: неверный retrieval, устаревшие данные, ошибка schema или генерация. Исправление без воспроизводимого входа часто создаёт новую регрессию. Трассировка — основа диагностики, но оценку качества формируйте на размеченных вопросах и фактах, а не по числу красивых traces.