LangGraph

1. Обзор концепции и системная проблема

Попытки построить надежного продакшен-агента с помощью простых циклов while True на Python или линейных цепочек быстро сталкиваются с критическими инженерными ограничениями:

1. Отсутствие персистентности: Если сервер перезагружается во время 5-минутного агентского процесса, все текущее состояние и прогресс безвозвратно теряются.
2. Неконтролируемость потока (Black Box Problem): Сложно предсказать, в какой момент агент решит завершить работу, или как принудительно вернуть его на шаг назад в случае ошибки валидации.
3. Невозможность длительной паузы (Human-in-the-Loop): Остановить выполнение программы в ожидании подтверждения от пользователя без блокировки памяти процесса в обычном коде крайне сложно.

LangGraph решает эти проблемы, моделируя агентские системы как Ориентированные графы состояния (Stateful Graphs). Любой сложный процесс разбивается на прозрачные узлы (Nodes), ребра переходов (Edges) и единственный типизированный состояние (State), который атомарно фиксируется в базе данных после каждого шага.

2. Архитектурная таксономия и ментальная модель

Архитектура LangGraph построена вокруг четырех ключевых сущностей:

• 1. Shared State (Общий состояние): Строго типизированный интерфейс (через TypedDict или Pydantic). Определяет схему данных, доступных всем узлам. Для полей можно задавать специфические редукторы (Reducers), например Annotated[list, add_messages], которые автоматически дописывают новые сообщения вместо перезаписи массива.
• 2. Nodes (Узлы графа): Обычные синхронные или асинхронные функции. Каждый узел принимает текущее состояние, выполняет вычисления (вызов модели, запуск тестов или обращение к БД) и возвращает частичное обновление состояния (State Delta).
• 3. Edges & Conditional Edges (Ребра переходов):
  • Обычные ребра: детерминированный переход от узла А к узлу Б.
  • Условные ребра: функция-роутер анализирует последний вывод модели и решает, куда направить поток (например: если вызван инструмент — перейти к tools, если найдён финальный ответ — к END).
• 4. Checkpointers (Чекпоинтеры): Драйверы долгосрочного хранения (MemorySaver для тестов, PostgresSaver / SqliteSaver для продакшена). Создают неизменные снимки (Snapshots) на каждом супершаге.

3. Технический пайплайн и внутренняя механика

Выполнение графа происходит по модели массового синхронного параллелизма (Bulk Synchronous Parallel, BSP):

1. State Initialization (Инициализация состояния): Граф принимает начальный ввод и конфигурационный объект с ключом thread_id. Чекпоинтер загружает последний сохранённый состояние для этого потока.
2. Superstep Execution (Выполнение супершага): Все активные узлы текущей фазы выполняются параллельно. Каждый узел читает идентичный снимок состояния и генерирует свой патч обновления.
3. Reducer Aggregation & Checkpoint Commit (Слияние состояния): После завершения работы всех узлов фазы система применяет редукторы к полученным изменениям, формирует новое состояние и атомарно фиксирует его в базе данных.
4. Edge Routing & Interrupt Inspection (Маршрутизация и проверка прерываний): Оцениваются условные переходы. Если граф наталкивается на точку прерывания (interrupt_before), выполнение безопасно завершается, передавая управление внешнему приложению.

4. Практические инженерные сценарии в продакшене

01. Автономный цикл разработки и исправления ошибок кода

Граф из четырех узлов:

• generate_code -> run_unit_tests -> evaluate_output.
• Если тесты прошли успешно — переход к create_pr.
• Если тесты упали — условное ребро возвращает состояние в generate_code вместе со стек-трейсом ошибки (с ограничением в максимум 5 итераций).

02. Финансовый процесс Human-in-the-Loop

Агент анализирует спорные счета клиентов. Если сумма возврата меньше $100, граф выполняет возврат автоматически через узел execute_refund. Если сумма больше — граф прерывается (interrupt), генерирует ссылку на форму согласования для менеджера и восстанавливает работу только после получения вебхука от человека.

03. Мультиагентная система «Супервизор — Специалисты»

Центральный узел Supervisor выступает маршрутизатором верхнего уровня. В зависимости от типа задачи он переключает контекст между специализированными подграфами: ResearchSubgraph (поиск в интернете и аналитика) и DraftingSubgraph (генерация контрактов), контролируя единый корпоративный контекст.

5. Подводные камни, типовые ошибки и безопасность

• Раздутие состояния (State Bloat): Сохранение в общий состояние гигабайтных PDF-файлов или массивных таблиц приводит к тому, что каждый чекпоинт в PostgreSQL занимает сотни миллисекунд. Храните в состоянии только легкие метаданные и S3-урлы артефактов.
• Recursion Limit Exceeded: Если условные ребра не имеют гарантированного выхода из цикла, выполнение упадет с системной ошибкой достижения лимита глубины (по умолчанию 25 шагов). Всегда контролируйте счётчик попыток прямо в схеме состояния.
• Несериализуемые объекты в State: Попытка сохранить в состояние открытый дескриптор файла, соединение с базой или функциональное замыкание приведет к падению чекпоинтера при попытке сериализации в JSON/Pickle.