LangGraph: фреймворк для графовых агентов¶

LangGraph — это программная библиотека с открытым исходным кодом на языке Python, предназначенная для создания, координации и управления состоянием многошаговых приложений на основе больших языковых моделей (LLM), в частности — агентных систем. Разработанная компанией LangChain, Inc., библиотека представляет архитектуру конечного автомата (stateful graph), где узлы графа выполняют функции (вызовы моделей, инструментов, логики), а рёбра определяют переходы между ними. LangGraph позиционируется как низкоуровневое решение для построения сложных, управляемых и отказоустойчивых агентов, в отличие от более высокоуровневых, но менее гибких цепочек (chains) из основного пакета LangChain.

¶История и происхождение

LangGraph появился как ответ на ограничения классического подхода LangChain, где логика приложения жёстко задавалась последовательностью (chain). В начале 2024 года компания LangChain, Inc. представила библиотеку как отдельный пакет, ориентированный на разработчиков, которым требуется точный контроль над циклом выполнения агента: возможность реализовывать циклы, ветвления, возвраты к предыдущим шагам и долговременное сохранение состояния. Ключевым стимулом стало распространение паттерна агентов-«исполнителей» (agent loop), когда модель многократно вызывает инструменты до достижения результата. LangGraph формализовал этот паттерн в виде графа, что упростило отладку, тестирование и масштабирование таких систем. Библиотека быстро стала основным инструментом экосистемы LangChain для продакшн-разработки, а в 2025 году её функциональность была интегрирована в единый пакет LangChain 1.0.

¶Основные концепции и архитектура

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

¶Граф, узлы и рёбра

Приложение описывается как граф (StateGraph). Узел (node) — это функция Python, которая принимает текущее состояние и возвращает обновление состояния. Узлы могут выполнять произвольный код: вызов языковой модели, обращение к внешнему API, выполнение кода, чтение базы данных. Рёбра (edges) определяют поток управления. В LangGraph существует несколько типов рёбер:

• Прямые рёбра — безусловный переход от одного узла к другому.
• Условные рёбра — переход, выбираемый динамически на основе текущего состояния (например, если модель считает, что задача решена, перейти к узлу завершения, иначе — к узлу вызова инструментов).

¶Состояние (State)

Центральное понятие — состояние, которое передаётся между узлами. Состояние представляет собой типизированную структуру данных (обычно TypedDict или объект с аннотациями типов). Оно может содержать список сообщений диалога, промежуточные результаты, метаданные. Узлы являются чистыми функциями состояния: они получают полное состояние и возвращают частичное обновление. Это обеспечивает детерминированность и возможность сериализации.

¶Компиляция и выполнение

После определения графа он компилируется в исполняемый объект (CompiledStateGraph). Компиляция проверяет корректность схемы, оптимизирует переходы и подготавливает граф к запуску. Выполнение графа происходит методом invoke(), который принимает начальное состояние и прогоняет его по узлам до достижения конечного узла. Поддерживаются также потоковые режимы (stream()), позволяющие выдавать промежуточные шаги в реальном времени.

¶Проверка и контроль (Checkpointing)

Критически важной функцией LangGraph является чекпойнтинг — автоматическое сохранение состояния после каждого шага выполнения. Это позволяет:

• восстанавливать выполнение после сбоев;
• реализовывать временные путешествия (time travel) — откат к любому предыдущему шагу;
• создавать многопользовательские и долгоживущие агенты, где состояние хранится в базе данных (например, Postgres, Redis, SQLite).

Чекпойнты хранятся в специальных хранилищах (checkpointer) и связываются с идентификаторами потоков (thread_id).

¶Ключевые возможности и паттерны

LangGraph предоставляет встроенные абстракции для решения типовых задач агентной разработки.

¶Агент-исполнитель (ReAct-паттерн)

Библиотека позволяет реализовать классический цикл агента: модель рассуждает (Reason), вызывает инструменты (Act), получает результаты и повторяет процесс. Вместо ручного написания цикла используется граф с условными рёбрами, который автоматически завершается при наличии финального ответа.

¶Хуки и переопределение поведения

Разработчик может переопределить стандартное поведение модели, добавив кастомные узлы до или после вызова LLM. Это позволяет внедрять модерацию контента, валидацию ответов, логирование, системы безопасности.

¶Параллельное выполнение и супервизор

LangGraph поддерживает параллельные ветви (fan-out/fan-in), когда несколько узлов выполняются одновременно, а затем их результаты объединяются. Также реализуется паттерн супервизора (supervisor), где одна модель управляет работой нескольких подчинённых агентов, распределяя задачи.

¶Долговременная память и сохранение контекста

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

¶Генерация с подкреплением (Reflection)

Паттерн, при котором агент генерирует ответ, затем второй узел (критик) оценивает его и возвращает обратно для улучшения. Цикл повторяется заданное число раз или до достижения критерия качества.

¶Применение и экосистема

LangGraph применяется для создания:

• агентных систем — автономных помощников, решающих многошаговые задачи (бронирование, анализ данных, написание кода);
• пайплайнов обработки документов — извлечение, суммаризация, генерация ответов по базе знаний;
• систем автоматизации рабочих процессов — интеграция LLM с корпоративными инструментами (CRM, ERP);
• исследовательских прототипов — для экспериментов с новыми архитектурами агентов.

Экосистема включает дополнительные пакеты: LangGraph Platform (облачный сервис для деплоя графов), LangGraph CLI (инструмент командной строки), интеграции с LangSmith (мониторинг и отладка), LangMem (управление памятью) и LangGraph Code Assistant (генерация кода по описанию).

¶Сравнение с альтернативами

LangGraph конкурирует с другими фреймворками оркестрации агентов, такими как Microsoft AutoGen, CrewAI, LlamaIndex Workflows. Отличительными чертами LangGraph являются:

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

Недостатками считаются более высокий порог входа и необходимость писать больше кода для простых сценариев по сравнению с высокоуровневыми библиотеками.

¶Критика и ограничения

Основные замечания разработчиков касаются сложности отладки графов при большом количестве узлов, а также документирования, которое местами отстаёт от быстро меняющегося API. Некоторые эксперты отмечают, что концепция «чистых функций состояния» накладывает ограничения на использование несериализуемых объектов (например, открытых сетевых соединений) внутри узлов. Кроме того, привязка к экосистеме LangChain может быть избыточной для проектов, использующих только OpenAI SDK.

¶Литература и источники

1. Документация LangGraph (docs.langchain.com/langgraph).
2. Официальный репозиторий LangGraph на GitHub (langchain-ai/langgraph).
3. Блог LangChain: анонсы и руководства (blog.langchain.com).
4. Книга «LangChain в действии» (Practical LangChain), 2024.