statelyai/agent

Create state-machine-powered LLM agents using XState

What it solves

It prevents AI agents from taking invalid actions by moving control flow logic out of the LLM and into a deterministic state machine. This ensures that agents remain predictable, inspectable, and resumable, while the LLM is restricted to picking from a set of legal events defined by the machine's current state.

How it works

Stately Agent integrates model requests and decisions into XState. The state machine defines the legal transitions and guards; the LLM proposes an event, and the machine determines if that event is allowed. The system separates the machine logic from the execution environment (the host), meaning the same agent machine can be run locally for testing with scripted executors or in production using providers like the Vercel AI SDK without changing the machine's definition.

Who it’s for

Developers building AI agents who need strict control over the agent's behavior, deterministic workflows, and the ability to easily test, visualize, and persist the state of their agents.

Highlights

  • Deterministic Control Flow: The state machine owns the logic, making invalid actions impossible.
  • Model Agnostic: The machine never talks to the model directly, allowing developers to swap LLM providers or executors easily.
  • Built-in Patterns: Includes runnable examples for common agent architectures like ReAct, reflection, plan-and-execute, and RAG.
  • Native XState Integration: Leverages XState's capabilities for snapshots, versioning, and migration of agent states.

Related

  • Project
    microsoft/agent-governance-toolkit

    A governance framework for autonomous AI agents that provides deterministic policy enforcement, identity management, and audit logging to prevent unauthorized actions.

  • Project
    statewright/statewright

    Statewright is an open‑source Rust‑based framework that wraps LLM agents in deterministic state‑machines, enforcing per‑state tool policies, model routing, and approval gates to make code‑writing agents more reliable. It ships a CLI/TUI, host plugins (Claude Code, Codex, Cursor, etc.), and a self‑hostable Docker stack.

  • Project
    henryqin1997/statem

    A command-line state machine that turns AI agent workflows into inspectable graphs of states and executable checks to ensure reliability in long-running tasks.

  • Project
    MORTEN-BUUR/nordef-matrix-open-control

    A model-independent safety control plane for AI agents that enforces deterministic policies and cryptographic human approval outside the language model.

  • Project
    langwatch/scenario

    An agent testing framework that uses simulations, user simulators, and judge agents to evaluate the behavior and robustness of AI agents in multi-turn conversations.