LangGraph: оркестрация LLM-агентов

Пошаговый туториал по построению графа агентов с LangGraph, готовый к продакшену. Время выполнения по шагам: 60–120 минут в зависимости от окружения.

Шаг 1: граф состояний

Команда: создайте файл графа state_graph.py или state_graph.yaml и опишите вершины и стартовую точку. Ниже пример на Python с langgraph runtime версии 0.4.0 (релиз 2026).

pip install langgraph==0.4.0  # ~55 MB, 2026 release

Пояснение: установка нужна один раз; версия 0.4.0 фиксирует API runtime и совместимость с persistence адаптерами.

# state_graph.py
from langgraph import Graph, Start, End

g = Graph("order-processing")

@g.start
def start(context):
    context.set("order_id", "12345")
    return "validate"

@g.node("validate")
def validate(context):
    # вызов LLM или локальной логики
    return "route"

@g.node("route")
def route(context):
    if context.get("valid"):
        return "charge"
    return "reject"

@g.end
def end(context):
    return True

Ожидаемый вывод при валидации графа (команда запуска check):

$ python -m langgraph.check state_graph.py
Graph "order-processing" validated: nodes=4, edges=3, hooks=2

Типовая ошибка: ImportError: cannot import name 'Graph'. Фикс: проверьте установленную версию (pip show langgraph) и интерпретатор Python; возможно установлен Python 3.10, тогда используйте 3.11.

Шаг 2: узлы и edges

Команда: определите узлы с LLM-интеграцией и пропишите edges в YAML для наглядности. Пример node, вызывающий OpenAI-совместимый API через адаптер.

# nodes.yaml
nodes:
  - id: validate
    type: llm
    model: gpt-4o-lite-2026
    timeout: 10s
    prompt: |
      Проверить валидность заказа с id {{ order_id }}
  - id: charge
    type: action
    command: charge_service.charge
edges:
  - from: start
    to: validate
  - from: validate
    to: route
  - from: route
    to: charge
  - from: route
    to: reject

Пояснение: здесь edge явно определяют возможные переходы, а типы узлов (llm/action) влияют на поведение рантайма: retry, timeout и сериализация.

Ожидаемый вывод при загрузке YAML в рантайм:

$ langgraph load nodes.yaml
Loaded graph "order-processing" (nodes=4 edges=4). Active runners: 1

Потенциальная ошибка: YAMLError: duplicate key. Исправление: проверьте уникальность id узлов и корректность отступов. YAML чувствителен к пробелам.

Шаг 3: persistence

Команда: поднимите PostgreSQL 15 и Redis 7 через Docker Compose для сохранения состояния и брокера задач. Ниже docker-compose.yml для локальной отладки.

version: '3.8'
services:
  db:
    image: postgres:15
    environment:
      POSTGRES_USER: lg
      POSTGRES_PASSWORD: lgpass
      POSTGRES_DB: langgraph
    ports:
      - "5432:5432"
    volumes:
      - pgdata:/var/lib/postgresql/data
  redis:
    image: redis:7
    ports:
      - "6379:6379"
volumes:
  pgdata:

Пояснение: PostgreSQL хранит состояние узлов и истории, Redis используется как очередь задач и for ephemeral locks. Образы: postgres:15 ~200 MB, redis:7 ~40 MB. Время поднятия контейнеров: примерно 6–12 секунд на NVMe SSD.

Запуск и проверка:

$ docker compose up -d
Creating network "langgraph_default" with the default driver
Creating volume "langgraph_pgdata" with default driver
Creating langgraph_db_1 ... done
Creating langgraph_redis_1 ... done
$ docker compose ps
NAME                  COMMAND                  SERVICE             STATUS              PORTS
langgraph_db_1        "docker-entrypoint.s…"   db                  running             0.0.0.0:5432->5432/tcp
langgraph_redis_1     "docker-entrypoint.s…"   redis               running             0.0.0.0:6379->6379/tcp

Типичная ошибка: psql: could not connect to server: Connection refused. Фикс: убедитесь, что контейнер db запущен (docker logs langgraph_db_1) и что локальный фаервол не блокирует порт 5432. Для systemd-based серверов проверьте, что Docker запущен: systemctl status docker.

Шаг 4: исполнение агентов

Команда: запустите runner LangGraph, укажите адаптеры persistence и провайдер LLM через переменные окружения. Пример запуска как systemd-сервис для стабильного продакшена.

# Экспорт переменных окружения
export LANGGRAPH_PG_DSN="postgresql://lg:lgpass@localhost:5432/langgraph"
export LANGGRAPH_REDIS_URL="redis://localhost:6379/0"
export OPENAI_API_KEY="sk-..."  # или URL локального LLM

# Запуск в foreground для отладки
langgraph run --graph state_graph.py --workers 4

Ожидаемый вывод:

2026-02-10 12:01:22 runner INFO  Starting LangGraph runner (workers=4)
2026-02-10 12:01:22 db INFO      Connected to PostgreSQL 15 at localhost:5432
2026-02-10 12:01:23 redis INFO   Connected to Redis 7 at localhost:6379
2026-02-10 12:01:23 llm INFO     Initialized provider: openai-gpt4o-lite
2026-02-10 12:01:23 graph INFO   Runner ready. Listening for executions.

Типичный runtime-ошибок: LLMError: 429 Too Many Requests. Фикс: настройте rate-limit retry policy в node-конфиге, добавьте экспоненциальный бэкофф. Пример конфигурации:

# retry config inline
@g.node("validate", retry={"retries": 5, "backoff": "exponential", "min_delay": "1s\