StatePilot
Deterministic state-machine guards for AI-agent workflows
Enforces the allowed tool order, transitions, loop limits, and cost budgets at runtime. Fail-closed, so an agent cannot step outside its declared state machine. Zero-dependency core, LangGraph-aware. 74 tests, MIT, Python.
What it solves
A recurring theme in agent tooling is wrapping a non-deterministic model in deterministic code, and the reason is simple: prompting an agent to only call these tools, in this order is a request, not a rule. It holds until it does not. statepilot turns that request into a state machine that the runtime enforces.
How it works
You define the machine, and at runtime it decides which tools the agent may call and in which order. Around that sit the guards that catch the failure modes you actually see: loop detection for the agent that keeps retrying the same step, a cost budget, and a hard cap on the number of steps. Anything the machine does not allow raises rather than silently proceeding. The core has zero runtime dependencies, is fully typed, and needs Python 3.10 or newer.
When to use it
It fits a workflow whose steps you can actually name: an intake that has to happen before a lookup, a payment that must not run twice, an escalation that only fires after a check. That is where a state machine is a description of the work rather than a cage around it.
When not to use it
Open-ended work is the wrong fit. If you cannot draw the states in advance, you will spend more time widening the machine than you save by having it, and every widening is a hole. Exploration, research and anything where the next step depends on what the last one found belong outside it.
Stars
★ 0
installs
↓ 20
Clones (14d)
⊟ 12
Language
Python
Updated
2026-08-01
Install
pip install statepilot