Как начать пользоваться LangGraph: фреймворк для production AI-агентов

LangGraph -- это Python и TypeScript фреймворк для создания AI-агентов с сохранением состояния. В отличие от простых цепочек промптов, агенты LangGraph умеют хранить контекст между шагами, делать паузу для проверки человеком, восстанавливаться после ошибок и продолжать работу с любой точки истории. Именно поэтому LangGraph выбирают для production-систем, а не только для прототипов и экспериментов.

В мае 2026 года вышла LangGraph 1.2.0 с content-block-aware стримингом, улучшённым interrupt() и полной поддержкой Python 3.10-3.14. 6 июля 2026 года выпущена версия 1.2.8 с DeltaChannel beta, обновлённым type-safe streaming v2 и более тонким контролем выполнения узлов. 10 июля 2026 года выпущена версия 1.2.9 с официальным выходом DeltaChannel из статуса beta, детализированными таймаутами узлов (параметры run_timeout и idle_timeout, пробрасывающие NodeTimeoutError) и node-level error handlers с восстановлением через Command. Ежемесячная аудитория запросов по LangGraph превысила 33 тысячи поисков в Google -- больше, чем у большинства других Python-фреймворков для агентов. Среди компаний, которые используют его в продакшене: Klarna (финансовые AI-агенты для клиентской поддержки), LinkedIn (алгоритмы рекомендаций контента), Uber (операционная автоматизация диспетчерских процессов) и Replit (AI-ассистент для написания и анализа кода).

Ключевая идея LangGraph: агент описывается как ориентированный граф. Каждый узел (node) -- это функция на Python, которая читает и модифицирует общее типизированное состояние (state). Рёбра (edges) определяют, какой узел вызывается следующим, и могут быть условными на основе текущего состояния. Например: если модель решила использовать инструмент поиска, выполнение переходит к узлу ToolNode; если ответ готов, граф завершается и возвращает результат пользователю. Каждый переход между узлами автоматически сохраняется через систему checkpoints, что делает агента устойчивым к сбоям и позволяет поддерживать долгосрочные многоходовые задачи.

Важно понимать, чем LangGraph отличается от других популярных фреймворков. Если CrewAI предлагает быстрый способ собрать команду из нескольких агентов через ролевые описания, то LangGraph даёт полный низкоуровневый контроль над потоком выполнения на уровне графа. Это сложнее для первоначального освоения, но значительно гибче и надёжнее в production-сценариях с требованиями к надёжности и восстанавливаемости.

Кому подойдёт LangGraph:

LangGraph не привязывает к конкретным LLM-провайдерам. Одна и та же логика агента работает с Claude, GPT, Gemini, Mistral или с локальными моделями через Ollama -- нужно лишь поменять импорт модели. Это удобно для экспериментов и для миграции между провайдерами без переписывания всей бизнес-логики.

LangGraph -- open-source библиотека под лицензией MIT, устанавливается через pip. Никакой регистрации для базового использования не нужно. Для мониторинга через LangSmith и для деплоя через LangGraph Platform потребуются аккаунты, но оба предоставляются бесплатно на базовом уровне.

Требования к системе. Тебе понадобится Python версии 3.10 или выше (рекомендуется 3.12 для наилучшей совместимости). Менеджер пакетов pip или более современная альтернатива uv. Виртуальное окружение -- venv или conda -- настоятельно рекомендуется, чтобы не засорять системный Python. Ключ API для выбранного LLM-провайдера: для Anthropic Claude -- ANTHROPIC_API_KEY, для OpenAI -- OPENAI_API_KEY.

Установка библиотек. Создай виртуальное окружение командой python -m venv .venv и активируй его: source .venv/bin/activate на Mac и Linux, .venv\Scripts\activate на Windows. Затем установи основные пакеты. Для работы с Claude: pip install langgraph langchain-anthropic. Для работы с OpenAI: pip install langgraph langchain-openai. Для production с PostgreSQL-checkpointer дополнительно: pip install langgraph-checkpoint-postgres psycopg[binary].

Настройка переменных окружения. Создай файл .env в корне проекта. Добавь ключ нужного провайдера в формате ANTHROPIC_API_KEY=sk-ant-... или OPENAI_API_KEY=sk-... Загружай переменные в скрипте через python-dotenv: pip install python-dotenv, затем from dotenv import load_dotenv; load_dotenv() в начале кода. Для LangSmith добавь LANGCHAIN_API_KEY и LANGCHAIN_TRACING_V2=true -- тогда все запуски будут автоматически логироваться.

LangGraph CLI и Studio. CLI позволяет запускать LangGraph Studio -- визуальный отладчик. Установи: pip install langgraph-cli. Для запуска Studio в папке с проектом выполни: langgraph dev. Откроется браузерный интерфейс на localhost:8000, где ты увидишь граф агента в виде диаграммы, текущее состояние и историю переходов. Это незаменимо при разработке и отладке сложных агентов.

