Как создать простого AI-агента с LangChain

Результат: после выполнения инструкции вы запустите минимального AI-агента на LangChain v1, который принимает пользовательское сообщение, умеет вызывать простую Python-tool и возвращает ответ через agent.invoke(...).

Коротко: для простого старта в LangChain v1 рекомендуемый путь — собрать агента через create_agent. Ниже показан минимальный проверяемый сценарий из официальных материалов: установить langchain и пакет провайдера, описать tool обычной Python-функцией, вызвать агента и при необходимости включить LangSmith tracing.

• ⏱️ Время: 20–35 минут
• 🎯 Сложность: средний
• 💰 Стоимость: зависит от выбранного провайдера модели и, при использовании, LangSmith; точные публичные цены в собранных источниках не указаны
• 🛠️ Что потребуется: Python, доступ к терминалу, API-ключ выбранного провайдера, установленный пакет интеграции LangChain для этого провайдера
• 📌 Актуальная версия: LangChain v1; пакет langchain — 1.3.15 на дату 2026-08-14. Для примера ниже используется пакет langchain-openai 1.4.0. Альтернативы: langchain-google-genai 4.2.7, langchain-anthropic 1.5.1, langchain-ollama 1.1.0.

Редакционное ограничение: в официальных источниках из пакета не зафиксирован один универсальный идентификатор модели, который подошёл бы всем аккаунтам и регионам. Поэтому в коде ниже используется переменная окружения OPENAI_MODEL: подставьте поддерживаемый ID модели из официальной интеграции OpenAI для вашего аккаунта.

Что выбрать перед стартом

В этой инструкции пример кода показан на интеграции OpenAI, потому что это самый короткий путь для воспроизведения. Если вам нужен другой провайдер, замените только пакет интеграции и объект модели.

Пошагово: как создать простого AI-агента с LangChain

1. Установите LangChain и пакет интеграции провайдера.

   Для сценария из этой статьи установите langchain и langchain-openai. Если вы используете pip, выполните:

   pip install -U langchain langchain-openai

   Если вы уже ведёте проект через uv, quickstart LangChain рекомендует схему с uv add и uv sync:

   uv add langchain langchain-openai
   uv sync

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

2. Задайте переменные окружения для доступа к модели.

   Ниже — минимальный набор переменных для примера с OpenAI. Команды показаны в синтаксисе оболочки типа bash; если у вас другой shell, используйте эквивалент.

   export OPENAI_API_KEY="YOUR_OPENAI_API_KEY"
   export OPENAI_MODEL="YOUR_OPENAI_MODEL_ID"

   Переменная OPENAI_MODEL нужна потому, что в источниках не зафиксирован один обязательный model ID для всех аккаунтов. Возьмите поддерживаемый идентификатор из официальной страницы интеграции ChatOpenAI.

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

3. Создайте файл agent.py с минимальным агентом и одной tool.

   Скопируйте код ниже целиком. Здесь tool — обычная Python-функция, а сам агент собирается через create_agent с параметрами model=, tools= и system_prompt=, как рекомендовано в документации.

   import os
   
   from langchain.agents import create_agent
   from langchain_openai import ChatOpenAI
   
   
   def lookup_demo_ticket(ticket_id: str) -> str:
       """Вернуть статус демонстрационного тикета по его ID."""
       data = {
           "A-404": "resolved",
           "B-200": "open",
       }
       return data.get(ticket_id, "not_found")
   
   
   model = ChatOpenAI(model=os.environ["OPENAI_MODEL"])
   
   agent = create_agent(
       model=model,
       tools=[lookup_demo_ticket],
       system_prompt=(
           "Вы полезный ассистент. Когда пользователь просит проверить статус тикета, "
           "используйте tool и отвечайте коротко по-русски."
       ),
   )
   
   result = agent.invoke(
       {
           "messages": [
               {
                   "role": "user",
                   "content": "Обязательно используй tool lookup_demo_ticket и скажи статус тикета A-404.",
               }
           ]
       }
   )
   
   print(result["messages"][-1].content_blocks)

   Ожидаемый результат: у вас есть законченный минимальный скрипт, который создаёт агента, регистрирует tool и вызывает agent.invoke в формате из quickstart.

4. Запустите скрипт.

   python agent.py

   LangChain quickstart предлагает проверять результат через result["messages"][-1].content_blocks. Поэтому в консоли вы увидите содержимое последнего сообщения агента в структурированном виде, а не обязательно одну строку обычного текста.

   Ожидаемый результат: скрипт выполняется без ошибок импорта и авторизации, а итоговый ответ содержит результат работы tool. Для запроса из примера вы должны увидеть, что для тикета A-404 возвращается статус resolved.

5. Включите LangSmith tracing для диагностики и запустите скрипт ещё раз.

   Если агент не вызывает tool, отвечает не так, как вы ожидали, или вы хотите видеть шаги исполнения, включите tracing. Для этого задайте переменные окружения из документации LangChain:

   export LANGSMITH_TRACING="true"
   export LANGSMITH_API_KEY="YOUR_LANGSMITH_API_KEY"
   python agent.py

   После этого откройте LangSmith и проверьте trace последнего запуска. При регистрации в LangSmith нужно выбрать регион данных на GCP — US, EU или APAC. Этот выбор, по официальной странице сервиса, потом изменить нельзя.

   Ожидаемый результат: помимо ответа в терминале вы видите trace выполнения в LangSmith и можете проверить, был ли реально вызван tool, на каком шаге возникла ошибка и какой был финальный ответ модели.

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

