Как перенести workflow из LangChain в LangGraph

После выполнения этой инструкции у вас будет рабочий план переноса существующего workflow из LangChain в LangGraph: вы выберете правильный путь миграции, приведёте код к актуальным API и проверите результат локально перед production-развёртыванием.

Практический вывод: если ваш workflow линейный или с небольшим ветвлением, начинайте с Functional API — это официальный путь с минимальным объёмом рефакторинга. Если вам нужны явное состояние, сложные ветвления, циклы, параллельная обработка и контроль над графом, переходите на Graph API. Если же у вас уже используется LangChain v1 create_agent, ваш runtime уже построен на LangGraph, и «миграция» может означать не смену платформы, а переход к более низкоуровневому управлению.

Редакционное ограничение: в собранных официальных источниках нет одной страницы с полным чек-листом «LangChain workflow → LangGraph graph». Шаги ниже собраны из нескольких официальных документов LangGraph и LangChain, поэтому перед массовым рефакторингом нестандартной архитектуры сверяйте сигнатуры и текущие ограничения в первоисточниках.

• Время: зависит от размера workflow; точная официальная оценка в источниках не указана.
• Сложность: средний.
• Стоимость: зависит от используемых сервисов и типа развёртывания; условия LangSmith Deployment и планов нужно проверять на официальной странице.
• Что потребуется: исходный код текущего workflow, Python 3.10+ для пакетов LangChain/LangGraph, Python 3.11+ для локального сервера LangGraph CLI, доступ к структуре приложения с langgraph.json, файлами зависимостей и при необходимости .env.
• Актуальная версия: LangGraph 1.2.11 по GitHub Releases на 2026-08-15; для LangChain в источниках зафиксирован v1.

Быстрый выбор пути миграции

Пошаговый перенос workflow из LangChain в LangGraph

1. 1. Зафиксируйте исходную точку текущего workflow.

   Составьте короткую карту процесса: какие шаги выполняются последовательно, где есть ветвления, что должно переживать повторный вызов, и используете ли вы уже LangChain v1 create_agent. Это один из самых важных шагов, потому что именно форма текущего workflow определяет, нужно ли вам минимальное перенесение в Functional API или полноценное моделирование графа.

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

2. 2. Проверьте версию Python для вашего сценария.

   Если вы переносите только код пакетов LangChain/LangGraph, ориентируйтесь на требование Python 3.10+ из руководства по миграции LangGraph v1. Если вы хотите локально поднять сервер для проверки через CLI, используйте Python 3.11+, потому что именно такое требование указано для локального сервера LangGraph.

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

3. 3. Выберите целевой API миграции.

   Примите одно решение: Functional API для минимального рефакторинга или Graph API для явного контроля над состоянием и ветвлениями. Официальные документы подчёркивают, что оба API работают на одном runtime, а также описывают путь дальнейшего перехода с Functional API на Graph API, если простой перенос позже перерастёт в более сложную оркестрацию.

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

4. 4. Перенесите линейную логику в Functional API, если вам нужен минимальный рефакторинг.

   Сохраните существующий порядок операций и переносите workflow как последовательность шагов без преждевременного усложнения. Это официальный путь с меньшим порогом входа: вы не переписываете архитектуру вокруг графа сразу, а сначала добиваетесь того же результата на runtime LangGraph.

   Минимальный путь миграции:
   текущие шаги workflow
   → оформить как переносимый исполняемый поток
   → сохранить существующий порядок вызовов
   → запустить на runtime LangGraph
   → при усложнении позже перейти в Graph API

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

5. 5. Смоделируйте workflow через Graph API, если вам нужны явные узлы, рёбра и состояние.

   В Graph API workflow моделируется как граф: вы определяете состояние, добавляете узлы и рёбра, а затем компилируете граф перед использованием. Этот путь подходит там, где логика уже не укладывается в «почти линейный» сценарий: есть несколько маршрутов исполнения, циклы, точки возврата, накопление общего состояния или параллельная обработка.

   Общий шаблон миграции в Graph API:
   1) описать общее состояние;
   2) оформить этапы workflow как узлы;
   3) соединить узлы рёбрами и условиями;
   4) вызвать compile();
   5) проверять выполнение через invoke() или stream().

   Ожидаемый результат: у вас есть явная графовая модель workflow, которую проще читать, отлаживать и расширять при сложной оркестрации.

6. 6. Замените устаревшие конструкции LangGraph v1.

   Если в проекте остался create_react_agent, замените его на LangChain create_agent: именно такой путь указан как актуальный. Если код использует MessageGraph, переведите его на StateGraph с ключом messages. Руководство по миграции LangGraph v1 прямо отмечает, что библиотека в целом в большой степени обратно совместима, но эти точки нужно привести к текущему виду.

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

7. 7. Подготовьте структуру приложения LangGraph.

   Упакуйте приложение так, как ожидает LangGraph: добавьте langgraph.json, файлы зависимостей и при необходимости .env. Эта структура нужна и для локальной проверки, и для дальнейшего развёртывания через LangSmith Deployment.

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

8. 8. Запустите локальную проверку командой langgraph dev.

   Для локальной разработки и smoke-теста поднимите сервер через langgraph dev. По документации локальный API стартует на http://127.0.0.1:2024, а Studio доступна для инспекции графа и прогонов. Это наиболее прямой способ понять, что миграция не только компилируется, но и исполняется так, как вы ожидаете.

   Ожидаемый результат: локальный API отвечает на 127.0.0.1:2024, а граф и прогоны видны в Studio.

