Как настроить observability для AI-агентов с LangSmith

После выполнения этой инструкции вы настроите observability для AI-агентов с LangSmith и сможете видеть traces запуска, вложенные вызовы LLM, инструменты и retriever-шаги в одном проекте. Самый быстрый путь для агента на LangChain или LangGraph: включить LANGSMITH_TRACING=true, задать LANGSMITH_API_KEY, при необходимости указать региональный LANGSMITH_ENDPOINT и заново запустить приложение.

Сводка

• ⏱️ Время: 20–40 минут, если у вас уже есть работающий агент.
• 🎯 Сложность: средний.
• 💰 Стоимость: по странице pricing у LangSmith есть Developer — $0/seat/month, Plus — $39/seat/month, Enterprise — custom pricing. Self-hosted — Enterprise add-on. Актуальные usage-начисления и налоги проверяйте на официальной странице.
• 🛠️ Что потребуется: аккаунт LangSmith, LANGSMITH_API_KEY, рабочий AI-агент, доступ к переменным окружения, а для теста quickstart — также OPENAI_API_KEY.
• 📌 Актуальность: условия и документы LangSmith проверены по состоянию на 2026-08-15; для OpenTelemetry документация требует langsmith>=0.3.18 и рекомендует langsmith>=0.4.25.

Практический вердикт: если ваш агент уже собран на LangChain или LangGraph, не начинайте с OpenTelemetry и не пытайтесь сразу self-hosted. Для большинства команд достаточно SaaS-интеграции через environment variables, а кастомные функции потом точечно размечаются через @traceable, context manager или RunTree API.

Редакционное ограничение: в проверенном source pack нет пошагово зафиксированных UI-действий для выпуска API key и нет точных региональных API URL в явном виде. Поэтому ниже — воспроизводимый путь через environment variables и проверку в интерфейсе LangSmith, а точное значение регионального endpoint берите из официальной документации по регионам и tracing.

Оглавление

• Какой путь настройки выбрать
• Пошагово: как настроить observability в LangSmith
• Как проверить, что всё работает
• Частые ошибки и исправления
• Безопасность и ограничения
• Что делать дальше
• Источники
• Вопросы и ответы

Какой путь настройки выбрать

Пошагово: как настроить observability в LangSmith

1. Выберите один путь интеграции для текущего агента.

   Если агент работает на LangChain, начните с LangChain integration. Если это LangGraph workflow, используйте LangGraph integration. Если код в основном кастомный или у вас несколько языков и уже есть OpenTelemetry, выбирайте manual instrumentation или OTel.

   Ожидаемый результат: у вас есть один основной путь внедрения, а не смесь нескольких подходов без необходимости.

2. Подготовьте SDK и зависимости для выбранного пути.

   В официальном quickstart для tracing используются пакеты langsmith и openai. Для OpenTelemetry документация отдельно указывает минимальную версию langsmith>=0.3.18 и рекомендует langsmith>=0.4.25.

   Если вы не запускаете quickstart-пример, а подключаете observability к уже готовому агенту, достаточно убедиться, что в окружении есть нужный LangSmith SDK и зависимости вашего приложения.

   Ожидаемый результат: ваше приложение может стартовать с LangSmith SDK без конфликтов по версии.

3. Задайте базовые переменные окружения для tracing.

   Это обязательный минимум из официального quickstart:

   export LANGSMITH_TRACING=true
   export LANGSMITH_API_KEY="your_langsmith_api_key"
   export OPENAI_API_KEY="your_openai_api_key"
   export LANGSMITH_PROJECT="your_project_name"

   LANGSMITH_PROJECT опционален. Если вы его не зададите, LangSmith использует автоматически созданный tracing project.

   Ожидаемый результат: tracing включён на уровне окружения, а данные будут отправляться в указанный проект или в auto-created project.

4. Укажите региональный endpoint, если ваш аккаунт не в default US region.

   Для аккаунтов вне default US region аутентификация без LANGSMITH_ENDPOINT может завершаться ошибкой. Документация перечисляет поддержанные SaaS endpoints для GCP US, GCP EU, GCP APAC и AWS US, но точное значение URL берите из официальной страницы tracing или Regions FAQ для вашего региона.

   Этот шаг особенно важен, если вы видите проблему не в коде агента, а именно в подключении к LangSmith.

   Ожидаемый результат: приложение авторизуется в правильном региональном инстансе LangSmith.

