LangChain по слоям: как устроен стек 2026 года — от create_agent до среды исполнения LangGraph

LangChain в 2026 году — это три открытые библиотеки на одной среде исполнения и LangSmith вокруг них. Даже агент, которого возвращает create_agent, компилируется в граф LangGraph. В опросе Stack Overflow 2026 LangChain — самый используемый агентный фреймворк, 30,2%, у LangGraph 18,8%, а в нашем рейтинге десяти фреймворков по реальным внедрениям стек занимает первое место. Ниже он разобран по слоям, от вызова агента до среды исполнения, которая его выполняет. Всё сверено с документацией и кодом Python-пакета langgraph 1.2.16 от 16 октября 2026 года; у JavaScript-версии @langchain/langgraph своя нумерация (1.5.2) и часть значений по умолчанию другая.

Коротко

• Четыре слоя: LangGraph (среда исполнения), LangChain 1.x (слой агентов), Deep Agents (обвязка для долгих задач) и LangSmith (трассировка, оценки, деплой). Три библиотеки — MIT, LangSmith — коммерческий сервис.
• create_agent принимает модель, инструменты, промпт, middleware и формат ответа и возвращает скомпилированный граф. Шесть хуков middleware встраиваются в цикл.
• Граф — это состояние с редьюсерами, узлы и рёбра. Среда исполнения выполняет его супершагами и сохраняет чекпоинт на границе каждого шага.
• interrupt() ставит прогон на паузу до решения человека; при продолжении узел перезапускается с начала.
• Где подводит: Command вместе с постоянным ребром запускает оба маршрута, работающие потоки подхватывают новый код, чекпоинты — поверхность атаки.
• В России стек работает с GigaChat через langchain-gigachat, а в закрытом контуре — без LangSmith, на своём Postgres.

01 · Стек: три библиотеки, одна среда исполнения

Источник: документация LangGraph и LangChain, октябрь 2026.

Слой	Что делает	Лицензия
LangGraph	Среда исполнения: состояние, граф, чекпоинты, прерывания, стриминг	MIT, langgraph 1.2.16
LangChain 1.x	Слой агентов: create_agent, middleware, модели, инструменты, сообщения	MIT
Deep Agents	Обвязка для долгих задач: планирование, субагенты, файловые инструменты, управление контекстом	MIT
langchain-core	Общие интерфейсы моделей, сообщений и инструментов	MIT
LangSmith	Трассировка, оценки, промпты и деплой для любого фреймворка	Коммерческая

Документация формулирует связь прямо: LangChain 1.0 построен поверх LangGraph, а «чтобы пользоваться LangChain, знать LangGraph не нужно». Обратное тоже верно: LangGraph можно использовать без LangChain, хотя сам пакет langgraph зависит от langchain-core.

Какой слой нужен вам. Агент с инструментами, промптом и при необходимости структурированным ответом — create_agent. Свой процесс с ветвлениями, параллельными шагами и своим состоянием — StateGraph. Долгие открытые задачи с планом, субагентами и файлами — Deep Agents. Трассировка, оценки и хостинг для любого из них или для другого фреймворка — LangSmith.

02 · Слой агентов: create_agent и middleware

Источник: release notes LangChain 1.0 и документация middleware.

LangChain 1.0 заменил старый create_react_agent из LangGraph на create_agent(model, tools, system_prompt, middleware, response_format, context_schema). Он собирает привычный цикл «модель — инструменты — снова модель» и возвращает скомпилированный граф LangGraph. Если передать чекпоинтер, сохранение состояния, стриминг, подтверждения и откат к прошлым шагам вы получаете, не написав ни одного узла.

В release notes middleware названы главной особенностью create_agent. Шесть хуков позволяют встроиться в цикл: before_agent и after_agent вокруг всего прогона, before_model и after_model вокруг каждого вызова модели, wrap_model_call и wrap_tool_call, которые оборачивают сами вызовы. Отдельной среды исполнения у middleware нет: хуки работают внутри скомпилированного графа. Среди готовых middleware — маскирование персональных данных, сжатие истории, подтверждение человеком, повторы вызовов инструментов и модели, переключение на запасную модель и лимиты вызовов. Для подтверждений нужен чекпоинтер.

