statelyai/agent
Create state-machine-powered LLM agents using XState
What it solves
It addresses the unpredictability of AI agents by providing a logic layer that separates the agent's control flow from the model's decision-making. Instead of letting a model have total control, this tool allows developers to define explicit rules, boundaries, and valid transitions that the agent must follow.
How it works
It integrates model requests and decisions into XState, treating the agent as a state machine. The state machine defines the allowed actions (events) and rules (guards). When the agent needs to make a choice, it uses agent.decide to ask a model to pick one of the currently allowed events. The machine then verifies if that choice is permitted; if a guard rejects the model's proposal, the decision is retried. This architecture allows the agent to be paused, its state (snapshot) to be saved, and then resumed later.
Who it’s for
Developers building AI agents who need strict control over workflows, the ability to visualize and test agent logic without calling APIs, and support for "human-in-the-loop" interactions.
Highlights
- Explicit Control Flow: Uses state machines to define exactly what an agent can and cannot do.
- Bounded Decisions: Models can only propose events that are valid for the current state.
- State Persistence: Ability to save XState snapshots to stop and resume agents across different processes.
- Provider Agnostic: While it provides an adapter for the Vercel AI SDK, the core logic does not depend on a specific model provider.
- Verifiable Logic: Machines can be linted, simulated, and explored without requiring an API key.