9. 9. Подготовьте production-развёртывание только после локального smoke-теста.

   Если локальная проверка успешна, переходите к LangSmith Deployment. Официальные документы описывают production-развёртывание именно через этот путь, а результат предлагается проверять в Studio и тестированием deployment API URL. Учитывайте, что в собранных источниках отдельно подчёркнуты различия по планам и типам хостинга, поэтому перед rollout перепроверьте текущие условия на официальной странице развёртывания.

   Ожидаемый результат: у вас есть подтверждённый путь от локального теста к production-развёртыванию без использования dev-сервера как хостинга.

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

1. Запустите langgraph dev в подготовленном приложении LangGraph.
2. Убедитесь, что локальный API доступен по адресу http://127.0.0.1:2024.
3. Откройте Studio и проверьте, что граф соответствует новой модели workflow: видны узлы, рёбра и ожидаемые переходы.
4. Повторно вызовите workflow на том же сценарии и проверьте поведение checkpointed re-invocation, если ваша миграция опирается на контроль состояния и продолжение выполнения.
5. Если вы уже готовите production, дополнительно протестируйте deployment API URL после публикации через LangSmith Deployment.

Что считать успешной миграцией: workflow запускается в локальном API, визуально прослеживается в Studio, а повторный вызов или продолжение из checkpoint не ломает логику состояния там, где это требуется вашему сценарию.

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

• Ошибка: вы пытаетесь уместить сложный workflow с глубокой ветвистостью в Functional API.
  Решение: переходите на Graph API, если вам нужны явные состояние, ветвления, циклы и параллельная обработка. Это официальный сценарий использования Graph API.
• Ошибка: локальный сервер не подходит вашему окружению, хотя код пакетов запускается.
  Решение: проверьте версию Python. Для LangChain-пакетов в источниках указано Python 3.10+, а для локального сервера LangGraph CLI — Python 3.11+.
• Ошибка: в проекте остался create_react_agent.
  Решение: замените его на LangChain create_agent, потому что именно он указан как актуальный путь в LangGraph v1.
• Ошибка: вы переносите старый MessageGraph как есть.
  Решение: переводите его на StateGraph с ключом messages — это указанная в документации замена.
• Ошибка: вы рассматриваете langgraph dev как production-хостинг.
  Решение: используйте dev-сервер только для разработки и тестирования. Для production в документации указан LangSmith Deployment.

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

• Локальный сервер LangGraph в режиме langgraph dev работает как in-memory server для разработки и тестирования, а не как production-среда.
• Структура приложения LangGraph предусматривает langgraph.json, файлы зависимостей и опциональный .env; это важно для воспроизводимости и переноса между средами.
• В собранных источниках нет полного единого чек-листа «старый LangChain workflow → новый LangGraph app», поэтому для нетиповых сценариев полезно сверять сразу несколько страниц документации.
• Условия deployment зависят от типа размещения и плана; отдельные региональные детали в источниках не перечислены, поэтому перед покупкой или rollout перепроверьте официальную страницу развёртывания.
• Если ваш код уже построен вокруг LangChain v1 create_agent, полноценная «миграция в LangGraph» может не понадобиться: сначала решите, нужен ли вам именно более низкоуровневый контроль над графом.

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

• Если перенос затрагивает не только orchestration, но и текстовые инструкции, посмотрите как перенести промпты из ChatGPT в Claude.
• Если хотите тестировать связанные LLM-сценарии рядом с кодом миграции, пригодится инструкция как подключить Claude в Cursor.
• Если перед рефакторингом нужно сохранить рабочие диалоги и примеры поведения старого сценария, используйте экспорт истории чатов из ChatGPT как опорный материал для регрессионной проверки.

Источники

• Choosing between the Graph and Functional APIs
• Graph API
• LangGraph v1 migration guide
• LangChain v1
• Run a local server
• Application structure
• LangSmith Deployment
• Releases · langchain-ai/langgraph

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

Можно ли перенести workflow без полного переписывания?

Да, если ваш сценарий линейный или с небольшим ветвлением. Официальные документы рекомендуют Functional API как lower-friction путь с минимальным рефакторингом, а затем при необходимости допускают переход в Graph API.

Нужен ли мне LangGraph, если я уже использую LangChain v1 create_agent?

Не всегда. LangChain v1 create_agent уже построен на LangGraph. В таком случае вопрос обычно не в смене runtime, а в том, нужен ли вам более низкоуровневый контроль над состоянием, узлами и ветвлениями.

Какая версия Python нужна для миграции?

Для LangChain-пакетов в руководстве по миграции LangGraph v1 указано Python 3.10+. Для локального сервера LangGraph CLI документация требует Python 3.11+.

Можно ли использовать langgraph dev как production-окружение?

Нет. Документация прямо указывает, что локальный in-memory server предназначен для разработки и тестирования. Для production нужно использовать LangSmith Deployment.

Что считать минимальной проверкой после переноса?

Минимум: локальный запуск через langgraph dev, доступность API на 127.0.0.1:2024, визуальная проверка графа в Studio и повторный вызов сценария или проверка checkpointed re-invocation там, где это важно для вашей логики.