LangGraph: создание AI-агентов на Python

AI-агенты — это программы, которые сами решают, какие действия выполнить для достижения цели: написать код, сходить в API, прочитать документ, вызвать другого агента. LangGraph от LangChain — самый популярный фреймворк для таких систем (больше 35 тысяч звёзд на GitHub по данным официального репозитория). Он даёт графовую архитектуру с состоянием, циклами и условной маршрутизацией — то, чего не хватает обычным цепочкам.

Что такое LangGraph и зачем он нужен

Обычные LLM-приложения работают как конвейер: запрос → LLM → ответ. Но реальные задачи требуют циклов — агент должен сам решить, нужен ли ему ещё один вызов модели, пора ли вызывать инструмент или ответ готов. LangGraph решает эту проблему через графовую модель: вы описываете узлы (nodes) — шаги, которые может выполнить агент, и рёбра (edges) — правила перехода между ними.

По прогнозу Gartner, к концу 2026 года 40% корпоративных приложений будут включать AI-агентов — против менее 5% в 2025 году. LangGraph занимает центральное место в этом стеке: его используют Klarna, Replit, Elastic, J.P. Morgan. Аналитики оценивают CAGR рынка AI-агентов в 48.5% с объёмом сервисных затрат $10.9–12.1 млрд.

Ключевое отличие LangGraph от других фреймворков — в первую очередь состояние. Каждый шаг агента сохраняет и обновляет объект состояния (TypedDict), который передаётся между узлами. Это позволяет строить сложную логику: агент пишет код → компилирует → читает ошибку → исправляет → снова компилирует. Всё это — один граф с циклическими переходами.

Если посмотреть на рынок фреймворков 2026 года, LangGraph остаётся самым низкоуровневым и гибким инструментом. CrewAI даёт высокоуровневую абстракцию «ролей» (исследователь, писатель, ревьювер), но скрывает детали переходов. AutoGen от Microsoft фокусируется на диалогах между агентами, но его сложно кастомизировать под нестандартные сценарии. LangGraph, напротив, требует вручную описать каждый переход — и именно поэтому даёт полный контроль над поведением агента.

На практике это означает, что вы не ограничены шаблонами. Хотите, чтобы агент делал ровно три попытки исправить код перед тем, как запросить помощь человека? Пишете conditional edge с счётчиком. Нужно, чтобы два агента работали параллельно, а третий собирал их результаты? Fan-out через Send API. LangGraph не угадывает ваши намерения — он исполняет то, что вы написали. Для продакшен-систем, где каждая лишняя итерация LLM стоит денег, это преимущество, а не недостаток.

Архитектура: StateGraph, узлы и рёбра

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

На схеме видно, как работает цикл: после вызова LLM маршрутизатор решает, нужен ли инструмент. Если да — исполняется узел инструмента, результат возвращается в LLM. Если нет — агент завершает работу и выдаёт ответ.

Важно, что граф может содержать сколько угодно узлов. Для простого агента достаточно двух (LLM и инструменты). Для сложного — пять-шесть: парсер ввода, классификатор запроса, генератор плана, исполнитель, валидатор. Каждый узел — отдельная Python-функция, которую можно тестировать изолированно.

Состояние (State) — это TypedDict, который вы определяете сами. Типичный набор полей:

from typing import TypedDict, Annotated, Sequence
from langgraph.graph import StateGraph, add_messages

class AgentState(TypedDict):
    messages: Annotated[list, add_messages]
    next_step: str
    tool_results: dict

Аннотация add_messages — встроенный редьюсер LangGraph, который умеет добавлять новые сообщения к списку, вместо того чтобы заменять их. Это критически важно для диалоговых агентов.

Установка и первый агент

LangGraph ставится через pip. Минимальный набор — сам LangGraph и провайдер LLM:

pip install langgraph langchain-openai

Вот простейший агент, который вызывает LLM и возвращает ответ. Это «Hello, world» от мира LangGraph:

from langgraph.graph import StateGraph, START, END
from langchain_openai import ChatOpenAI

# Состояние агента
class SimpleState(TypedDict):
    messages: Annotated[list, add_messages]