5. Перезапустите приложение с авто-трейсингом LangChain или LangGraph.

   Для LangChain apps базовый tracing после настройки integration работает без дополнительного кода. Для LangGraph действует тот же поток, если вы используете модули LangChain.

   Если у вас LangChain.js, задайте режим background callbacks в зависимости от деплоя:

   Сценарий	Рекомендация
   Не serverless	LANGCHAIN_CALLBACKS_BACKGROUND=true для снижения latency
   Serverless	LANGCHAIN_CALLBACKS_BACKGROUND=false, чтобы tracing успел завершиться до выхода функции

   Ожидаемый результат: при следующем запуске агент начнёт автоматически отправлять traces в LangSmith.

6. Разметьте кастомные функции, tools и SDK-вызовы, которые не покрывает авто-интеграция.

   Если внутри LangGraph или другого оркестратора у вас есть собственные функции, retriever, обращения к внешним SDK или внутренние service-layer вызовы, используйте один из официально поддержанных механизмов manual instrumentation:

   • @traceable
   • Python trace context manager
   • RunTree API

   Для custom SDKs или функций внутри LangGraph документация отдельно советует оборачивать их через @traceable/traceable или wrap_openai, чтобы traces правильно вкладывались друг в друга.

   Если вы хотите, чтобы в Details view корректно отображались токены и latency, используйте run_type="llm". Если нужно видеть retrieved documents inline, задавайте run_type="retriever".

   Ожидаемый результат: в одном trace появляются не только верхнеуровневые вызовы агента, но и внутренние шаги, инструменты и retrieval.

7. Подключите OpenTelemetry, если ваш стек не ограничен LangChain.

   Для OTel-пути документация требует включить и LangSmith tracing, и OTel, и корректный региональный endpoint. Минимальная конфигурация начинается с таких переменных:

   export LANGSMITH_TRACING=true
   export LANGSMITH_OTEL_ENABLED=true

   Дальше завершите OTel-настройку по официальному гайду именно для вашего языка и текущей инфраструктуры. Этот путь оправдан, если у вас polyglot stack, существующий OTel-pipeline или observability уже унифицирована на уровне платформы.

   Ожидаемый результат: вы отправляете телеметрию в LangSmith через OpenTelemetry-маршрут, а не только через LangChain-specific integration.

8. Сделайте один тестовый прогон агента и откройте проект в LangSmith UI.

   После запуска откройте tracing project в LangSmith UI, нажмите на строку trace и проверьте Trace details panel. По документации боковая панель организована вокруг threads, поэтому удобнее проверять не только отдельный run, но и контекст последовательности сообщений.

   Если вы правильно задали run_type, то для llm увидите token counts и latency, а для retriever — retrieved documents inline.

   Ожидаемый результат: хотя бы один успешный trace виден в UI и разбирается по вложенным шагам.

Как проверить, что всё работает

1. Отправьте агенту один простой запрос, который гарантированно проходит через вашу обычную цепочку: LLM, tool или retriever.
2. Откройте tracing project в LangSmith UI и убедитесь, что появилась новая строка trace.
3. Нажмите на строку и проверьте, что открывается Trace details panel.
4. Убедитесь, что вложенные шаги расположены логично: верхний run агента, внутри — LLM/tool/retriever вызовы.
5. Если вы специально размечали типы run, проверьте результат рендеринга: run_type="llm" должен показывать token counts и latency, а run_type="retriever" — retrieved documents inline.
6. Если у вас conversation-style агент, проверьте, что боковая панель действительно группирует данные вокруг threads, а не только вокруг одного isolated вызова.

Если все шесть проверок проходят, observability для AI-агента с LangSmith настроена корректно.

Частые ошибки и исправления

• ❌ Ошибка: аутентификация не проходит, хотя LANGSMITH_API_KEY задан.
  ✅ Решение: проверьте, не находится ли ваш аккаунт вне default US region. В этом случае обязательно задайте корректный LANGSMITH_ENDPOINT из официальной региональной документации.
• ❌ Ошибка: приложение запускается, но traces не появляются.
  ✅ Решение: убедитесь, что LANGSMITH_TRACING=true действительно выставлен в окружении процесса, а не только в локальном shell. Для quickstart-проверки также нужен валидный LANGSMITH_API_KEY.
• ❌ Ошибка: в LangGraph часть внутренних вызовов не видна или не вложена в родительский trace.
  ✅ Решение: явно оберните custom SDKs и функции через @traceable/traceable или wrap_openai, как рекомендует документация LangGraph tracing.