Ещё три изменения 1.0 важны в повседневной работе. Структурированный ответ теперь получается в основном цикле, без дополнительного вызова модели. У сообщений появилось поле content_blocks — единый способ читать новые возможности моделей у разных провайдеров. А старые цепочки (chains), ретриверы и hub переехали в пакет langchain-classic: импорт langchain.chains превращается в langchain_classic.chains.

03 · Граф: что вы описываете

Источник: документация Graph API LangGraph.

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

• Состояние — типизированная схема, обычно TypedDict. У каждого ключа свой редьюсер, который решает, как сливаются обновления: add_messages дописывает сообщения в список, а ключ без редьюсера перезаписывается последним значением.
• Узлы — обычные функции, синхронные или асинхронные. Читают состояние, возвращают обновление.
• Рёбра выбирают следующий шаг: add_edge — постоянный переход, add_conditional_edges — функция маршрутизации.

Тот же цикл, который даёт create_agent, собирается в семь строк:

builder = StateGraph(State)
builder.add_node("model", call_model)
builder.add_node("tools", run_tools)
builder.add_edge(START, "model")
builder.add_conditional_edges("model", route)
builder.add_edge("tools", "model")
graph = builder.compile(checkpointer=saver)

Для остальной маршрутизации есть три инструмента. Send раздаёт работу одному узлу с разными входами, в духе map-reduce. Command одним возвратом обновляет состояние и переходит в нужный узел. Подграф — скомпилированный граф в роли узла: добавленный напрямую, он делит ключи состояния с родителем; вызванный внутри узла, сохраняет свою схему. В обоих случаях у подграфа своё пространство чекпоинтов, поэтому родитель может увидеть его обновления не сразу.

У одной среды исполнения два способа описать процесс. Graph API — явный граф: подходит для ветвлений, параллельных путей со слиянием и команд, которые читают схемы. Functional API (@entrypoint, @task) оставляет обычный поток управления Python и подходит для линейного кода, который не хочется переписывать, но визуализировать такой процесс нельзя.

04 · Среда исполнения: супершаг за супершагом

Источник: документация среды исполнения LangGraph (Pregel).

Компиляция графа даёт объект Pregel — среду исполнения. Она работает по модели Bulk Synchronous Parallel; автор выбрал её за детерминированный параллелизм и полную поддержку циклов. Каждый супершаг — три фазы:

1. План: выбрать узлы, подписанные на каналы, которые изменились на прошлом шаге.
2. Исполнение: запустить их параллельно. Записи узлов друг другу не видны до следующего шага.
3. Обновление: применить записи к каналам состояния через редьюсеры.

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

Лимит рекурсии задавайте явно в config и следите за ним через RemainingSteps. На значение по умолчанию не полагайтесь: документация и код сейчас называют разные числа.

05 · Память: чекпоинты, потоки и store

Источник: документация LangGraph о персистентности и чекпоинтерах.

Чекпоинтер сохраняет состояние на границе каждого супершага под thread_id — первичным ключом разговора (потока). Один механизм даёт четыре возможности: продолжение после сбоя, подтверждения человеком, память разговора и откат к прошлым шагам. Если в шаге один узел завершился ошибкой, записи остальных сохраняются как отложенные, и при продолжении перезапускается только он.

Режим durability	Когда пишет	Если процесс упал
exit	Только в конце прогона	Промежуточное состояние потеряно
async (по умолчанию)	Пока идёт следующий шаг	Последний шаг может потеряться
sync	До начала следующего шага	Каждый законченный шаг сохранён, ценой задержки

InMemorySaver и SQLite — для разработки, для рабочей системы документация рекомендует PostgresSaver. Запускайте setup() отдельным шагом миграции, держите thread_id короче 255 символов и чистите старые чекпоинты: на длинных разговорах они накапливаются. По умолчанию каждый чекпоинт хранит каждый канал целиком; DeltaChannel (бета с 1.2) хранит только изменения.

Store — вторая память: долговременные данные, общие для всех потоков, с адресом из namespace и ключа и необязательным семантическим поиском. Поток помнит разговор, store — пользователя.

Откат к прошлым шагам позволяет повторить или разветвить прогон с любого чекпоинта. При повторе результаты не берутся из кэша: вызовы модели и API выполняются заново.

06 · Человек в контуре

Источник: документация LangGraph о прерываниях.

interrupt(payload) ставит граф на паузу, сохраняет состояние и отдаёт payload вызывающему коду. Через часы или дни graph.invoke(Command(resume=value), config) с тем же thread_id продолжает прогон, и value становится результатом interrupt().