# Узел — вызов LLM
def call_model(state: SimpleState):
    llm = ChatOpenAI(model="gpt-4")
    response = llm.invoke(state["messages"])
    return {"messages": [response]}

# Собираем граф
builder = StateGraph(SimpleState)
builder.add_node("model", call_model)
builder.add_edge(START, "model")
builder.add_edge("model", END)

# Компилируем и запускаем
graph = builder.compile()
result = graph.invoke({
    "messages": [("human", "Расскажи про AI-агентов")]
})
print(result["messages"][-1].content)

Три строчки регистрации узла и два ребра — и агент работает. START и END — это специальные узлы, которые обозначают начало и конец графа. Между ними может быть сколько угодно узлов и переходов.

Важный момент: граф нужно скомпилировать вызовом .compile(). В этот момент LangGraph проверяет, что все узлы связаны, нет тупиков, и типы данных согласованы. При ошибках — падает с понятным сообщением, а не в рантайме.

Инструменты и условная маршрутизация

Обычная цепочка LLM → ответ — не агент. Агент начинается там, где модель решает, какой инструмент вызвать и нужно ли вызывать его повторно. LangGraph делает это через условные рёбра (conditional edges).

Добавим инструмент — функцию, которая ищет информацию в базе знаний:

from langchain_core.tools import tool

@tool
def search_knowledge_base(query: str) -> str:
    """Поиск информации в базе знаний компании."""
    # В реальности — вызов векторной БД или API
    return f"Результаты по запросу: {query}"

tools = [search_knowledge_base]
llm_with_tools = llm.bind_tools(tools)

Теперь добавим условное ребро — функция, которая смотрит на ответ модели и решает, куда идти дальше:

def router(state: AgentState) -> str:
    messages = state["messages"]
    last = messages[-1]
    if hasattr(last, "tool_calls") and last.tool_calls:
        return "tools"
    return END

# Строим граф
builder.add_node("agent", call_model)
builder.add_node("tools", execute_tools)
builder.add_conditional_edges("agent", router, {
    "tools": "tools",
    END: END
})
builder.add_edge("tools", "agent")  # после инструмента — снова к LLM
builder.add_edge(START, "agent")

Агент работает по циклу: LLM → если нужен инструмент → выполняем → результат → снова LLM. И так до тех пор, пока модель не решит, что ответ готов. LangGraph поддерживает до 25 итераций по умолчанию (параметр recursion_limit).

Это и есть принципиальное отличие от обычного чат-бота. Чат-бот отвечает один раз. Агент может выполнить цепочку действий: прочитать документацию, написать SQL-запрос, выполнить его, проанализировать результат и только потом ответить пользователю.

Разберём чуть подробнее, как работает условная маршрутизация. Функция router получает текущее состояние и возвращает имя следующего узла. LangGraph вызывает эту функцию после каждого выполнения узла «agent». Если модель вернула tool_calls — идём в узел «tools», если нет — в END. Внутри execute_tools мы вызываем инструменты, кладём результат в состояние и возвращаем управление графу. Ребро из «tools» в «agent» замыкает цикл.

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

def smart_router(state: AgentState) -> str:
    last = state["messages"][-1]
    if not hasattr(last, "tool_calls") or not last.tool_calls:
        return "respond"
    tool_name = last.tool_calls[0]["name"]
    if tool_name == "search_knowledge":
        return "search_tool"
    elif tool_name == "calculate":
        return "calc_tool"
    elif tool_name == "send_email":
        return "email_tool"
    return "fallback"

Каждый узел — обычная Python-функция. Вы можете тестировать их по отдельности, писать юнит-тесты, логировать вход и выход. Для команды разработки это означает, что агента можно разрабатывать как любой другой софт: декомпозировать на функции, покрывать тестами, ставить брейкпоинты.

Multi-agent системы с LangGraph

Один агент справляется с простыми задачами. Но в реальных проектах нужна команда: исследователь собирает данные, код-агент пишет код, ревьювер проверяет, супервайзер координирует. LangGraph позволяет строить такие системы естественным образом — как граф, где каждый узел это отдельный агент.

Вот как выглядит многоагентная архитектура:

Каждый круглый узел на схеме — это полноценный агент со своим состоянием и инструментами. Оркестратор принимает запрос, понимает, какой агент для чего нужен, и делегирует задачу. Супервайзер проверяет результат и либо отправляет на доработку, либо финализирует.

Код типичного supervisor-узла:

class SupervisorState(TypedDict):
    task: str
    subtasks: list
    results: dict
    status: str

def supervisor_node(state: SupervisorState):
    """Распределяет подзадачи и собирает результаты."""
    llm = ChatOpenAI(model="gpt-4")
    # Анализируем, какие подзадачи нужны
    if state["status"] == "planning":
        subtasks = plan_subtasks(state, llm)
        return {"subtasks": subtasks, "status": "executing"}
    elif state["status"] == "reviewing":
        verdict = review_results(state, llm)
        return {"status": "approved" if verdict else "revise"}
    return state

# Каждый специализированный агент — отдельный граф
research_agent = create_research_agent()
code_agent = create_code_agent()
review_agent = create_review_agent()

Эта архитектура повторяет то, как работают команды разработки: планирование → параллельное исполнение → ревью → доработка → релиз. Разница в том, что вместо людей — AI-агенты, и цикл занимает секунды, а не дни.

Продакшн: контроль потока и отладка

LangGraph даёт несколько механизмов, которые критически важны в продакшене:

Recursion limit. По умолчанию граф выполняет не больше 25 шагов. Это защита от зацикливания: если агент бесконечно вызывает инструменты, он просто остановится. Параметр настраивается: graph.invoke(input, {"recursion_limit": 50}). На практике для большинства задач хватает 10-15 шагов. Если агент регулярно упирается в лимит — значит, логика маршрутизации написана неправильно, и инструменты вызываются по кругу без прогресса.

Прерывания. LangGraph поддерживает точки остановки — NodeInterrupt. Можно приостановить выполнение графа, дождаться подтверждения от человека и продолжить. Для корпоративных сценариев с human-in-the-loop это must-have. Например, агент готов отправить email с коммерческим предложением — но перед отправкой запрашивает одобрение менеджера. Граф ставится на паузу, ждёт внешнего сигнала и продолжает с того же места.

Логирование узлов. LangGraph включает встроенные хуки, которые логируют, какой узел запущен, сколько времени занял, какое состояние на входе и выходе. Это сильно упрощает отладку многокомпонентных систем. А если нужно больше — пишется кастомный callback, который шлёт метрики в Prometheus или логи в ELK.

Параллельные узлы. Можно запускать несколько узлов одновременно через «fan-out» рёбра — например, отправить запрос сразу к трём разным LLM и собрать результаты. Для задач, где важна скорость, это даёт существенный выигрыш. LangGraph использует Send() API для параллельного запуска: вы передаёте список узлов и состояние для каждого, граф выполняет их конкурентно, а потом собирает результаты в общий стейт.

Persistent state. В LangGraph можно подключить хранилище состояния — встроенный MemorySaver для SQLite или кастомный бэкенд под PostgreSQL. Это позволяет «заморозить» граф посередине выполнения, перезапустить сервер и продолжить с того же места. Для долгих агентов, которые работают часами (мониторинг, ETL, обработка документов), это indispensable.

Коротко

LangGraph — это не очередной абстрактный фреймворк, а инструмент для решения конкретной задачи: как сделать так, чтобы LLM не просто отвечала, а действовала. Графовая архитектура с состоянием, условные переходы, встроенная поддержка циклов, human-in-the-loop — всё это уже нужно бизнесу прямо сейчас, а не «когда-нибудь». 40% enterprise-приложений будут содержать AI-агентов к концу 2026 года по данным Gartner, и LangGraph — один из основных инструментов, на котором это строят.

Если вы хотите внедрить AI-агентов в свой бизнес — не обязательно разбираться во всём сами. Мы в N20 помогаем с архитектурой, разработкой и деплоем агентных систем под ключ. Напишите в Telegram — обсудим бесплатно.

Автор: N202 Research · Июнь 2026
Источники: LangGraph GitHub, LangGraph Docs, Habr: LangChain и LangGraph, Habr: курс по LangGraph, Real Python: LangGraph Tutorial, Enterprise AI Agents Statistics 2026