LangGraph: что это и как собрать stateful AI-агента на Python

LangGraph это библиотека от команды LangChain Inc для построения AI-агентов, которые умеют возвращаться к предыдущим шагам, хранить состояние между итерациями и работать циклами, а не просто идти от начала к концу. По состоянию на август 2026 актуальная версия на PyPI 1.2.10, скачивается больше 16 миллионов раз в неделю. В статье разберем архитектуру графов, чем LangGraph отличается от обычного LangChain, и соберем минимального рабочего агента с нуля.

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

На портале уже выходила статья про LangChain на Python: там разобраны линейные и ветвящиеся цепочки вызовов, RAG и работа с документами. LangGraph не заменяет LangChain, а достраивает его там, где обычной цепочки не хватает.

Чем LangGraph отличается от LangChain?

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

LangChain технически представляет собой направленный ациклический граф, то есть цепочку без петель. Работает отлично для предсказуемых задач: скачал сайт, разбил текст на чанки через text splitter, сложил в векторную базу, ответил на вопрос. Как только нужен цикл, вроде «сгенерировал код, проверил, если не прошло, вернулся к генерации», линейная цепочка ломается.

LangGraph как раз про это. Разработчики закладывают в него полноценный граф с циклами и возвратами. У него другой набор строительных блоков, не document loader и chain, а узлы (nodes), ребра (edges) и общий объект состояния (state). Управление состоянием здесь на порядок мощнее: LangChain хранит в основном историю диалога через Memory, а в LangGraph состояние это типизированная структура, которую читает и обновляет каждый узел графа.

Кстати, между ними нет конкуренции. LangGraph построен поверх LangChain и часто используется вместе с ним: LangChain отвечает за вызовы моделей и промпты, LangGraph добавляет сверху слой оркестрации с памятью и циклами.

Как устроен граф из узлов, ребер и состояния?

Узел это функция на Python, которая получает текущее состояние, что-то делает (например, вызывает модель) и возвращает обновление. Ребро решает, какой узел выполнится следующим. Состояние это общий "блокнот", который видят все узлы графа.

Три сущности держат на себе всю архитектуру LangGraph: StateGraph как контейнер, узлы как обработчики и ребра как правила перехода. По состоянию на 2026 год именно эта тройка остается неизменным ядром библиотеки, несмотря на десятки минорных релизов за последний год.

Узел не хранит данные сам. Он читает состояние, выполняет действие, возвращает частичное обновление, а LangGraph сам сливает это обновление с общим состоянием. Ребра бывают двух типов: жесткие, которые всегда ведут из узла А в узел Б, и условные, которые проверяют текущее состояние и выбирают один из нескольких следующих узлов. Именно условные ребра дают графу способность ветвиться и зацикливаться.

Состояние в LangGraph описывается как типизированный словарь, обычно через TypedDict или Pydantic-схему. Так система заранее знает, какие поля хранятся и как они обновляются, поведение агента становится предсказуемым даже на сценариях из десятка узлов.

Зачем вообще нужны циклы в агенте?

Циклы нужны там, где результат первого прохода может оказаться неверным и требует повторной попытки: генерация кода с проверкой, research-агент с уточнением запроса, диалоговый ассистент, который переспрашивает пользователя.

Возьмем задачу: агент предлагает подтемы для исследования, пользователь отвечает да или нет, и в зависимости от ответа граф либо идет дальше искать документы, либо возвращается к генерации новых подтем. Без цикла эту логику пришлось бы городить костылями из отдельных запусков скрипта. С LangGraph это одно условное ребро.

Максим: «Мог просто засесть до пяти ночи и просто там править одну какую-то функцию, которая не работала. Но я понимал, что это можно решить и нужно решить, чтобы идти дальше.»

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

Как собрать минимального агента на LangGraph?

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

Ниже пошаговая сборка на Python. Установка через pip, дальше три блока кода: схема состояния, узлы и сборка графа.

pip install langgraph langchain-anthropic

Шаг 1. Опишите состояние через TypedDict. Здесь достаточно поля с вопросом пользователя, списком собранных подтем и флагом одобрения:

from typing import TypedDict, List

class AgentState(TypedDict):
    topic: str
    subtopics: List[str]
    approved: bool

Шаг 2. Напишите узлы как обычные функции. Каждая принимает состояние и возвращает словарь с обновлением:

from langgraph.graph import StateGraph, END
from langchain_anthropic import ChatAnthropic

model = ChatAnthropic(model="claude-sonnet-4-6")

