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.