LangGraph — агент как граф состояний

LangGraph — открытый фреймворк оркестрации ИИ-агентов на Python от команды LangChain: поведение агента описывается графом, где узлы выполняют работу, рёбра выбирают следующий шаг, а состояние сохраняется между вызовами. Ставится командой pip install -U langgraph, лицензия MIT. Разбираем первый граф, память и чекпойнты, остановку на человеке, локальный сервер со Studio и подключение MCP-серверов. Проверено по официальной документации 19 августа 2026 года.

Часть 1 · Знакомство

Что такое LangGraph и где он в стеке

Документация называет LangGraph низкоуровневым фреймворком и рантаймом для долгоживущих агентов с состоянием. Ключевая мысль: в одном графе спокойно уживаются жёстко прописанные шаги и шаги, которые ведёт модель. Там, где нужна предсказуемость и аудит, стоит обычный код; там, где нужна гибкость, решает модель. Среди компаний, которые строят на нём агентов, документация называет Klarna, Uber и J.P. Morgan.

Часть 2 · Установка

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

pip install -U langgraph

# или через uv
uv add langgraph

# модели и инструменты обычно берут из LangChain (нужен Python 3.10+)
pip install -U langchain

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

from langgraph.graph import StateGraph, MessagesState, START, END

def mock_llm(state: MessagesState):
    return {"messages": [{"role": "ai", "content": "hello world"}]}

graph = StateGraph(MessagesState)
graph.add_node(mock_llm)
graph.add_edge(START, "mock_llm")
graph.add_edge("mock_llm", END)
graph = graph.compile()

graph.invoke({"messages": [{"role": "user", "content": "hi!"}]})

Часть 3 · Как устроен граф

Состояние, узлы и рёбра

• State. Общая структура данных, снимок текущего состояния приложения. Обычно описывается схемой, которую видят все узлы.
• Nodes. Обычные функции: получают состояние, делают работу или побочный эффект, возвращают обновление состояния. Внутри может быть вызов модели, а может — просто код.
• Edges. Функции, решающие, какой узел выполнится следующим. Бывают фиксированными переходами и условными ветвлениями.

Под капотом работает передача сообщений: узел завершил работу и отправил сообщения по рёбрам дальше, получатели выполнились и передали свои — и так шаг за шагом. Эти шаги в документации называют супер-шагами, а сама идея заимствована у системы Pregel от Google. Практический смысл терминологии простой: узлы, работающие параллельно, относятся к одному супер-шагу, а те, что идут друг за другом, — к разным. Выполнение заканчивается, когда все узлы неактивны и сообщений в пути не осталось.

Часть 4 · Память

Чекпойнты, потоки и долгая память

from langgraph.checkpoint.memory import InMemorySaver
from langgraph.store.memory import InMemoryStore

checkpointer = InMemorySaver()
store = InMemoryStore()

graph = builder.compile(checkpointer=checkpointer, store=store)

result = graph.invoke(
    {"messages": [{"role": "user", "content": "Hi, my name is Bob."}]},
    {"configurable": {"thread_id": "thread-1"}},
)

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

Часть 5 · Согласование

Как остановить агента и спросить человека

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

1. Подключите чекпойнтер. Без него сохранять состояние негде; в продакшене он должен быть долговечным.
2. Передайте thread_id. По нему рантайм понимает, какое состояние загружать при возобновлении.
3. Вызовите interrupt там, где нужна пауза. Значение, которое вы передаёте, должно сериализоваться в JSON — оно уходит наружу, вызывающей стороне.

Часть 6 · Разработка

Локальный сервер и визуальная Studio

pip install -U "langgraph-cli[inmem]"

langgraph new путь/к/проекту --template new-langgraph-project-python

cd путь/к/проекту
pip install -e .

# в .env положить ключ LangSmith
# LANGSMITH_API_KEY=lsv2...

langgraph dev

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

Часть 7 · Инструменты

Как подключить MCP-серверы

MCP — открытый протокол, по которому приложения отдают моделям инструменты и контекст: файловые системы, базы, внешние сервисы. В экосистеме LangChain за это отвечает пакет langchain-mcp-adapters: клиент принимает описание сразу нескольких серверов и возвращает их инструменты одним списком.

pip install langchain-mcp-adapters

# ---

from langchain_mcp_adapters.client import MultiServerMCPClient

client = MultiServerMCPClient(
    {
        "math": {
            "transport": "stdio",          # локальный процесс
            "command": "python",
            "args": ["/path/to/math_server.py"],
        },
        "weather": {
            "transport": "http",           # удалённый сервер
            "url": "http://localhost:8000/mcp",
        },
    }
)

tools = await client.get_tools()

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

Вопросы

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

Читать дальше

Соседние гайды