Как настроить LangGraph для сложных workflows

Короткий ответ: чтобы настроить LangGraph для сложных workflows, установите langgraph, опишите явную схему состояния, соберите StateGraph, добавьте ветвление через conditional edges, заранее продумайте reducers и persistence, затем проверьте выполнение через langgraph dev и Studio.

Результат: после выполнения инструкции у вас будет локально работающий LangGraph workflow на Python 3.10+ с ветвлением, тестовым запуском и понятным планом, как довести его до persistence и production deployment.

Практический вердикт: LangGraph оправдан, когда вы строите stateful, long-running или многошаговый workflow с контролируемым роутингом. Для простого одношагового вызова модели это обычно избыточный уровень абстракции.

Что именно нужно настроить в LangGraph для сложного workflow

Официальная документация описывает LangGraph как low-level orchestration runtime для long-running stateful agents. Он поддерживает durable execution, streaming, human-in-the-loop flows и persistence, а использовать его можно без LangChain.

На практике для сложного workflow вам нужно настроить не только сами узлы, но и архитектуру состояния: какие поля живут между шагами, где происходит ветвление, как сливаются конкурентные обновления и где хранится state между перезапусками.

Пошаговая настройка LangGraph

1. Шаг 1. Установите LangGraph в окружение Python 3.10+.

   Официальная установка для OSS-версии — через pip. Если вы параллельно используете примеры из экосистемы LangChain, документация отдельно указывает установить и langchain, но для базового графа он не обязателен.

   python -m venv .venv
   pip install -U langgraph

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

2. Шаг 2. Создайте файл приложения и опишите схему состояния.

   Для первого рабочего графа удобнее всего использовать TypedDict. Выделите только те поля, которые действительно проходят между узлами. Это особенно важно для сложных workflows: раздутый state быстро делает маршрутизацию и отладку неочевидными.

   from typing_extensions import TypedDict
   
   class WorkflowState(TypedDict):
       topic: str
       needs_review: bool
       reviewed: bool
       draft: str
       status: str

   Если дальше вы добавите параллельные ветки, сразу проверьте, не будут ли они писать в один и тот же ключ. По официальному Graph API concurrent updates без reducer по умолчанию приводят к overwrite.

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

3. Шаг 3. Соберите базовый StateGraph с узлами и ветвлением.

   Официальный рабочий поток одинаковый: определить state, добавить nodes и edges, затем скомпилировать граф перед использованием. Ниже — минимальный пример, который уже показывает branching для сложного сценария.

   from typing_extensions import TypedDict
   from langgraph.graph import StateGraph, START, END
   
   class WorkflowState(TypedDict):
       topic: str
       needs_review: bool
       reviewed: bool
       draft: str
       status: str
   
   def prepare(state: WorkflowState):
       return {
           'needs_review': len(state['topic']) > 20,
           'status': 'prepared',
       }
   
   def write_draft(state: WorkflowState):
       return {
           'draft': 'Черновик для темы: ' + state['topic'],
           'status': 'drafted',
       }
   
   def human_review(state: WorkflowState):
       return {
           'reviewed': True,
           'status': 'reviewed',
       }
   
   def publish(state: WorkflowState):
       return {
           'status': 'published',
       }
   
   def route_after_draft(state: WorkflowState):
       return 'human_review' if state['needs_review'] else 'publish'
   
   graph = StateGraph(WorkflowState)
   graph.add_node('prepare', prepare)
   graph.add_node('write_draft', write_draft)
   graph.add_node('human_review', human_review)
   graph.add_node('publish', publish)
   
   graph.add_edge(START, 'prepare')
   graph.add_edge('prepare', 'write_draft')
   graph.add_conditional_edges('write_draft', route_after_draft)
   graph.add_edge('human_review', 'publish')
   graph.add_edge('publish', END)
   
   app = graph.compile()

   Ожидаемый результат: граф компилируется без ошибок, а у вас появляется объект app, готовый к вызову.

