Building Agents
MDX
State Machines for Agent Workflows
Combining model judgment with explicit workflow states, transitions, and recovery paths.
Editorial review: clarity, operational relevance, safety boundaries, and source quality.
Make progress explicit
States such as gathering information, awaiting approval, executing, and verifying give the application a durable view of progress. The model helps choose within a state instead of controlling the entire process implicitly.
A state should describe externally meaningful progress, not every model turn. `collecting_evidence`, `awaiting_approval`, and `verifying_write` survive process restarts and make permitted actions obvious. Store model observations as events or artifacts while keeping the state vocabulary small and stable.
Guard every transition
A transition should check required data, authorization, and prior results before moving forward. Invalid transitions become visible application errors rather than confusing model behavior.
Transitions are commands with preconditions. Moving to execution might require a complete proposal, an unexpired approval for its hash, and available budget. The model may recommend the transition, but code evaluates the guard and records who or what caused the change.
Recovery becomes manageable
Persisted states let interrupted work resume and failed steps retry safely. Operators can inspect where tasks are stuck without reconstructing a conversation transcript.
Recovery policies belong to states and actions. Temporary reads may retry with backoff; an uncertain write moves to reconciliation; expired approval returns to review. Persist checkpoints before side effects, and make operators able to inspect and safely resume or cancel a stranded task.
Practical example
A publication workflow
A content task moves from gathering to drafting, fact_check, awaiting_editor, publishing, and verifying. The editor approves a hash of the exact draft. Publishing uses an idempotency key, and the task reaches completed only after the live page is read back and matches. A timeout during publish enters reconciling rather than immediately retrying and risking a duplicate.
Field checklist
Apply it in practice
- Define a small set of durable, meaningful states.
- Put authorization and data checks on transitions.
- Persist before side effects and use idempotency.
- Design explicit retry, reconciliation, cancellation, and expiry paths.
Decision framework
Questions to answer before you build
A state machine makes progress, authority, recovery, and operator intervention explicit while leaving bounded judgment to the model inside each state.
Is this a durable state or an event?
Use states for meaningful progress such as awaiting approval or verifying a write. Store individual model calls and observations as events.
What guards each transition?
Check required data, permissions, approval freshness, budgets, and prior effects before moving to a more consequential state.
How does each failure recover?
Define retry, reconciliation, expiry, cancellation, and human intervention paths before production incidents expose the gaps.
Common failure signals
Watch for these warning signs
- Creating a state for every model turn and making the workflow impossible to understand.
- Letting the model directly mutate state without transition validation.
- Retrying uncertain writes instead of entering a reconciliation state.
Selected primary references
Continue with the source material
These sources inform the wider editorial perspective for this topic. They are not presented as line-by-line citations for every statement.