• Запустите python agent.py и убедитесь, что нет ошибок вида отсутствующего пакета или переменной окружения.
• Проверьте вывод последнего сообщения: в quickstart LangChain для этого предлагается смотреть result["messages"][-1].content_blocks.
• Убедитесь, что ответ соответствует вашей tool. В примере выше ожидаемый итог — статус resolved для тикета A-404.
• Если включён LangSmith tracing, откройте trace и проверьте, что видно полный прогон агента и вызов tool.

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

• ❌ Ошибка: ModuleNotFoundError для langchain_openai.
  ✅ Решение: установите пакет интеграции в то же окружение, где запускаете скрипт: pip install -U langchain langchain-openai или используйте эквивалентную схему через uv add/uv sync.
• ❌ Ошибка: скрипт падает из-за отсутствия OPENAI_API_KEY или OPENAI_MODEL.
  ✅ Решение: задайте обе переменные окружения в текущей сессии терминала перед запуском. Для OPENAI_MODEL используйте поддерживаемый ID из официальной интеграции ChatOpenAI.
• ❌ Ошибка: вы пытаетесь подключить сторонний OpenAI-compatible endpoint и поведение отличается от ожидаемого.
  ✅ Решение: для воспроизведения этой инструкции используйте официальный OpenAI API. В документации указано, что интеграция ChatOpenAI ориентирована именно на него; сторонние compatible endpoints нужно проверять отдельно.
• ❌ Ошибка: в LangSmith не появляются traces.
  ✅ Решение: проверьте, что заданы обе переменные: LANGSMITH_TRACING="true" и LANGSMITH_API_KEY, затем перезапустите скрипт.
• ❌ Ошибка: агент отвечает, но «не помнит» предыдущий ход диалога.
  ✅ Решение: минимальный пример в этой статье статeless. Если вам нужен state или persistence между ходами, документация рекомендует передать checkpointer; в локальном примере для этого используется InMemorySaver() и thread_id.

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

• Не храните API-ключи в исходном коде. Для минимального примера достаточно переменных окружения.
• Эта инструкция воспроизводит путь через OpenAI. Для Google, Anthropic и Ollama меняется пакет интеграции и объект модели.
• Если вы выбираете Google-путь, интеграция поддерживает Gemini Developer API и Vertex AI, а backend выбирается автоматически. Доступность конкретных моделей и квот зависит от региона и аккаунта.
• Если вы выбираете Ollama, нужен локальный экземпляр Ollama. Это не облачный сценарий, и производительность зависит от вашей машины.
• Точные публичные цены моделей и LangSmith в собранных источниках не указаны; перед production-использованием проверьте официальные страницы провайдера и сервиса.
• Если вам нужен детерминированный многошаговый workflow или более сложная оркестрация, минимального агента через create_agent может быть недостаточно; в исходных материалах LangChain для более сложных сценариев предлагаются более продвинутые инструменты экосистемы.
• При регистрации в LangSmith регион данных выбирается один раз и позже не меняется.

Практический вердикт: если вам нужен первый рабочий агент без долгой оркестрации, LangChain v1 с create_agent — самый короткий путь из официальной документации. Если же вы заранее знаете, что вам нужна память между ходами, детерминированные ветки и сложный workflow, сразу закладывайте более продвинутую архитектуру, а не только минимальный demo-агент.

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

• Если хотите сравнить кодовый агентный подход с другим фреймворком, посмотрите инструкцию Как создать ИИ-агента на CrewAI.
• Если вам ближе no-code или low-code автоматизация, переходите к гайду Как настроить агента в n8n с ИИ.
• Перед выносом агента в рабочий контур проверьте базовые принципы AI Safety (безопасность ИИ).
• Когда базовый агент заработает, попробуйте прикладной сценарий: как сгенерировать тесты с помощью AI.

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

Нужен ли LangSmith, чтобы запустить первого агента?

Нет. Минимальный путь работает без LangSmith: достаточно установить LangChain и пакет провайдера, создать агента, вызвать agent.invoke и проверить ответ. LangSmith нужен для tracing и диагностики.

Можно ли использовать ChatOpenAI со сторонним OpenAI-compatible API?

В официальной документации сказано, что интеграция ChatOpenAI ориентирована на официальный OpenAI API. Если вы хотите использовать сторонний совместимый endpoint, его поведение и совместимость нужно проверять отдельно.

Как добавить память между ходами диалога?

Для этого нужен state/persistence. В документации LangChain для таких случаев рекомендуется передавать checkpointer; в локальном примере используется InMemorySaver() и thread_id.

Можно ли запустить такого агента локально без облачного API?

Да, для локального сценария у LangChain есть интеграция с Ollama. Но для этого требуется локально установленный и доступный экземпляр Ollama.

Сколько это стоит?

Точные публичные цены LangSmith и провайдерских моделей в собранных источниках не указаны. Перед использованием в рабочем проекте проверьте официальные страницы выбранного провайдера и LangSmith.

Источники

• Changelog – Docs by LangChain
• ChatAnthropic integration – Docs by LangChain
• LangChain release process · Issue #38437 · langchain-ai/langchain · GitHub

• Quickstart – Docs by LangChain
• Agents – Docs by LangChain
• What’s new in LangChain v1 – Docs by LangChain
• langchain · PyPI
• langchain-openai · PyPI
• langchain-google-genai · PyPI
• langchain-anthropic · PyPI
• langchain-ollama · PyPI
• ChatOpenAI integration – Docs by LangChain
• ChatGoogleGenerativeAI integration – Docs by LangChain
• Ollama integration – Docs by LangChain
• LangSmith