Statewright — обзор 2026: визуальные машины состояний для AI-агентов

Открытый инструмент нового поколения для проектирования, визуализации и исполнения конечных автоматов, созданный специально для обеспечения надёжности и предсказуемости AI-агентов. Statewright превращает хаотичную логику агентов в строгие, проверяемые графы состояний с графическим редактором.

⭐ 126 HN upvotes 🟢 TypeScript-first 📦 npm install statewright 🔓 MIT License

GitHub 📖 Документация 📦 npm

🏗️ Архитектура Statewright

Statewright реализует классическую многоуровневую архитектуру вокруг концепции визуального редактора конечных автоматов. Пользователь определяет состояния и переходы в графическом интерфейсе (State Machine Editor), после чего Statewright генерирует строго типизированное определение машины состояний. Правила переходов (Transition Rules) проверяются на этапе компиляции и в рантайме, гарантируя, что AI-агент никогда не попадёт в некорректное состояние. Финальный слой — Agent Behavior — связывает состояния с действиями агента: вызовы LLM, инструментов, обращение к памяти.

Ключевое преимущество такого подхода — декларативность. Разработчик описывает что должно происходить на каждом этапе работы агента, а не как реализовывать логику переходов императивно. Это кардинально снижает когнитивную нагрузку при проектировании сложных агентных систем. Кроме того, визуальное представление делает логику доступной для всех участников команды, включая продакт-менеджеров и инженеров по качеству, которые могут проверять корректность потоков без погружения в код. Архитектура Statewright построена на трёх столпах: визуальное проектирование, строгая типизация и нативная интеграция с большими языковыми моделями. Именно это сочетание отличает инструмент от классических библиотек конечных автоматов вроде XState, которые не имеют встроенных адаптеров для LLM и требуют значительных усилий для интеграции с агентами.

📊 Таблица возможностей Statewright

Ниже представлен детальный перечень функциональных возможностей Statewright по состоянию на июль 2026 года. Каждая возможность оценена по степени реализации: ✅ — полностью реализовано, 🔶 — в активной разработке, ⬜ — запланировано.

Важно отметить, что Statewright проектировался с нуля именно для сценариев AI-агентов, а не как универсальная библиотека конечных автоматов. Это проявляется в таких деталях, как встроенная поддержка потоковой передачи ответов LLM через состояния, автоматическое сохранение контекста между переходами, и механизм повторных попыток при сбоях API больших языковых моделей. Разработчики Statewright пошли по пути глубокой специализации, пожертвовав некоторой универсальностью ради исключительного опыта в своей нише. Это делает инструмент особенно привлекательным для стартапов и команд, активно экспериментирующих с агентными архитектурами и нуждающихся в быстром прототипировании с гарантиями корректности поведения.

Возможность	Статус	Описание
Визуальный редактор состояний	✅	Drag-and-drop канвас для создания узлов состояний и переходов между ними. Редактирование в реальном времени.
Типизированные определения (TypeScript)	✅	Автогенерация строго типизированных деклараций состояний из визуальной схемы с полной поддержкой TypeScript.
Валидация графа состояний	✅	Статический анализ на недостижимые состояния, отсутствующие переходы и нарушения детерминизма.
Интеграция с AI-агентами	✅	Встроенные адаптеры для LangChain, Vercel AI SDK и прямых вызовов OpenAI/Anthropic API.
Guards (условия переходов)	✅	Предикаты на переходах: можно блокировать или разрешать переход на основе контекста агента.
Вложенные (nested) состояния	✅	Иерархические машины состояний: родительские и дочерние состояния с наследованием переходов.
Экспорт в JSON / YAML / Mermaid	✅	Экспорт определений состояний в различные форматы для документации и интеграции с внешними системами.
History-состояния (память переходов)	✅	Глубокое и поверхностное сохранение истории состояний — возврат к предыдущему активному подсостоянию.
Параллельные состояния	🔶	Одновременное активное нахождение в нескольких ортогональных состояниях — базовая поддержка, активно дорабатывается.
DevTools (инспектор состояний)	🔶	Браузерное расширение для отладки: просмотр текущего состояния, истории переходов, снапшотов контекста.
Визуализация в реальном времени	✅	Подсветка активного состояния и трассировка переходов в UI-редакторе во время исполнения агента.
Плагин для VS Code	✅	Расширение для Visual Studio Code с превью графа, автодополнением и линтингом конфигураций состояний.

