Model the workflow before giving an agent a loop.
Define states, legal transitions, guards, pauses and recovery while the host application remains responsible for execution.
Short answer
Represent the workflow as explicit states and events before adding model decisions. The machine declares what states exist, which transitions are legal and which guards must pass. The model may choose among the events currently offered, but the host application reads data, calls models and executes tools. Persisted states make pauses, retries and human checkpoints visible. XState v5 provides the general state-machine foundation. The @statelyai/agent 2.0 package applies this approach to agents, but it is currently alpha: APIs can change, exact versions should be pinned and production readiness must be assessed independently.
Key points
- 01
The model chooses only among transitions that are legal in the current state.
- 02
Guards protect transitions; the host executes every external effect.
- 03
@statelyai/agent 2.0 is alpha and should not be presented as a stable production dependency.
01 / SITUATION
A prompt is a poor place to hide a business process
An agent loop often begins as a sequence of instructions: gather context, search, ask a question, create a proposal, wait for approval and execute. Once retries, missing data, denied access and human pauses appear, that sequence becomes a business process whose legal paths are difficult to see in one prompt.
A state machine names those paths. It can make waiting different from failure, make approval different from execution and prevent a model-selected event from skipping a required checkpoint. The result is easier to inspect even when individual model calls remain probabilistic.
02 / MECHANISM
A machine for the control flow, a host for the effects
Design the workflow so every transition and external side effect has one explicit owner.
- 01Name the states
Describe meaningful conditions such as gathering context, awaiting clarification, preparing, awaiting approval, executing, completed and failed. Avoid states that only mirror UI loading.
- 02Define events and legal transitions
List the events accepted in each state and their destinations. If an event is not legal now, the model cannot make it take effect.
- 03Add deterministic guards
Check required fields, permissions, freshness and business invariants before entering a state. A guard runs as code, not as a model opinion.
- 04Bound model decisions
Offer the model only the currently legal events and typed requests. Keep free-form reasoning separate from authority over the workflow.
- 05Execute in the host
Let the host supply model calls, tools, credentials, persistence and network access. Revalidate permissions and state at every consequential effect.
- 06Persist, observe and test
Store resumable snapshots, trace transitions and test legal, illegal, timeout and recovery paths. Evaluate the resulting state as well as the generated text.
03 / In real work
Support intake
The machine moves from collecting context to awaiting clarification or preparing a ticket. Only a confirmed proposal can enter the submission state.
Equipment intervention
A read-only diagnostic path may suggest a procedure. Any state that could affect equipment pauses for an authorised operator and a fresh safety check.
Finance exception
The model can classify the request and assemble evidence. Guards decide whether required fields exist; the host opens the authorised review action.
Common failure modes
- Encoding the whole control flow in a system prompt and a hand-rolled while loop.
- Allowing model output to call external effects without a host-side transition.
- Adding catch-all transitions that bypass guards when the model returns an unexpected event.
- Persisting messages but not the workflow state needed to resume safely.
- Treating an alpha package API as stable because the underlying pattern is sound.
Implementation checklist
- Business states and terminal states are explicitly named.
- Every state lists the events it accepts.
- Guards are deterministic and independently tested.
- The model sees only currently eligible decisions and tools.
- The host owns credentials, effects and permission checks.
- Human pauses, timeouts, retries and cancellation have defined transitions.
- Tests cover illegal events, stale state, partial failure and resume.
What this approach does not claim
- A state machine constrains paths; it does not make model judgments or tool results correct.
- XState is stable infrastructure, while @statelyai/agent 2.0 is alpha and may introduce breaking changes before a stable release.
- Very small read-only flows may not need a dedicated machine until branching or recovery becomes material.
Sources and reference types
- 01Stately and XState v5 documentationStately · 2026Official documentation
- 02@statelyai/agent 2.0 alpha documentationStately · 2026Official documentation
- 03Demystifying evals for AI agentsAnthropic · 2026Field practice
Practical questions
Does the model still plan inside a state machine?
It can propose text, parameters or one of the events offered in the current state. The machine decides which choices are legal and the host decides whether to execute.
Must we use @statelyai/agent?
No. The architecture can be built with XState, another state-machine library or a small explicit reducer. The important part is the visible transition contract.
How should a human approval be represented?
As a real waiting state with a persisted proposal, expiry rules and separate confirm, edit and reject events. It should not be inferred from conversational tone.