Проще говоря, StateGraph - это схема маршрута агента. Агент не просто отвечает как чат, а проходит по шагам: получил задачу, обновил state, выбрал следующий узел, выполнил действие, снова обновил state и дошел до финального ответа или ручной проверки.
Ключевая идея - state. Это общий объект с данными запуска: сообщение пользователя, история, найденные документы, результаты tools, ошибки, текущий статус, попытки, решение guardrails, trace id и промежуточные выводы. Узлы читают и обновляют state, а не передают друг другу хаотичный текст.
StateGraph полезен для сложных сценариев: поддержка клиентов, RAG, multi-agent системы, обработка документов, CRM-интеграции, аналитические отчеты и процессы с approval. Там, где важны повторяемость, отладка и контроль, граф понятнее и надежнее, чем один большой агентский цикл.
В графе часто есть conditional edges - условные переходы. Например, если классификация показала billing, идти к finance agent; если confidence низкий, отправить человеку; если tool вернул ошибку, попробовать retry; если документ невалиден, запросить уточнение.
Для production StateGraph хорошо сочетается с checkpoint и tracing. Checkpoint сохраняет состояние после шагов, чтобы можно было продолжить процесс после сбоя. Trace показывает путь по графу: какие узлы были выполнены, почему выбран переход и где произошла ошибка.
Примеры
- В поддержке StateGraph сначала классифицирует обращение, затем ищет ответ в базе знаний, потом проверяет confidence и либо отвечает, либо делает fallback to human.
- В обработке документов граф проходит узлы: загрузка файла, OCR, structured extraction, validation, three-way matching и approval.
- В CRM-сценарии StateGraph читает сделку, готовит черновик заметки, проверяет права и только потом вызывает tool для записи.
- Если tool calling возвращает ошибку timeout, conditional edge отправляет выполнение в retry node, а после нескольких попыток - в failed state.
- В multi-agent системе supervisor node выбирает, какой подагент должен выполнить следующий шаг, и записывает результат в общий state.
Где используется
- построение AI-агентов на LangGraph
- orchestration сложных agent workflow
- RAG с проверкой источников и fallback
- обработка документов по этапам
- multi-agent системы с supervisor agent
- approval workflow для рискованных действий
- retry и обработка ошибок tool calling
- checkpoint и восстановление после сбоя
- наблюдаемость через trace и structured logs
Связанные термины
Частые вопросы
Что такое StateGraph простыми словами?
Это граф шагов AI-агента: каждый узел делает часть работы, переходы выбирают следующий шаг, а общее состояние хранит данные всего процесса.
Чем StateGraph отличается от обычного agent loop?
Agent loop часто сам решает следующий шаг в цикле. StateGraph задает более явную структуру: узлы, переходы, состояние, правила остановки и проверяемый маршрут выполнения.
Что хранить в state?
Обычно хранят вход пользователя, историю, результаты поиска, tool results, ошибки, счетчики retry, решения guardrails, статусы approval, trace id и данные для финального ответа.
Когда нужен StateGraph?
Когда сценарий состоит из нескольких этапов, есть условия, ошибки, проверки, инструменты, память или handoff человеку. Для простого одношагового ответа граф может быть лишним.
Как отлаживать StateGraph?
Нужны trace, structured logs, сохранение state на ключевых шагах, понятные имена узлов, лимиты итераций и тестовые сценарии для разных веток графа.
