Deterministic agent state machine

A deterministic agent state machine is a fixed plan of steps around an AI agent. Ordinary software tracks which step the agent is in and what it may do there, and applies those rules the same way every time: that is what deterministic means. At a returns desk, for example, the agent cannot pay a refund before the order check is done, however sure of itself it is.

How does it work?

A finite-state machine is always in exactly one of a limited number of states and moves between them through transitions. For an AI agent, each state is a phase of the work, such as planning, implementing or testing, with its own list of permitted tools (state machine guardrails). A transition can carry a guard, a check in code such as "the tests passed", or wait for a person's approval (human-in-the-loop). The model works inside the current state and asks to move on; a small engine without a language model decides.

Statewright, which Ben Cochran presented in a Show HN on 12 May 2026, is one implementation. According to its README of May 2026, its core is a deterministic Rust engine with no LLM in the loop, connected to coding agents such as Claude Code through MCP and hooks. In its bugfix workflow the agent may only read and search while planning, make edits of at most 20 lines in at most three files while implementing, and run only test commands such as pytest while testing. A tool call outside the current phase is rejected with a message that lists what is available. A failed test sends the agent back to implementing. Cochran's reasoning is that a model that sees five tools instead of dozens works in a smaller, more focused context.

Why not write the rules in the prompt?

Instructions in a system prompt are text the model can ignore. The Statewright README calls enforcement "hard" when a tool call is intercepted before it runs, and "advisory" when the rules only sit in the model's context. In May 2026 its Claude Code integration was hard and its Cursor integration advisory.

Anthropic's Building effective agents (December 2024) separates workflows, which run models and tools "through predefined code paths", from agents, which direct their own process and tool use. An agent state machine combines the two: code fixes the phases and their order, and within a phase the model chooses its own steps.

How does it differ from a pipeline?

A pipeline built as a DAG (directed acyclic graph) only moves forward. A state machine can loop back, from testing to implementing for example. LangGraph supports this pattern: nodes and edges over a shared state, fixed or conditional edges, loops, and hand-coded steps next to steps the model drives. The CAX-Agent paper (Lin et al., May 2026) applies the same split to engineering simulations: the orchestrator enforces retry budgets and stop conditions, and the model repairs failed scripts within those limits.

Where does it go wrong?

• Someone has to write the workflow, although an agent can draft it.
• A workflow that is too strict leaves the agent stuck. Statewright has a command that switches it off.
• The machine controls order and permissions. Whether the work inside a step is right depends on guards such as a test result.
• The evidence is thin. Statewright's own test used five SWE-bench tasks out of 2,294: with the workflow, two local models went from 2 of 10 passing attempts to 10 of 10. Models under about 13 GB still could not make accurate edits.

Example

Suppose an accounting firm lets an agent prepare expense claims. The states are collect (read the mailbox only), book (enter lines in the accounting software), approve (a staff member checks the claim) and submit. The guard from book to approve checks in code that every line has a receipt. If the agent tries to submit while it is still collecting, the engine refuses and lists the tools it may use in that state.