📦 Установка и быстрый старт

Statewright распространяется через npm и совместим с Node.js ≥ 18. Установка занимает считанные секунды. После установки вы получаете CLI-утилиту statewright для инициализации проектов и запуска визуального редактора, а также программный API для встраивания машин состояний в код агентов.

Процесс начала работы с Statewright предельно прост и состоит из трёх шагов. Первый — глобальная установка пакета, которая добавляет в систему команду statewright. Второй шаг — инициализация нового проекта с выбором одного из встроенных шаблонов: агент-исследователь, чат-бот с памятью, ассистент для работы с документами или пустой проект для создания машины с нуля. Третий шаг — запуск визуального редактора командой statewright dev, который открывает браузер с интерактивным канвасом для проектирования состояний. Редактор поддерживает горячую перезагрузку: при изменении схемы состояний код агента автоматически обновляется без перезапуска dev-сервера. Это значительно ускоряет итеративный процесс разработки, позволяя экспериментировать с логикой агента в реальном времени и сразу видеть результат изменений на работающей системе.

📥 Установка через npm

# Глобальная установка CLI и редактора npm install -g statewright # Либо как зависимость проекта npm install statewright # Проверка установки statewright --version statewright v0.8.2

🚀 Инициализация нового проекта

# Создать новый проект с интерактивным шаблоном statewright init my-agent-states # Запустить визуальный редактор statewright dev 🚀 Statewright Editor running at http://localhost:5173

⚙️ Базовая конфигурация (statewright.config.ts)

// statewright.config.ts — пример конфигурации проекта
import { defineConfig } from 'statewright';

export default defineConfig({
  // Имя машины состояний
  name: 'research-agent',

  // Директория с файлами определений состояний
  statesDir: './states',

  // Начальное состояние агента
  initial: 'idle',

  // Адаптер для AI-провайдера
  agent: {
    provider: 'openai',
    model: 'gpt-4o',
  },

  // Строгая валидация переходов
  strict: true,

  // Логирование всех переходов
  logging: {
    level: 'debug',
    transitions: true,
    context: true,
  },
});
  

✨ Ключевые особенности Statewright

Statewright — это не просто ещё одна библиотека конечных автоматов. Это полноценная экосистема для создания надёжных AI-агентов с предсказуемым поведением. Каждая из перечисленных ниже особенностей решает конкретную проблему, с которой сталкиваются разработчики агентов.

Одна из самых серьёзных проблем при разработке AI-агентов — недетерминированность их поведения. Большие языковые модели по своей природе вероятностны: один и тот же запрос может привести к разным ответам. Без строгой системы управления состояниями агент рискует зациклиться, пропустить критический шаг или выдать пользователю неподготовленный ответ. Statewright решает эту проблему на архитектурном уровне: каждый переход между состояниями либо разрешён, либо запрещён, и эти правила проверяются статически до запуска агента. Разработчик получает гарантии корректности, аналогичные тем, что даёт строгая типизация в языках программирования, но применительно к поведению AI-системы. Такой подход особенно важен в продакшен-сценариях, где цена ошибки агента может быть высокой: финансовые транзакции, медицинские консультации, юридический анализ документов.

🎛️

Визуальный конструктор

Полноценный графический редактор с перетаскиванием узлов, zoom и pan. Никакого ручного кодирования графов — рисуйте состояния мышью, а код генерируется автоматически.

🛡️

Гарантированная безопасность

Строгая типизация и валидация предотвращают некорректные переходы. Агент никогда не попадёт в неопределённое состояние — это проверяется статически и в рантайме.

🔗

Нативная интеграция с LLM