Подвох описан в документации: при продолжении среда исполнения перезапускает весь узел с начала. Со строки, где был вызван interrupt(), выполнение не продолжается. Письмо, отправленное до паузы, уйдёт дважды. Отсюда пять правил:

1. Побочные эффекты до interrupt() делайте идемпотентными или переносите после него.
2. Не оборачивайте interrupt() в try/except: пауза устроена как исключение, и если его перехватить, пауза не сработает.
3. Не меняйте порядок нескольких прерываний в узле: ответы сопоставляются по номеру.
4. Не ставьте interrupt() в цикл while: каждое продолжение заново проигрывает все прошлые итерации.
5. Статические точки останова (interrupt_before, interrupt_after) — только для отладки.

07 · Стриминг и сбои

Стриминг показывает тот же цикл: values (всё состояние после шага), updates (что изменил каждый узел), messages (токены модели), custom (ваши события), а с чекпоинтером ещё checkpoints и tasks. В 1.2 появился event streaming с типизированными проекциями, его документация советует для новых приложений.

Сбои документация разводит по типам: временные ошибки вроде сетевых сбоев и лимитов — RetryPolicy на узле; ошибки, которые может исправить модель, — в состояние и снова в цикл; ошибки, которые должен исправить человек, — пауза через interrupt(); неожиданные — пусть всплывают. С 1.2 у узла может быть таймаут (только у асинхронных) и error_handler, который срабатывает после исчерпания повторов. Прерывания не проходят ни через повторы, ни через error_handler.

08 · Deep Agents и деплой

Источник: документация LangSmith Agent Server и отдельного сервера.

Deep Agents — обвязка поверх LangGraph для долгой открытой работы: планирование, субагенты, файловые инструменты и управление контекстом. По кейсу в блоге LangChain, Rippling держит на ней супервизора с субагентами для более чем миллиона пользователей.

Деплой идёт через LangSmith Agent Server. PostgreSQL — главное хранилище: ассистенты, потоки, прогоны, чекпоинты и store. Redis отвечает только за сигналы, отмену и стриминг и данных прогонов не хранит. API-серверы без состояния создают прогоны, воркеры без состояния их забирают, причём в одном потоке одновременно идёт не больше одного прогона. Чекпоинтер в коде графа при этом не настраивают: его подставляет сервер.

Библиотека открыта, хостинг — нет. Облачный деплой требует платного плана LangSmith, а даже отдельный сервер на своей инфраструктуре требует лицензионный ключ LangSmith. Ключ проверяется один раз при старте, а без режима air-gapped серверу нужен исходящий доступ к beacon.langchain.com для проверки лицензии и отчётов об использовании. Agent Server можно не использовать вовсе и запускать граф внутри своего сервиса со своим чекпоинтером на Postgres.

09 · Что это значит для команд в России

• GigaChat. Пакет langchain-gigachat от ai-forever — интеграция GigaChat с LangChain; версия 0.5.1 вышла 9 октября 2026 года (PyPI). Прежний пакет gigachain объявлен устаревшим: на PyPI его авторы советуют удалить пакеты gigachain-* и перейти на обычный langchain вместе с langchain_gigachat. Пакет рассчитан на langchain-core 1.x, поэтому GigaChat передаётся в create_agent или вызывается в узле как обычная чат-модель LangChain.
• Закрытый контур. Сама библиотека LangGraph не требует LangSmith: граф, чекпоинтер на своём Postgres и store работают внутри вашей инфраструктуры. Внешние зависимости появляются вместе с LangSmith — трассировкой, оценками и Agent Server, которому нужен лицензионный ключ, а без режима air-gapped ещё и проверка лицензии и отчёты об использовании у LangChain. Локальный сервер langgraph dev и Studio тоже требуют API-ключ LangSmith, а вызовы облачной модели, в том числе GigaChat по API, уходят наружу в любом случае. Для контура, где данные не должны уходить наружу, это решение уровня архитектуры, его стоит принять до первого деплоя.
• Подтверждения по образцу Т-Инвестиций. Т-Инвестиции открыли внешним ИИ-агентам доступ к брокерскому счёту через MCP с тремя уровнями прав и правилом: агент не выполняет операции без подтверждения человека (CNews, сентябрь 2026). Какой стек у них внутри, не раскрыто; в LangGraph такой шаг собирается из interrupt() перед узлом, который проводит операцию, и чекпоинтера, который хранит прогон, пока человек решает. Только помните про перезапуск узла: сама операция должна стоять после паузы.
• Контур контроля снаружи модели. По данным ComNews, Яндекс, МТС, Т1 и Сбер строят системы, которые ставят действия агента под контроль и при необходимости подключают человека; в Т1 говорят, что число запросов бизнеса на механизмы контроля ИИ-агентов за год выросло примерно втрое. Граф с явными узлами и паузами подходит для такого контура: каждый рискованный шаг виден на схеме и может остановиться для проверки.

