Конечные автоматы и pydantic-graph: новый подход к надёжному управлению состояниями агентов

В статье на Habr ML автор делится опытом построения движка управления состояниями для AI‑агентов. Традиционный подход – набор флагов, бесконечный while‑цикл и громоздкий if‑else‑блок – быстро превращается в «чёрный ящик», где трудно отследить, какие переходы возможны и почему некоторые ветки недостижимы.

Решением стал pydantic-graph‑fsm – небольшая, но мощная библиотека, построенная на базе pydantic и её графового расширения pydantic-graph. Вместо императивного кода разработчик описывает состояния и переходы в виде Pydantic‑моделей, а библиотека автоматически генерирует граф, проверяет целостность и предоставляет визуализацию.

Ключевые возможности:

• Типобезопасные состояния: каждое состояние – отдельный BaseModel с явно описанными полями.
• Валидация переходов: при объявлении переходов проверяется, что целевое состояние совместимо с текущим контекстом.
• Обнаружение недостижимых веток: при построении графа библиотека сигнализирует о «мертвых» состояниях.
• Визуализация: готовый DOT‑файл можно отобразить в Graphviz, что упрощает отладку и документирование.
• Интеграция с агентскими фреймворками: пример интеграции с LangChain показан в статье – агент получает текущий State из FSM и вызывает соответствующий Tool.

Автор приводит небольшой пример:

class Init(State):
    prompt: str

class Generated(State):
    text: str

fsm = FSM()
fsm.add_state(Init)
fsm.add_state(Generated)
fsm.add_transition(Init, Generated, condition=lambda s: len(s.prompt) > 0)

В результате код стал чище, а тесты покрывают все возможные переходы. По словам автора, за счёт статической проверки количество багов, связанных с «запертой» логикой, сократилось более чем на 70 %.

Библиотека уже доступна на PyPI (версия 0.3.0) и имеет открытый репозиторий на GitHub, где можно найти более продвинутые примеры, включая асинхронные переходы и вложенные подграфы.