• ❌ Ошибка: в Details view нет token counts, latency или inline-списка документов.
  ✅ Решение: проверьте выбранный run_type. Для токенов и latency нужен run_type="llm"; для retrieved documents inline — run_type="retriever".
• ❌ Ошибка: в LangChain.js вы видите лишнюю latency или, наоборот, недописанные traces при serverless-вызовах.
  ✅ Решение: вне serverless используйте LANGCHAIN_CALLBACKS_BACKGROUND=true; в serverless — false, чтобы tracing успел завершиться до выхода функции.

Безопасность и ограничения

• Retention traces: в LangSmith SaaS trace data хранится 180 дней с момента ingestion. Если вам нужно сохранить важные данные дольше, используйте datasets: по документации они сохраняются indefinitely.
• Регионы: региональные инстансы доступны на всех планах, включая free plans. При этом pricing одинаков по поддержанным cloud regions, оплата идёт в USD, а migration между регионами не поддерживается.
• Self-hosted: self-hosted LangSmith — это Enterprise add-on. Для development/testing официальный путь — Docker Compose; для production — Kubernetes плюс Helm. Это не тот вариант, с которого стоит начинать, если у вас просто один агент и нет требований к изоляции.
• Версии для OTel: для OpenTelemetry соблюдайте порог langsmith>=0.3.18; документация рекомендует >=0.4.25. Если пинните версии жёстко, сверяйте релизы SDK и ваш internal dependency policy.
• Self-hosted releases: в changelog на момент проверки есть и release candidate, и stable-релизы, включая langsmith-0.17.0-rc.6 и langsmith-0.16.2. Перед апгрейдом подтверждайте точную целевую версию, а не ориентируйтесь только на последнюю запись в changelog.
• UI и live labels: документация фиксирует workflow просмотра traces, но конкретные UI labels и beta-элементы могут меняться. Перед подготовкой внутренних SOP или скриншотов перепроверьте текущий интерфейс в вашем регионе.

Что делать дальше

• Если вы строите сложную агентную оркестрацию, переходите к инструкции Как настроить LangGraph для сложных workflows.
• Если observability нужна для retrieval-цепочек, полезно параллельно настроить RAG с LlamaIndex и размечать retriever-вызовы отдельным run_type.
• Если агент живёт в no-code/automation-сценариях, посмотрите как настроить AI-автоматизацию в n8n и как настроить агента в n8n с ИИ.
• Для проектирования многошаговых систем полезно свериться с термином оркестрация агентов, чтобы отделить tracing отдельного run от логики всего workflow.

Источники

• Tracing quickstart – Docs by LangChain
• Trace LangChain applications (Python and JS/TS) – Docs by LangChain
• Trace LangGraph applications – Docs by LangChain
• Custom instrumentation – Docs by LangChain
• Trace with OpenTelemetry – Docs by LangChain
• View traces – Docs by LangChain
• Observability concepts – Docs by LangChain
• Regions FAQ – Docs by LangChain
• Self-hosted LangSmith – Docs by LangChain
• Self-hosted LangSmith changelog – Docs by LangChain
• LangSmith Plans and Pricing
• GitHub – langchain-ai/langsmith-sdk
• Releases · langchain-ai/langsmith-sdk

Вопросы и ответы

Можно ли настроить LangSmith без LangChain?

Да. Для этого у LangSmith есть manual instrumentation через @traceable, Python trace context manager и RunTree API, а также отдельный путь через OpenTelemetry для polyglot или non-LangChain stack.

Нужно ли писать дополнительный код для базового tracing?

Если приложение уже построено на LangChain и вы включили интеграцию через environment variables, для basic tracing дополнительный код не нужен. Но для кастомных SDK, tools и внутренних функций внутри LangGraph или вашего приложения явная разметка всё равно полезна.

Когда обязательно задавать LANGSMITH_ENDPOINT?

Когда ваш аккаунт не находится в default US region. Иначе аутентификация может завершаться ошибкой, даже если API key корректный.

Сколько хранятся traces?

В LangSmith SaaS traces хранятся 180 дней с момента ingestion. Если вам нужно сохранить важные примеры надолго, переносите их в datasets: по документации они сохраняются indefinitely.

Можно ли использовать self-hosted вместо SaaS?

Да, но это Enterprise add-on. Для development/testing официальный путь — Docker Compose, а для production — Kubernetes и Helm. Для одной команды или первого пилота чаще практичнее начать с SaaS и только потом оценивать self-hosted.