Why it matters
An agent that is a while-loop with a prompt has no representation of where it is. You cannot say what is legal next, you cannot resume after a crash, and every guard is a sentence the model may ignore. A state machine gives the run a finite vocabulary — collecting, planning, acting, waiting for approval, done, failed — with code enforcing which transitions exist.
Mental model
A state machine is a board game's rulebook: the model chooses a move and the rules say which moves are legal. The metaphor breaks because a rulebook is complete and static, while agent states are discovered as the product grows, so the machine is always missing an edge someone will hit.
How it works
Event · step 1 of 7
Collecting
The run starts with a goal record. Its first legal move is Planning; the machine has no edge from Collecting to Acting.
In state
- Collecting
Next: Planning
- Edges taken
- 0 / 7
- Refused
- 0
Figure. States are boxes, events are edge labels and a guard sits next to the event that needs it. The dotted red edge with no arrowhead is a late event that the machine refuses; nothing in the figure lets the model take it.
What to notice. The refused edge is the mechanism: after Done, a queued plan event still arrives, and code rejects it and logs the attempt instead of coercing the run back into Planning. Without that check the state record would disagree with the work already finished. Error and timeout exits from Collecting, Planning and Acting are omitted for clarity; the waiting state shows both.
Text version
A state machine with six states. Collecting goes to Planning on ready. Planning goes to Acting on guard. Acting returns to Planning on revise. Acting goes to Awaiting approval on irreversible. Awaiting approval returns to Acting on approved, or exits to Failed on rejected or timeout. Acting also goes to Done on verified. A dotted red edge with no arrowhead runs from Done back to Planning, labelled refused, late event; it is the transition the machine refuses. The trace walks Collecting, Planning, Acting, Awaiting approval, then Acting again after approval, then Done, then a refused late event. Edges taken moves from 0 of 7 to 5 of 7, and refused transitions from 0 to 1.
- List the states a run can be in and the event that moves it to each successor.
- Keep model-driven choice inside a state and put the transition table in code.
- Persist the current state and the data each transition needs, so a resume restarts at a boundary.
- Attach a timeout and an error transition to every state, including the waiting ones.
- Reject illegal transitions at runtime and log the attempt rather than silently coercing it.
- Test the machine by walking every edge, including failure edges, without calling a model.
Trade-offs
| Choice | Good for | Cost | Fails when |
|---|---|---|---|
| Free-form loop | Maximum flexibility, least code | No legality, resume or testability | Runs must survive restarts or audits |
| Explicit state machine | Testable, resumable, auditable | New states need code changes | The domain is open-ended and changes weekly |
| Model chooses transitions | Handles unanticipated paths | Illegal and looping transitions | Actions are consequential |
| Workflow engine graph | Durable, observable, visual | Framework coupling and ceremony | The task is genuinely exploratory |
Good for
Maximum flexibility, least code
Cost
No legality, resume or testability
Fails when
Runs must survive restarts or audits
- Runs must survive restarts or audits
- The domain is open-ended and changes weekly
- Actions are consequential
- The task is genuinely exploratory
Figure. Each choice with what it buys, what it costs, and the case where it loses.
What to notice. The fourth column is the decision: if the losing case describes your situation, the choice is wrong.
Text version
Four trade-offs: Free-form loop is good for Maximum flexibility, least code, costs No legality, resume or testability, and fails when Runs must survive restarts or audits. Explicit state machine is good for Testable, resumable, auditable, costs New states need code changes, and fails when The domain is open-ended and changes weekly. Model chooses transitions is good for Handles unanticipated paths, costs Illegal and looping transitions, and fails when Actions are consequential. Workflow engine graph is good for Durable, observable, visual, costs Framework coupling and ceremony, and fails when The task is genuinely exploratory
Failure modes
- Unreachable state. A run sits in a state with no timer and no event that can move it. Debug: build the transition graph and assert every state has an exit for success, error and timeout.
- Illegal transition accepted. The model triggers a step from the wrong state and invariants break. Debug: log rejected transitions and assert a non-zero count only for expected cases.
- State and data diverge. The persisted state says acting while the tool call already completed. Debug: compare the state record with the action journal at resume.
In production
Monitor the count of runs per state and the age in each; a growing waiting or acting bucket is the earliest sign of a stuck system. Alert on illegal transition attempts.
Common misconceptions
People think: A state machine makes the agent deterministic.
Actually: It makes control flow deterministic; the model's choice inside a state is still sampled.
People think: State machines are only for simple workflows.
Actually: They matter most where a model is involved, because they bound what the model's choice can reach.
Interview angle
Strong answers separate the transition table from the model's choice, describe persistence at state boundaries and explain how illegal transitions are handled. Weak answers draw a diagram of boxes and never say what enforces the arrows.
Sources
- LangGraph documentation — explicit graph state, nodes and conditional edges for agent control flow.
- Anthropic, Building effective agents — workflows as predefined code paths versus model-directed loops.