10 · Где подводит и когда брать

Большую часть ловушек описывает сама документация.

• Command вместе с постоянным ребром запускает оба маршрута. Command только добавляет переходы, а рёбра из add_edge срабатывают всё равно.
• Работающие потоки подхватывают новый код. LangGraph сразу применяет последнюю версию графа ко всем потокам. После переименования или удаления узла потоки, остановленные на нём, перестают загружаться. Новые поля состояния делайте необязательными, а переименование проводите в два шага: сначала добавить, потом удалить.
• Повтор — не кэш. Вызовы модели и API выполняются снова.
• Чекпоинты — поверхность атаки. В langchain-core была уязвимость сериализации с оценкой CVSS 9.3, закрытая в 1.2.5. В langgraph-checkpoint исправили RCE в JSON-сериализаторе в 3.0.0 (CVE-2025-64439, срабатывает, когда в чекпоинт попадают недоверенные данные) и уязвимость десериализации в 4.1.1 (CVE-2026-48775, нужна запись в хранилище). Обновитесь до langgraph 1.2.16 (он требует langgraph-checkpoint не ниже 4.3.0 и langchain-core не ниже 1.4.7) или зафиксируйте langgraph-checkpoint не ниже 4.1.1; ограничьте запись в хранилище и шифруйте чекпоинты.

Независимые инженеры добавляют ещё один риск: фреймворк становится слоем между вашим кодом и бизнес-логикой. Инженеры LinkedIn поставили поверх LangGraph слой адаптеров для своего рекрутингового агента, чтобы сменить фреймворк относительно дёшево. В нашей CRM, AgenticCRM, чат-агент работает на StateGraph из LangGraph.

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

Пять настроек, которые стоит задать явно до запуска:

1. PostgresSaver с setup() как миграцией и задачей очистки старых чекпоинтов.
2. Режим durability для каждого графа, sync там, где потерянный шаг стоит денег.
3. Явный recursion_limit.
4. RetryPolicy на каждом узле, который ходит во внешний сервис.
5. Необязательные новые поля состояния, чтобы остановленные потоки загружались после деплоя.

Для сравнения — наш разбор OpenAI Agents SDK по частям.

FAQ

Чем LangChain отличается от LangGraph в 2026 году? LangGraph — среда исполнения: состояние, граф, чекпоинты, прерывания и стриминг. LangChain 1.x — слой агентов поверх неё: create_agent, middleware, модели, инструменты и сообщения. create_agent возвращает скомпилированный граф LangGraph, поэтому агент на LangChain работает на среде исполнения LangGraph.

Что такое супершаг в LangGraph? Одна итерация среды исполнения: выбрать узлы, которые нужно запустить, выполнить их параллельно, пока их записи не видны друг другу, и применить записи к каналам состояния. Узлы, которые идут параллельно, принадлежат одному супершагу, а чекпоинт сохраняется на его границе.

Почему после подтверждения узел LangGraph выполняется второй раз? Потому что при продолжении среда исполнения перезапускает весь узел с начала. Строка, где был вызван interrupt(), точкой продолжения не служит. Код до interrupt() выполняется снова, поэтому побочные эффекты в нём должны быть идемпотентными.

Нужен ли LangSmith, чтобы запускать LangGraph в работе? Для библиотеки — нет: LangGraph распространяется по лицензии MIT и работает с вашим чекпоинтером на Postgres. LangSmith нужен для его трассировки и оценок и для деплоя на Agent Server: даже отдельный Agent Server на своём сервере требует лицензионный ключ LangSmith.

Можно ли использовать LangChain с GigaChat? Да: пакет langchain-gigachat от ai-forever, версия 0.5.1 вышла 9 октября 2026 года. Прежний пакет gigachain объявлен устаревшим, его авторы советуют перейти на обычный langchain вместе с langchain_gigachat.

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