def generate_subtopics(state: AgentState):
    response = model.invoke(f"Предложи 3 подтемы для: {state['topic']}")
    return {"subtopics": response.content.split("\n")}

def ask_approval(state: AgentState):
    answer = input(f"Подходят подтемы {state['subtopics']}? (yes/no): ")
    return {"approved": answer.strip().lower() == "yes"}

Шаг 3. Соберите граф, добавьте условное ребро и скомпилируйте:

builder = StateGraph(AgentState)
builder.add_node("generate", generate_subtopics)
builder.add_node("approve", ask_approval)
builder.set_entry_point("generate")
builder.add_edge("generate", "approve")
builder.add_conditional_edges(
    "approve",
    lambda s: END if s["approved"] else "generate",
)

graph = builder.compile()
graph.invoke({"topic": "вайбкодинг для новичков", "subtopics": [], "approved": False})

Если пользователь ответит "no", условное ребро вернет процесс на узел generate, а не завершит граф. Это и есть тот самый цикл, которого нет в обычной цепочке LangChain.

Когда выбрать LangGraph, а когда хватит LangChain?

Берите LangGraph, если в системе есть ветвления, повторы или несколько агентов, которые обмениваются состоянием. Для простого однопроходного RAG-бота без циклов LangGraph только усложнит код.

Для research-агента с уточняющими вопросами или системы код-ревью с циклом правок LangGraph подходит по умолчанию. Для бота, который просто суммирует сайт и отвечает на вопрос без переспросов, хватит обычного LangChain на Python, граф здесь только добавит лишний код без пользы.

Сколько стоит LangGraph и нужна ли платная подписка?

Сама библиотека LangGraph бесплатна и распространяется с открытым исходным кодом. Платят только за LangGraph Cloud или LangSmith, если нужны хостинг, трейсинг и мониторинг в продакшене.

По данным PyPI на август 2026, пакет langgraph устанавливается через обычный pip и тянет за собой langchain-core, langgraph-checkpoint, langgraph-prebuilt и langgraph-sdk. Для локальной разработки этого достаточно, никакого API-ключа для самой библиотеки не нужно, платить придется только за токены LLM, которую вы подключите к узлам.

Отдельно есть LangGraph CLI для запуска сервера разработки с горячей перезагрузкой и LangSmith для визуализации графа и отладки сложных цепочек узлов. Для учебного проекта или MVP это не обязательно, для продакшен-агента с десятком узлов уже сильно облегчает жизнь.

Термины LangGraph простыми словами

Частые вопросы про LangGraph

LangGraph это часть LangChain или отдельная библиотека?
LangGraph сделан командой LangChain Inc и построен поверх LangChain, но устанавливается отдельным пакетом и может работать без него. На практике их почти всегда используют вместе.

Нужно ли знать LangChain, чтобы начать с LangGraph?
Не обязательно, но полезно. Базовые понятия вроде промптов и вызова модели переносятся напрямую, а вот структура графа, узлы и состояние это уже отдельная логика, специфичная для LangGraph.

Чем LangGraph отличается от LangFlow?
LangFlow это визуальный low-code конструктор поверх LangChain для быстрого прототипирования мышкой. LangGraph требует кода на Python и подходит для продакшен-систем, а не только для MVP.

Можно ли использовать LangGraph без LangSmith?
Да, LangSmith нужен только для мониторинга и отладки. Для простого проекта без сложной аналитики его можно вообще не подключать.

Какая модель лучше всего подходит для узлов LangGraph?
Зависит от задачи узла. Для сложной архитектурной логики чаще берут Claude Opus, для рутинных шагов вроде генерации подтем достаточно более легкой и дешевой модели.

Сколько времени нужно, чтобы собрать первого агента?
Минимальный граф из двух узлов, как в примере выше, собирается за 15-20 минут, если модель и API-ключ уже настроены.

LangGraph подходит для мультиагентных систем?
Да, это одна из его основных ниш. Разные агенты можно представить отдельными узлами одного графа, которые обмениваются данными через общее состояние.

Итог: кому в 2026 году реально нужен LangGraph

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

Если хотите не собирать агентов вручную, а сразу писать промпты голосом в готовой AI IDE, посмотрите обзор Claude Code в каталоге VibeCoderz, а логику мультиагентных систем разберите подробнее в статье про мультиагентную оркестрацию. Полный каталог инструментов для вайбкодинга смотрите в каталоге AI IDE, а если нужна помощь с архитектурой конкретного проекта, запишитесь на консультацию к Максиму.

Источники: официальная документация LangGraph, репозиторий LangGraph на GitHub, страница пакета на PyPI.

Обновлено: август 2026