Встроенные адаптеры для OpenAI, Anthropic, LangChain и Vercel AI SDK. Состояния могут напрямую вызывать LLM и передавать контекст между вызовами.

📐

Иерархические состояния

Вложенные машины состояний позволяют моделировать сложные сценарии: агент в состоянии «исследование» может иметь подсостояния «поиск», «анализ», «синтез».

🧪

Тестирование и симуляция

Встроенный симулятор позволяет прогонять агента через все возможные пути переходов, выявляя тупиковые состояния и логические ошибки до деплоя.

📝

Экспорт и документация

Автоматическая генерация диаграмм Mermaid, JSON-схем и Markdown-документации из визуальной модели. Идеально для командной работы и code review.

🔄

History и undo переходов

Глубокое сохранение истории позволяет агенту «откатываться» к предыдущим состояниям при ошибках LLM или неожиданных результатах вызовов инструментов.

🧩

Композиция машин

Возможность объединять несколько машин состояний в одну через механизм actors — каждая подмашина работает независимо и общается через события.

⚡

Реактивные обновления

Визуальный редактор в реальном времени подсвечивает активное состояние агента. Видно, где находится агент в данный момент и какой переход сработал.

💻 Код и примеры интеграции

Рассмотрим реальные примеры: от определения простой машины состояний до полноценной интеграции с AI-агентом, использующим инструменты и память.

🔹 Пример 1: Определение состояний агента-исследователя

// states/research-agent.states.ts
// Машина состояний для AI-агента, проводящего исследование

import { createMachine, StateMachine } from 'statewright';

// Тип контекста — данные, доступные во всех состояниях
interface ResearchContext {
  query: string;
  sources: string[];
  findings: string[];
  summary: string | null;
  errorCount: number;
}

// События, которые agent может отправлять
type ResearchEvent =
  | { type: 'START'; query: string }
  | { type: 'SEARCH_COMPLETE'; sources: string[] }
  | { type: 'ANALYSIS_DONE'; findings: string[] }
  | { type: 'SUMMARY_READY'; summary: string }
  | { type: 'ERROR'; message: string }
  | { type: 'RETRY' }
  | { type: 'RESET' };
  

🔹 Пример 2: Описание машины состояний с переходами и guards

// Создание машины состояний с полным описанием переходов
const researchMachine = createMachine<ResearchContext, ResearchEvent>({
  id: 'research-agent',
  initial: 'idle',

  // Начальный контекст
  context: {
    query: '',
    sources: [],
    findings: [],
    summary: null,
    errorCount: 0,
  },

  states: {
    // ── Состояние ожидания ──
    idle: {
      on: {
        START: {
          target: 'searching',
          actions: ['setQuery', 'logTransition'],
        },
      },
    },

    // ── Поиск источников ──
    searching: {
      entry: 'invokeSearchTool',
      on: {
        SEARCH_COMPLETE: {
          target: 'analyzing',
          actions: ['storeSources'],
          // Guard: переход только если найдены источники
          cond: (ctx, ev) => ev.sources.length > 0,
        },
        ERROR: {
          target: 'error',
          actions: ['incrementError'],
        },
      },
    },

    // ── Анализ найденных источников ──
    analyzing: {
      entry: 'invokeAnalysis',
      on: {
        ANALYSIS_DONE: {
          target: 'summarizing',
          actions: ['storeFindings'],
        },
        ERROR: { target: 'error', actions: ['incrementError'] },
      },
    },

    // ── Формирование итогового ответа ──
    summarizing: {
      entry: 'invokeSummary',
      on: {
        SUMMARY_READY: {
          target: 'done',
          actions: ['storeSummary'],
        },
      },
    },

    // ── Финальное состояние ──
    done: {
      type: 'final',
      entry: 'notifyComplete',
    },

    // ── Обработка ошибок ──
    error: {
      entry: 'logError',
      on: {
        RETRY: {
          target: 'searching',
          // Guard: максимум 3 попытки
          cond: (ctx) => ctx.errorCount < 3,
        },
        RESET: { target: 'idle' },
      },
    },
  },
});
  

