> ## Documentation Index
> Fetch the complete documentation index at: https://speshu.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# LangGraph: как построить ИИ-агента с памятью, состояниями и ветвлениями

> Обзор LangGraph: stateful-агенты, графы состояний, память, ветвления и пример подключения SpeShu.AI через OpenAI-compatible API.

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

О LangGraph говорят всё чаще, потому что агентные приложения редко остаются линейными. В реальных задачах есть проверка результата, повторные попытки, human-in-the-loop, маршрутизация и память между сообщениями.

В этой статье разберём, как работает LangGraph и как собрать простого агента с памятью на моделях SpeShu.AI.

## Что такое langgraph

LangGraph — это низкоуровневый orchestration framework для long-running и stateful-агентов. Вместо одной цепочки вы описываете граф: узлы выполняют действия, рёбра задают переходы, состояние передаётся между шагами.

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

LangGraph можно использовать отдельно, но чаще его комбинируют с LangChain-компонентами: `ChatOpenAI`, tools, retrievers и memory.

## Как работает langgraph

В основе LangGraph лежит `StateGraph`. Вы описываете тип состояния, добавляете узлы и соединяете их переходами. На каждом шаге узел получает текущее состояние и возвращает обновление.

Для памяти используется checkpointing. В простом примере это `InMemorySaver`, а в продакшене — SQLite, Postgres или другое постоянное хранилище. Благодаря `thread_id` один и тот же граф может вести независимые диалоги с разными пользователями.

Архитектурно это похоже на workflow engine, но заточенный под LLM: сообщения, tool calls, состояние, стриминг, паузы и продолжение работы.

## Что умеет langgraph

* хранить состояние агента между шагами;
* добавлять короткую память диалога через checkpointer;
* строить ветвления и циклы;
* подключать tools и retrievers;
* делать human-in-the-loop;
* стримить промежуточные события;
* переносить граф из прототипа в production-runtime.

Мини-кейсы: агент поддержки с эскалацией, code-review агент, аналитик с несколькими источниками данных, агент продаж, который сначала уточняет вводные, а потом готовит ответ.

## langgraph на практике

Пример ниже создаёт граф из одного узла, но уже с memory-checkpointer. Второй вызов с тем же `thread_id` получает историю через состояние.

```python theme={null} theme={null}
import os
from langchain_openai import ChatOpenAI
from langgraph.checkpoint.memory import InMemorySaver
from langgraph.graph import MessagesState, StateGraph, START

llm = ChatOpenAI(
    model="openai/gpt-5.5",
    api_key=os.environ["SPESHU_AI_API_KEY"],
    base_url="https://speshu.ai/api/v1",
)

def call_model(state: MessagesState):
    response = llm.invoke(state["messages"])
    return {"messages": [response]}

builder = StateGraph(MessagesState)
builder.add_node("assistant", call_model)
builder.add_edge(START, "assistant")

graph = builder.compile(checkpointer=InMemorySaver())

config = {"configurable": {"thread_id": "demo-user"}}

graph.invoke(
    {"messages": [{"role": "user", "content": "Меня зовут Анна."}]},
    config,
)

result = graph.invoke(
    {"messages": [{"role": "user", "content": "Как меня зовут?"}]},
    config,
)

print(result["messages"][-1].content)
```

Для реального проекта замените `InMemorySaver` на Postgres-checkpointer, добавьте узлы retrieval, проверки качества и инструментов. Так агент станет устойчивее: если один шаг упал, граф можно продолжить из checkpoint.

## Преимущества и недостатки langgraph

Плюсы:

* понятная модель состояния;
* удобен для сложных агентов;
* есть persistence и thread-based memory;
* хорошо сочетается с LangChain.

Минусы:

* выше порог входа, чем у обычного LangChain;
* для простого Q\&A он может быть лишним;
* нужно явно проектировать состояние и переходы.

## langgraph vs альтернативы

LangGraph vs LangChain: LangChain удобен для компонентов и простых цепочек. LangGraph нужен, когда появляются состояния, ветвления и долговременное выполнение.

LangGraph vs CrewAI: CrewAI проще для multi-agent ролей. LangGraph даёт больше контроля над графом и состоянием.

LangGraph vs AutoGPT: AutoGPT ближе к готовому автономному агенту. LangGraph — фреймворк, из которого вы сами собираете предсказуемую систему.

## Кому подойдёт langgraph

LangGraph подойдёт разработчикам, которые строят AI-агентов для бизнеса: поддержку, аналитические workflow, внутренние ассистенты, агентные backend-сервисы и системы с контролем качества.

Если задача ограничивается одним prompt и ответом, начните с обычного вызова модели. Если появляются циклы, проверки и память — переходите к графу.

## Как попробовать langgraph через SpeShu.AI

SpeShu.AI подключается через тот же OpenAI-compatible интерфейс, который использует `ChatOpenAI`:

* не нужен VPN;
* не нужна зарубежная карта;
* можно переключать модели в одном коде;
* один ключ работает для разных сценариев;
* быстрый старт через [speshu.ai/profile](https://speshu.ai/profile).

Используйте `base_url="https://speshu.ai/api/v1"` и модель из [каталога](/api-reference/models/list).

## Заключение

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

Начните с одного состояния, одного checkpointer и двух-трёх узлов. Этого достаточно, чтобы понять, нужен ли вам полноценный stateful-agent.

***

<Card title="Подключить API" icon="plug" type="tip" href="https://speshu.ai/profile">
  Запустите интеграцию через SpeShu.AI: единый доступ к AI-моделям, без VPN и зарубежной карты
</Card>