Проверка установки. Запусти: python -c "import langgraph; print(langgraph.__version__)". Если вывелась версия 1.2.x или выше -- установка успешна и можно приступать к первому агенту.

Начнём с классического ReAct-агента с памятью между разговорами. ReAct расшифровывается как Reasoning + Acting -- агент чередует размышления и конкретные действия, что делает логику прозрачной. Это самый распространённый паттерн для агентов-ассистентов.

Создай простейшего агента через prebuilt. LangGraph предоставляет create_react_agent -- готовый пресет, который инкапсулирует стандартный граф ReAct. Тебе нужно передать только модель и список инструментов. Создай экземпляр ChatAnthropic с нужной моделью, например claude-opus-4-8. Для инструментов в учебных целях подойдёт простая Python-функция, помеченная декоратором @tool из langchain_core.tools -- например, функция get_weather, которая принимает город и возвращает строку с погодой (для теста можно вернуть любую захардкоженную строку). Передай функцию в список tools, создай агента через create_react_agent(model, tools) и вызови invoke.

Важно: устаревший импорт langgraph.prebuilt. В актуальных версиях LangGraph модуль langgraph.prebuilt объявлен устаревшим (deprecated). Функция create_react_agent и другие prebuilt-компоненты перемещены в langchain.agents. Если в вашем коде есть строка from langgraph.prebuilt import create_react_agent -- замените её на from langchain.agents import create_react_agent. Старый импорт пока работает, но будет удалён в следующей мажорной версии. При запуске агента обращайте внимание на DeprecationWarning в консоли -- они укажут на устаревшие импорты, которые нужно обновить.

Добавь память через MemorySaver. Без checkpointer агент не помнит предыдущих сообщений -- каждый вызов invoke начинается с нуля. Импортируй MemorySaver из langgraph.checkpoint.memory, создай экземпляр и передай его в create_react_agent как параметр checkpointer. Теперь при каждом вызове передавай config -- словарь вида {"configurable": {"thread_id": "уникальный-id-сессии"}}. LangGraph автоматически сохранит историю и загрузит её при следующем вызове с тем же thread_id. Проверь: в первом сообщении представься по имени, во втором спроси агента, как тебя зовут -- он должен вспомнить.

Переход к ручному графу. Prebuilt удобен для старта, но для нестандартных задач создавай граф вручную через StateGraph. Определи TypedDict с полями состояния -- как минимум поле messages типа list с аннотацией add_messages из langgraph.graph. Добавь узлы: функцию call_model (вызывает LLM) и ToolNode (выполняет инструменты). Добавь условное ребро: если последнее сообщение содержит вызов инструмента -- перейди в ToolNode, иначе завершись. Скомпилируй граф методом compile(checkpointer=checkpointer). Это стандартный паттерн для большинства агентов.

LangGraph Studio для отладки. Запусти langgraph dev, открой localhost:8000 в браузере и выбери свой граф. Слева ты увидишь диаграмму с узлами и рёбрами. Отправь сообщение через встроенный чат -- и Studio пошагово покажет, как граф выполнялся: какой узел был вызван, какие данные передавались, что ответила модель. Функция time-travel позволяет кликнуть на любое историческое состояние и возобновить выполнение с него -- это делает отладку ошибок в агентах принципиально проще, чем добавление print-ов по всему коду.

Checkpoint-система для надёжности. Это главная особенность LangGraph. Каждый переход между узлами графа автоматически персистируется через checkpointer. Это даёт возможность паузы с сохранением (агент остановился и ждёт человека -- работа продолжится при следующем вызове), восстановления после сбоя (сервер рухнул посреди задачи -- агент возобновит с последнего сохранённого шага), и time-travel debugging (откат к любому прошлому состоянию для анализа). Для production используй PostgreSQL или Redis checkpointer, для локальной разработки достаточно MemorySaver.

Human-in-the-loop через interrupt(). Функция interrupt() позволяет агенту остановиться в определённом месте графа и дождаться подтверждения от человека. Это особенно критично для агентов, выполняющих необратимые действия: отправка email, запись в базу данных, перевод средств, изменение файлов. Агент показывает предполагаемое действие и ждёт команды «продолжить» или «отменить». В LangGraph 1.2 семантика interrupt() улучшена -- паузу можно делать в любом узле без специальной подготовки графа.

Стриминг событий в реальном времени. Метод stream (вместо invoke) возвращает генератор событий. Каждое событие -- это обновление состояния конкретного узла. Можно подписаться только на нужные типы событий: updates (финальный результат каждого шага), messages (токены по мере генерации LLM), custom (кастомные события из своего кода). Это позволяет строить UI с прогрессом выполнения без опроса сервера.

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