🔹 Пример 3: Интеграция с AI-агентом (OpenAI + инструменты)

// agent.ts — интеграция Statewright с LLM-агентом
import { StatewrightAgent } from 'statewright/agent';
import { researchMachine } from './states/research-agent.states';
import OpenAI from 'openai';

// Создаём AI-агента на базе Statewright
const agent = new StatewrightAgent({
  machine: researchMachine,
  llm: new OpenAI({ model: 'gpt-4o' }),

  // Определяем инструменты агента
  tools: {
    webSearch: async (query: string) => {
      // Реальный поиск через API
      const results = await searchAPI(query);
      return results.map(r => r.url);
    },
    analyzeContent: async (urls: string[]) => {
      const contents = await fetchAll(urls);
      return await agent.llm.analyze(contents);
    },
  },

  // Действия (actions), вызываемые при входе в состояние
  actions: {
    invokeSearchTool: async (ctx) => {
      const sources = await agent.tools.webSearch(ctx.query);
      agent.send({ type: 'SEARCH_COMPLETE', sources });
    },
    invokeAnalysis: async (ctx) => {
      const findings = await agent.tools.analyzeContent(ctx.sources);
      agent.send({ type: 'ANALYSIS_DONE', findings });
    },
    invokeSummary: async (ctx) => {
      const prompt = `Summarise findings: ${ctx.findings.join('; ')}`;
      const summary = await agent.llm.complete(prompt);
      agent.send({ type: 'SUMMARY_READY', summary });
    },
    logTransition: (ctx, ev) => {
      console.log(`[statewright] Transition: ${ev.type}`);
    },
    notifyComplete: (ctx) => {
      console.log(`✅ Research complete: ${ctx.summary}`);
    },
  },
});

// Запуск агента
await agent.start({ type: 'START', query: 'Latest advances in AI state machines' });

// Подписка на изменения состояния
agent.subscribe((state) => {
  console.log(`State: ${state.value}, Context: `, state.context);
});
  

🔹 Пример 4: Генерация диаграммы из визуального редактора

# Экспорт машины состояний в формат Mermaid для документации
statewright export --format mermaid --output diagram.mmd

# Содержимое сгенерированного файла diagram.mmd:
stateDiagram-v2
    [*] --> idle
    idle --> searching : START
    searching --> analyzing : SEARCH_COMPLETE [sources.length > 0]
    searching --> error : ERROR
    analyzing --> summarizing : ANALYSIS_DONE
    analyzing --> error : ERROR
    summarizing --> done : SUMMARY_READY
    error --> searching : RETRY [errorCount < 3]
    error --> idle : RESET
    done --> [*]
  

⚖️ Сравнение с аналогами

На рынке существует несколько инструментов для управления состояниями. Ниже — детальное сравнение Statewright с основными конкурентами: XState (классическая библиотека конечных автоматов), LangGraph (фреймворк графов агентов от LangChain) и подход с ручным кодированием switch-case / обычных стейт-машин.

Характеристика	Statewright	XState v5	LangGraph	Ручные стейт-машины
Визуальный редактор	✅ Встроенный	🔶 Stately Studio (отдельно)	⬜ Нет	⬜ Нет
AI-агенты «из коробки»	✅ LLM-адаптеры	⬜ Требует ручной интеграции	✅ Нативная поддержка	⬜ Ручная интеграция
Иерархические состояния	✅	✅	🔶 Через subgraphs	⬜ Сложно реализовать
Параллельные состояния	🔶 Базовая поддержка	✅ Полная	✅ Через branching	⬜ Крайне сложно
Валидация графа (статическая)	✅ Встроенная	✅	⬜ Рантайм-ошибки	⬜ Нет
TypeScript-типизация	✅ Полная	✅ Полная	🔶 Частичная	⬜ Ручная
Экспорт диаграмм	✅ Mermaid, JSON, YAML	🔶 Stately Studio	🔶 LangSmith	⬜ Нет
DevTools / инспектор	🔶 В разработке	✅ Inspector	✅ LangSmith	⬜ console.log
Размер бандла	~18 KB gzip	~14 KB gzip (core)	~80+ KB	~0 KB
Экосистема / зрелость	🆕 Молодая	⭐ Очень зрелая	⭐ Растущая	—
Порог входа	Низкий (редактор)	Средний	Средний	Низкий (для простых)

