An AI agent state machine turns a loosely described loop of observe, reason and act into persisted states with permitted transitions and terminal outcomes. The model can propose what should happen next, but deterministic runtime code checks whether that transition is valid. This separation makes approvals, handoffs, retries, timeouts and asynchronous tasks testable. It also gives operators a truthful answer to “what is this agent doing now?” after the original process has disappeared.
The state machine does not eliminate flexible reasoning. It places reasoning inside bounded phases and protects changes to business state. Edilec's agent workflow guide explains the conceptual loop, and the first-principles guide covers goals, tools and state. This article turns those concepts into a runtime contract with guards, versions and recovery.
Define the AI agent state machine boundary
Create one state machine per durable business task, not per HTTP request or model turn. A claims review, purchase request or support resolution can contain many model calls and tool invocations while retaining one task identity. Child tasks may have their own machines linked to the parent. Keep provider transport and worker lease state separate so a temporary connection loss does not become a business failure.
Name the authoritative owner of state and transitions. The model output is an input to that owner, never the state store itself. Persist task ID, tenant, type, current state, version, owner, timestamps and terminal reason. Every transition records prior state, event, guard result, actor, evidence and next state. This event history supports audit and reconstruction without storing private reasoning.
Choose states that reveal operational reality
A useful baseline separates submitted, ready, planning, awaitingtool, awaitinginput, awaitingapproval, retryscheduled, reconciling, completed, failed, canceled and expired. Adapt names to the domain, but avoid one broad running state. Waiting states should identify what event can release them. Terminal states should be immutable except through an explicit correction or reopened task with a new version.
The A2A specification models tasks with defined statuses, messages and artifacts for potentially long-running agent collaboration. Its exact states need not dictate an internal runtime, but the separation demonstrates a valuable principle: task lifecycle is protocol data, not sentiment inferred from an agent response. Map internal states explicitly when exposing an A2A interface.
| State | Entry event | Allowed next states | Operational invariant |
|---|---|---|---|
| ready | Task accepted | planning, canceled, expired | No worker owns an effect |
| awaiting_approval | Bound request created | ready, canceled, expired | No approved effect has dispatched |
| awaiting_tool | Idempotent command reserved | reconciling, ready, failed | Operation key is durable |
| reconciling | Outcome is uncertain | ready, completed, failed | No blind repeat is allowed |
| completed | Acceptance criteria proven | None or explicit reopen | Output and effects are authoritative |
Make every transition event-driven and guarded
Transitions respond to typed events: userinputreceived, approvalgranted, toolresultobserved, leaseexpired, deadlinereached or cancellationrequested. A guard verifies expected state version, identity, authority, evidence freshness, policy, limits and required fields. The model can emit a structured proposal such as request_tool, but the runtime translates it into an event only after schema and policy validation.
Use compare-and-set writes so concurrent workers cannot advance the same state version. The winning transition increments the version; losing workers reload and discard stale output. Keep transition functions small and deterministic. External calls happen after an intent record is committed, and their results arrive as new events. This avoids holding transactions across unpredictable model or network operations.
Place the model loop inside bounded states
The OpenAI Agents SDK running guide describes a loop in which a model can produce final output, request a handoff or call tools, with a maximum-turn limit available. Wrap each outcome in runtime rules. Final output advances only if it matches the required type and acceptance checks. A handoff advances only to an allowed specialist. A tool call creates a validated command and waiting state.
Set budgets for turns, tokens, tool calls, elapsed work and handoff depth. Budget exhaustion is a defined event leading to review, partial completion or failure; it should not surface as an unclassified exception. Record prompt, model, tool-set and policy configuration identifiers for each planning attempt. The results guide exposes final output and generated items, but the application decides which result satisfies its terminal contract.
Encode stop conditions as invariants
Completion requires evidence, not a phrase such as “done.” Define acceptance by task type: required artifacts exist, authoritative record reaches expected state, reconciliation succeeds and no mandatory approval remains. Failure becomes terminal when retry policy is exhausted or a non-recoverable rule is violated. Expiry is driven by business deadline. Cancellation stops new work and reconciles in-flight effects before terminal confirmation.
Prevent infinite loops by disallowing transitions that do not advance state or evidence after a bounded count. Track repeated tool proposals and equivalent handoffs. A self-transition can be valid for gathering another evidence item, but it needs a progress measure and budget. Escalate when the runtime cannot identify a permitted next transition. The model should not invent new state names at runtime.
Persist for recovery and schema evolution
Store current state and append-only transition history. Snapshot compact verified context, pending commands, approvals and evidence references at semantic boundaries. Version the task schema and define migrations that preserve invariants. If a new deployment cannot interpret an old state, quarantine it with an operator action instead of coercing fields or restarting from the beginning.
On recovery, validate deadline, identity, policy, evidence freshness, tool compatibility and any pending operation outcome. Acquire a lease only after state-version comparison. A worker crash should leave a resumable task and expiring lease, not a counterfeit failure transition. Administrative repair tools must use the same guarded events, record operator identity and prevent direct database state edits.
Partition checkpoint access by tenant and task owner, and make child-task references directional rather than globally searchable. A recovery worker needs the minimum state for its assigned task, not unrestricted access to every paused conversation. Backup, restore and regional failover tests must preserve encryption, version ordering and unique operation keys; a restored stale checkpoint must not outrank newer authoritative state.
| Fault injected | Expected state | Required recovery proof |
|---|---|---|
| Worker dies during planning | planning with expired lease or ready | Fresh worker uses same state version |
| Approval arrives twice | One transition from awaiting_approval | Duplicate returns current state |
| Tool response is lost | reconciling | Authoritative query precedes retry |
| Policy changes during wait | resume_validation or review | New policy decision is recorded |
| Unsupported checkpoint version | quarantined | Migration or explicit operator resolution |
Test the transition graph, not only prompts
Generate tests from the state-transition table. For every state, verify allowed events succeed, forbidden events fail without mutation and duplicate events are idempotent. Exercise concurrent events, clock boundaries, stale versions, missing evidence and unauthorized actors. Use model fixtures for valid and malformed proposals, but keep transition correctness deterministic. Property tests can assert that terminal states never dispatch new work and every consequential action has prior authorization.
Apply secure development practices to state code, migrations and operator tooling. NIST's SP 800-218A extends software development guidance for generative AI systems. Threat-model events as untrusted inputs, protect stored context, review dependency updates and preserve release evidence. The state machine is a security boundary because it decides when agent proposals become executable work.
Operate queues and transitions as a service
Dashboards should show counts and age by meaningful state, transition failure, retry schedule, reconciliation backlog, expired leases and terminal outcome. Alert on impossible or ownerless conditions: awaiting approval with no request, awaiting tool with no operation key or ready with no eligible worker. Report user-facing progress from state, not from speculative model narration.
Review transition histories for repeated loops, manual repairs and long waits. These patterns can reveal poor tool contracts, missing authority or confusing completion criteria. Version metrics with state schemas so renamed states do not break trends. Retain events according to business and privacy requirements, deleting bulky transient context sooner than compact decision evidence. Edilec's audit log guide helps shape investigation-ready events.
Govern graph changes like database migrations. A new state needs entry and exit events, guards, ownership, user meaning, metrics and handling for tasks already in flight. Removing a transition requires evidence that no persisted task still depends on it. Run old and new graphs against recorded event sequences in a staging environment, then deploy with a compatibility window. If rollback is needed, preserve states created by the newer version instead of coercing them into superficially similar older labels.
Expose a read-only state explanation to support teams: current state, time entered, expected releasing event, responsible role and safe escalation. Keep model-generated narrative separate from this operational view. This lets staff answer users accurately and prevents well-intentioned operators from forcing transitions through ad hoc database edits when a queue appears stuck.
Key takeaways
- Model one durable business task with explicit waiting, recovery and terminal states.
- Let models propose actions while deterministic guards own transitions.
- Use typed events, optimistic concurrency and durable command records for effects.
- Define completion, cancellation, expiry and budget exhaustion as operational invariants.
- Test the full graph under concurrency, duplicate events, upgrades and lost responses.
Frequently asked questions
Is a state machine too rigid for an AI agent?
No. The model remains flexible inside planning and interpretation states. The machine constrains lifecycle and effects that software must operate reliably. Add new states deliberately when the business discovers a real condition rather than allowing arbitrary runtime invention.
Should every tool call be a state?
Only when the call creates a meaningful waiting, authority or recovery boundary. Short read-only calls can remain within planning execution while still being traced. Consequential or asynchronous calls deserve durable command and reconciliation states.
Can event sourcing replace a current-state record?
An event log can reconstruct state, but operational systems often maintain a current-state projection for efficient locking and queries. Whichever pattern is used, events and projections need versioning, integrity and tested rebuild behavior.
Conclusion
An AI agent state machine converts autonomy into an operable transition system. It makes waiting visible, effects guarded, retries bounded and completion provable. Models contribute judgment where uncertainty exists, while application code retains authority over the states that determine business behavior.
Write the transition table before adding another tool or specialist. Then terminate workers, duplicate events and change policy while tasks are waiting. If the machine always produces a valid owned state and a safe next action, the agent loop has become production software rather than a persistent prompt.