Нативная поддержка MCP. LangGraph интегрирован с экосистемой Model Context Protocol. Любой MCP-сервер -- для работы с файловой системой, браузером, базой данных, сторонними API -- подключается как набор инструментов агента. Это открывает доступ к сотням готовых интеграций без необходимости писать обёртки вручную.

DeltaChannel, per-node timeouts и error handlers (LangGraph 1.2.8-1.2.9). DeltaChannel -- механизм инкрементальных обновлений состояния для агентов с длинными рабочими потоками: вместо сохранения полного состояния при каждом переходе записывается только разница. Впервые появился в beta в версии 1.2.8, а в версии 1.2.9 (10 июля 2026 года) вышел из статуса beta -- теперь он полностью поддерживается во всех проектах без предупреждений об изменении API. Это существенно снижает нагрузку на checkpointer при работе с большими объёмами данных в контексте. Per-node timeouts в версии 1.2.9 стали детальнее: вместо одного параметра timeout теперь доступны run_timeout (максимальное время активного выполнения узла) и idle_timeout (максимальное время ожидания между внутренними операциями). При превышении любого из них выбрасывается NodeTimeoutError, который можно поймать и обработать отдельно. Настройка: graph.add_node("fetch_data", fetch_data, run_timeout=30.0, idle_timeout=10.0). Node-level error handlers -- новый механизм в 1.2.9 для восстановления после сбоя узла: когда узел исчерпал все попытки retry, вместо падения всего графа вызывается функция-обработчик. Она получает текущее состояние и исключение, и может вернуть Command с маршрутом к резервному узлу. Это делает обработку ошибок явной и управляемой без усложнения логики самого узла.

Type-safe streaming v2 API. В LangGraph 1.2.8 доработан стриминговый API с типобезопасными событиями. Вместо разбора сырых словарей используются типизированные модели: StreamEvent, NodeStartEvent, NodeEndEvent, ToolCallEvent. Это делает код стриминга читаемым и позволяет ловить ошибки на уровне линтера, а не в runtime. Используется через stream_mode="events" в методе astream_events. Миграция с v1: основные паттерны stream и invoke работают без изменений, типизированный API -- опциональное улучшение для новых проектов.

LangGraph как библиотека полностью бесплатен и open-source под лицензией MIT. Платишь только за вызовы к LLM-провайдерам -- это стандартные API-тарифы OpenAI или Anthropic, никак не связанные с LangGraph.

LangSmith (мониторинг и трассировка): Бесплатный план -- 5000 трасс в месяц и основная аналитика. Платные планы от примерно 39 долларов в месяц (актуальные цены смотри на smith.langchain.com/pricing) -- расширенное логирование, командный доступ, удержание данных, расширенные фильтры поиска по трассам и сравнение версий агентов.

LangGraph Platform (деплой и хостинг): Self-hosted вариант бесплатен -- разворачиваешь Docker-образ на собственном сервере командой langgraph build, потом запускаешь контейнер. Managed Cloud вариант (Google Cloud под капотом) стартует от нескольких сотен долларов в месяц в зависимости от нагрузки. Для большинства стартапов и малых команд self-hosted на VPS в 10-20 долларов в месяц вполне достаточно.

Ограничения: Порог входа выше, чем у более высокоуровневых фреймворков -- концепция типизированного состояния и условных рёбер требует времени на освоение. Для простых однотуровых агентов без персистентного состояния LangGraph избыточен. Документация обширная, но разбросана между docs.langchain.com, langchain-ai.github.io и видеотуториалами -- найти конкретный пример с первого раза непросто. Рекомендуем начинать с официального 45-минутного туториала на сайте LangChain.

LangGraph -- это библиотека, работающая локально на твоём компьютере или сервере. Установка через pip работает в России без ограничений, исходный код на GitHub тоже доступен без VPN. Весь процесс разработки агентов можно вести без VPN при условии использования провайдеров, доступных в России.

Что может потребовать VPN или зарубежного сервера:

Практический совет: начни разработку локально, используя Anthropic API через VPN или локальные модели через Ollama. Это даст полноценный опыт работы с LangGraph без зависимости от сетевых ограничений. Для production выбирай зарубежный сервер с нужными API-провайдерами.

В 2026 году LangGraph достиг статуса General Availability (GA) со стабильным релизом версии 1.0. Это означает гарантию обратной совместимости API -- код, написанный для LangGraph 1.0, будет работать в последующих версиях без изменений.

Критическое изменение в импортах: модуль langgraph.prebuilt объявлен устаревшим (deprecated). Вместо него необходимо использовать отдельный пакет langgraph_prebuilt. Если в коде есть строки вида from langgraph.prebuilt import ..., их нужно обновить до from langgraph_prebuilt import .... Установка: pip install langgraph-prebuilt.

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

Этот материал подготовлен командой AI-агентов AravanaAI и проверен главным редактором.