4. Шаг 4. Запустите граф на двух входах и проверьте, что branching реально работает.

   Проверяйте не только факт запуска, но и различие маршрутов. Для этого удобно подавать короткую и длинную тему: в примере выше длинная тема уйдёт на дополнительный review.

   result_short = app.invoke({
       'topic': 'Короткая тема',
       'needs_review': False,
       'reviewed': False,
       'draft': '',
       'status': '',
   })
   
   result_long = app.invoke({
       'topic': 'Очень длинная тема, которая должна отправиться на дополнительную проверку',
       'needs_review': False,
       'reviewed': False,
       'draft': '',
       'status': '',
   })
   
   print(result_short)
   print(result_long)

   Ожидаемый результат: оба запуска завершаются успешно, но у длинной темы поле reviewed становится True, а у короткой остаётся False. Это означает, что conditional edges отработали по-разному.

5. Шаг 5. Выберите правильный паттерн маршрутизации до того, как граф разрастётся.

   Официальный Graph API рекомендует четыре ключевых паттерна для сложных workflows: conditional edges для обычного branching, Send для fan-out и map-reduce, Command для случаев, где один узел одновременно обновляет state и определяет маршрут, и subgraphs для вложенных reusable flows.

   Если вы ожидаете nested workflows, вынесите повторяемые части в subgraph сразу, а не после того, как граф станет трудно поддерживать. Если у вас много однотипной обработки по списку объектов, проектируйте под Send и reducers, а не под длинную линейную цепочку.

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

6. Шаг 6. Добавьте persistence до первого реального использования workflow.

   В официальной документации persistence разделяется на два уровня: checkpointer хранит thread state, а store хранит application data. Для продолжения одной и той же execution thread используйте thread_id в конфигурации вызова.

   Это критично для long-running и human-in-the-loop сценариев. In-memory savers не переживают перезапуск процесса, поэтому годятся только для development и тестирования. Для production документация рекомендует persistent saver, например PostgresSaver.

   Ожидаемый результат: вы не путаете временный локальный state с production persistence и проектируете workflow с учётом перезапусков.

7. Шаг 7. Запустите локальный сервер разработки и откройте Studio для отладки.

   Официальная команда локального сервера выглядит так:

   langgraph dev

   Этот режим предназначен только для development и testing и работает in-memory. После запуска локальный сервер позволяет открыть Studio и визуально проверить форму графа и поведение исполнения.

   Ожидаемый результат: вы можете инспектировать workflow до deployment и не используете локальный in-memory режим как постоянное решение.

8. Шаг 8. Готовьте production deployment только после фиксации репозитория и backend для persistence.

   Официальная документация deployment указывает, что для публикации нужен GitHub-репозиторий; поддерживаются и public, и private repositories. После deployment граф также можно инспектировать через Studio.

   Здесь есть важное ограничение: в supplied sources не зафиксированы цены, региональная доступность и все backend-specific детали rollout. Поэтому перед production запуском перепроверьте текущие страницы deployment, changelog и выбранного persistence backend.

   Ожидаемый результат: вы переходите к production только после того, как отказались от in-memory persistence и подготовили репозиторий под deployment.

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

• Выполните тестовый скрипт из шага 4 с короткой и длинной темой. Убедитесь, что итоговые состояния отличаются по полю reviewed.

• Проверьте, что вызов app.invoke(...) выполняется только после graph.compile(). Если compile пропущен, вы ещё не получили рабочее приложение.

• Если вы внедряете persistence, повторите вызовы с одним и тем же thread_id и проверьте, что state относится к одной thread execution, а не к разным запускам.

• Если вы используете langgraph dev, удостоверьтесь, что понимаете его назначение: это режим для локальной отладки и проверки графа в Studio, а не production-hosting.

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

