Agent State Machines: Constraining the Loop That Wanders

A free-running agent loop has exactly one rule: keep going until the model stops emitting tool calls. Every decision about what to do next lives inside the model, which is convenient right up until the agent spends nine turns re-reading files it has already read.

A state machine takes some of those decisions back. You define a small set of phases, which tools are available in each, and which transitions are legal. The model still decides what to do; it no longer decides what kind of work it is doing.

What a state adds

Three things, and they compound. First, a restricted tool set: in an investigation state the agent can search and read but cannot write, so a whole category of premature editing becomes impossible rather than discouraged.

Second, a state-specific prompt. Instead of one system prompt that has to cover every phase of the work, each state carries instructions relevant only to that phase, which is shorter and far more likely to be followed.

Third, legible failure. When something goes wrong you know which state it went wrong in, and states fail in characteristically different ways. That alone often halves debugging time. Agent observability and tracing covers capturing the transitions.

A concrete shape

For a bug-fixing agent, five states cover most of the work: triage, investigate, patch, verify, report.

Triage reads the issue and decides whether the task is in scope, with no tools beyond reading the ticket. Investigate has search and read, no writes. Patch has read and write, no test execution. Verify can run tests and read output, but cannot edit. Report has no tools at all — it produces the summary and ends.

The transitions matter as much as the states. Verify can go back to patch when tests fail, but patch cannot go directly to report without passing through verify. That single constraint eliminates premature completion, which is one of the four failure modes every unconstrained loop exhibits. Agent loop anatomy covers the other three.

Transitions should be mechanical where they can be

There are two ways to move states: the model requests it through a transition tool, or the harness decides based on an observable condition.

Prefer the harness wherever a condition is checkable. Moving from verify to report when the test suite exits zero is a fact, not a judgement, and facts should not be delegated to a model that has an incentive to believe it is finished.

Reserve model-requested transitions for genuinely open decisions, such as whether investigation has gathered enough to attempt a patch. Even then, make the transition a tool call with a required argument explaining the reason — it forces the decision to be articulated, and it gives you something to read when the choice turns out to be wrong.

What it costs

Rigidity. A state machine encodes an assumption about how the work proceeds, and tasks that do not fit that shape will fight it. An agent stuck in investigate because the codebase does not contain what it was told to look for needs an escape hatch, or it will thrash until the turn limit.

Build the escape in deliberately: every state should have a legal transition to a terminal state that reports failure. An agent that can give up cleanly is far more useful than one that cannot, because a clean stop is a handoff and a thrash is a bill.

The second cost is engineering time. A state machine is real code with real tests, and for a simple task it is more machinery than the task deserves. If a plain loop with good tools finishes your work reliably, you do not need this. ReAct versus plan-and-execute covers the lighter-weight middle ground.

States compose with a loop inside

The useful architecture is not a state machine instead of a loop, it is a state machine around one. Inside each state the agent runs an ordinary loop with the tools that state permits, for up to some number of turns.

This keeps the flexibility that makes agents useful — the model still decides which file to read and in what order — while bounding the scope of what a wrong decision can affect. A confused agent in investigate wastes reads; it cannot corrupt the working tree, because it holds no write tool.

Give each state its own turn ceiling. Investigation deserves more turns than patching, and a per-state limit catches thrashing far earlier than a global one would. Agent planning strategies covers what belongs in a plan versus in the structure.

Where the human fits

Explicit states give you natural approval points. A transition into patch, or out of verify into a state that pushes anything, is a place a human can sit without having to interpret a raw transcript.

That is a much better interface than approving individual tool calls. Reviewing "the agent has finished investigating and proposes to change these three files" is a decision someone can make in seconds; reviewing forty tool calls is not something anyone does carefully twice. Human-in-the-loop design covers where to place the gates.

States are also the right unit for checkpointing. A transition is a well-defined boundary with a known set of completed work behind it, which makes it far easier to resume from than an arbitrary turn. Agent checkpointing covers what to save at those boundaries.

Testing states individually

The largest practical benefit is that states are testable in isolation. You can construct an entry condition, run one state, and assert on what it produced, without running the whole pipeline.

This turns agent development into something resembling ordinary software development. Investigation quality can be measured against known-good answers. Patch quality can be measured with the investigation held fixed. When end-to-end reliability drops, you can find which state regressed instead of guessing.

Start with two states — do the work, verify the work — and add more only where you have observed a specific failure that structure would have prevented. Most agents that need states need three or four, not nine.