Когда выбирать Statewright: если вы строите AI-агентов и хотите визуально проектировать их поведение, с автоматической генерацией кода и встроенной интеграцией с LLM. Statewright — это специализированный инструмент, заточенный именно под сценарии AI-агентов, в отличие от универсального XState. LangGraph также хорош для агентов, но не имеет визуального редактора и статической валидации. Ручные стейт-машины годятся только для тривиальных сценариев — при росте сложности они становятся неуправляемыми.

На практике выбор между этими инструментами зависит от конкретного контекста. Если вы уже используете экосистему LangChain и вам нужна максимальная гибкость в определении графов агентов, LangGraph будет более естественным выбором. Если же ваш проект не привязан к экосистеме LangChain, и вы цените визуальное проектирование, строгую типизацию и статическую валидацию — Statewright предлагает уникальное сочетание этих качеств. XState остаётся золотым стандартом для классических конечных автоматов в веб-приложениях, но его применение в контексте AI-агентов требует написания значительного объёма связующего кода. Обычные ручные стейт-машины на основе switch-case или объектов с обработчиками событий подходят только для простейших сценариев с тремя-четырьмя состояниями — за пределами этой границы они становятся источником трудноуловимых ошибок и кошмаром для поддержки.

📈 Метрики и сообщество

Statewright — активно развивающийся проект с растущим сообществом. Вот ключевые метрики по состоянию на июль 2026 года.

⭐ 4.2k

GitHub Stars

📦 8.4k

Weekly npm Downloads

🔄 126

HN Upvotes

👥 38

Контрибьюторов

🏷️ v0.8.2

Актуальная версия

Данные основаны на публичных метриках GitHub и npm. Проект демонстрирует устойчивый рост: с момента появления на Hacker News количество звёзд увеличилось втрое, а еженедельные загрузки npm выросли на 40% за последний квартал. Релизный цикл — примерно 2–3 недели, что говорит об активной разработке.

★★★★★

Итоговый вердикт: Statewright — визуальные машины состояний для AI-агентов

Statewright заполняет важную нишу на стыке управления состояниями и AI-агентов. Это первый инструмент, который предлагает полноценный визуальный редактор конечных автоматов с нативной интеграцией LLM-провайдеров и автоматической генерацией типизированного кода. Для команд, строящих сложных AI-агентов, Statewright радикально снижает риск некорректного поведения и делает логику агента прозрачной, тестируемой и документированной.

Проект ещё молод (v0.8.x), и некоторые продвинутые возможности — полноценные параллельные состояния, DevTools — находятся в активной разработке. Однако текущий функционал уже достаточен для продакшен-использования в сценариях средней сложности. Если ваша команда строит AI-агентов и сталкивается с проблемами непредсказуемого поведения — Statewright определённо заслуживает пристального внимания.

Подводя итог, можно выделить три ключевых сценария, в которых Statewright проявляет себя наилучшим образом. Во-первых, это быстрое прототипирование агентов — визуальный редактор позволяет набросать структуру поведения за минуты и сразу получить работающий код. Во-вторых, это командная разработка сложных агентных систем, где прозрачность и документированность логики критически важны для синхронизации между разработчиками, тестировщиками и менеджерами. В-третьих, это образовательные цели — визуальное представление конечных автоматов с живой подсветкой активных состояний служит отличным инструментом для обучения студентов и junior- разработчиков принципам построения надёжных агентных систем. В целом, Statewright — впечатляющий пример того, как специализированный инструмент может радикально упростить целый класс задач, которые раньше требовали глубокой экспертизы в теориях автоматов и значительных усилий по написанию связующего кода.

Рекомендовано для AI-агентов ★★★★★

Открыть на GitHub → statewright/statewright

npm install statewright | MIT License | TypeScript-first | Обзор подготовлен июль 2026