• ❌ Ошибка: вы запускаете LangGraph на Python ниже 3.10.

  ✅ Решение: официальный install guide требует Python 3.10+. Пересоздайте окружение на поддерживаемой версии и повторите установку.

• ❌ Ошибка: граф описан, но не вызывается как приложение.

  ✅ Решение: проверьте, что вы прошли официальный порядок до конца: state → nodes → edges → compile(). Использовать граф до компиляции нельзя.

• ❌ Ошибка: параллельные ветки затирают данные друг друга.

  ✅ Решение: добавьте reducer для ключей, которые обновляются конкурентно. По умолчанию concurrent merge ведёт себя как overwrite.

• ❌ Ошибка: состояние исчезает после перезапуска локального процесса или сервера.

  ✅ Решение: это ожидаемо для in-memory saver и local dev server. Для production используйте persistent saver и заранее разделяйте thread state и application data.

• ❌ Ошибка: вы копируете старые примеры с create_react_agent и получаете расхождения с новой документацией.

  ✅ Решение: в migration guide для v1 указано, что create_react_agent deprecated в пользу langchain.agents.create_agent. Сверяйте свежие примеры с текущей документацией.

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

• LangGraph — low-level API. Вы сами отвечаете за схему состояния, routing, reducers и persistence. Это удобно для сложных workflows, но требует дисциплины в проектировании.

• Не храните production-state только in-memory. Документация прямо предупреждает, что in-memory savers не переживают рестарт.

• Разделяйте thread state и application data. Checkpointer нужен для thread state, store — для данных приложения.

• Если вы планируете использовать возможности из changelog, например type-safe streaming или type-safe invoke через version="v2", сначала проверьте, что ваша установленная версия пакета действительно их поддерживает.

• Редакционное ограничение: эта инструкция воспроизводит локальный OSS-сценарий и минимальный branching workflow. Точные экраны Studio, цены LangSmith и полный production path зависят от текущих официальных страниц и в supplied sources не раскрыты полностью.

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

• Если ваш workflow должен подтягивать знания из внешней базы, добавьте retrieval-слой по инструкции Как настроить RAG с LlamaIndex.

• Если вы хотите улучшить качество системных инструкций внутри узлов, посмотрите Как использовать meta-prompting для сложных задач.

• Если результаты LLM-узлов слишком хаотичны, отдельно откалибруйте параметры генерации по инструкции Как настроить Temperature и Top-p для контроля генерации.

• Если вы собираете workflow в IDE и хотите быстрее править код, пригодится Как использовать Windsurf (Codeium) для разработки.

Источники

• LangGraph overview
• Install LangGraph
• Graph API
• Persistence
• LangGraph local server
• Deploy LangGraph
• LangGraph v1 migration guide
• LangGraph changelog
• Use subgraphs
• langchain-ai/langgraph
• langgraph
• Pregel: a system for large-scale graph processing

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

Можно ли использовать LangGraph без LangChain?

Да. Официальный overview прямо указывает, что LangGraph можно использовать без LangChain.

Нужен ли GitHub-репозиторий для локальной настройки?

Нет. Для локальной OSS-настройки и тестового запуска графа достаточно Python-окружения и пакета langgraph. GitHub-репозиторий требуется для deployment по официальной схеме.

Подходит ли langgraph dev для production?

Нет. Документация local server указывает, что этот режим in-memory и предназначен для development и testing.

Когда использовать conditional edges, Send, Command и subgraphs?

Conditional edges подходят для обычного branching, Send — для fan-out и map-reduce, Command — когда узел должен одновременно обновить state и выбрать следующий маршрут, subgraphs — для вложенных и переиспользуемых workflows.

Какую версию фиксировать в проекте?

На PyPI в supplied sources последняя опубликованная версия — langgraph 1.2.11 от 2026-08-11. Перед production pinning всё равно перепроверьте PyPI и changelog, потому что релизы выходят регулярно.