Agentic Frameworks & Coordination

3 — Agentic State Machines

Make agent progress an explicit set of states, guarded transitions, and durable events so every action has a permitted execution context.

Concept overview

An agentic state machine defines named states and the events that can move a run between them. States represent operational facts such as awaiting evidence, ready for review, or committed; they should not claim to expose the model's private reasoning. Transition guards enforce business invariants outside the model.

The model can propose an event or classify an observation, but deterministic transition code decides whether it is legal. Persist the state version alongside the transition event to prevent concurrent workers from both advancing the same run. State design is therefore a concurrency and authorization decision as much as an orchestration technique.

Why it matters in production

Proof of concept

A proof of concept often uses booleans such as approved and finished. Replace ambiguous combinations with a small explicit state model before adding external writes.

Production

Production adds transition guards, optimistic concurrency, expiration events, and an operator view. Terminal states must explain whether work succeeded, failed, or was cancelled.

Enterprise scale

Enterprise deployments require machine-version migration and compatibility for old runs. A new release cannot assume that every persisted execution starts at the first state.

Architecture components

State definition

Names legal states, terminal states, accepted events, and transition guards.

Transition service

Atomically verifies expected state version and records the next state.

Event inbox

Deduplicates callbacks and delivers observations to the correct execution instance.

Action dispatcher

Starts side effects only after the relevant transition is durably accepted.

State inspector

Exposes current state, blocked conditions, and permitted operator interventions.

The architecture, mapped

Controlled supplier onboarding states — An uncertain activation enters reconciliation instead of blindly issuing another creation request.

stateDiagram-v2
 [*] --> Collecting
 Collecting --> Assessing: Required documents received
 Assessing --> Reviewing: Assessment validated
 Assessing --> Collecting: Evidence missing
 Reviewing --> Activating: Authorized approval
 Reviewing --> Rejected: Reviewer rejects
 Activating --> Active: Directory confirms creation
 Activating --> Reconciling: Outcome unknown
 Reconciling --> Active: Existing supplier verified
 Active --> [*]
 Rejected --> [*]

Competing callbacks use versioned transitions — Conditional writes expose conflicting events so the application can resolve them under explicit transition policy.

sequenceDiagram
 participant A as Callback A
 participant B as Callback B
 participant S as Transition service
 participant D as State store
 A->>S: Approval for state version 7
 B->>S: Cancellation for state version 7
 S->>D: Commit approval if version is 7
 D-->>S: Accepted as version 8
 S->>D: Commit cancellation if version is 7
 D-->>S: Version conflict
 S-->>B: Reload current state and apply policy

Runtime flow

1
Create instance
Bind workflow version, business identifier, and initial state in durable storage.
2
Receive event
Authenticate its source and deduplicate its event identifier before considering a transition.
3
Evaluate guard
Check required evidence, authority, and expected state version using trusted services.
4
Commit transition
Atomically record the accepted event and next state; reject competing stale updates.
5
Dispatch action
Start the permitted task through an outbox or equivalent reliable boundary.
6
Handle completion
Convert success, rejection, timeout, or cancellation into explicit subsequent events.

Supplier onboarding with explicit approval

Enterprise operations · Illustrative enterprise scenario, not a reported customer outcome.

Business situation

A multinational distributor onboards suppliers across procurement, finance, and compliance teams.

The problem

Email-driven status changes permit activation before bank-detail verification or after an approval has expired.

Agent requirement

The agent must gather documents and assess completeness while activation remains gated by verified review.

Architecture

A durable state machine coordinates collection, assessment, approval, activation, and ambiguous-outcome reconciliation.

Runtime

A document callback moves a supplier from collection to assessment only when all required document types are present.
An approved assessment enables activation; the directory's confirmed identifier is required before the state becomes active.

Failure scenario

If the activation call times out, the run enters reconciliation and checks for an existing supplier before any retry.

Operational impact

Monitor time spent in each state, rejected transitions, stale approvals, and reconciliation backlog to reveal process bottlenecks.

Architecture tradeoffs

Decision	Benefit	Cost
Explicit states	Illegal action sequences become testable and visible.	Excessive state granularity can make evolution cumbersome.
Atomic transitions	Concurrent callbacks cannot silently overwrite progress.	Contention and storage availability affect advancement.
Versioned machines	In-flight work remains interpretable across releases.	Migration logic and operational tooling require maintenance.

Failure scenarios & recovery

Duplicate approval arrives after cancellation

Detect: Transition guard sees a terminal state and rejects the event.

Recover: Record the rejected callback without reopening the supplier.

Worker crashes after transition commit

Detect: State advances but no task completion appears.

Recover: Redeliver the outbox action using the original operation identity.

Common architecture mistakes

Using free-form text as workflow state

Store an enumerated state and separate explanatory notes.

Letting the model bypass a guard

Evaluate authority and prerequisites in application code.

Changing state names without migration

Pin machine versions and explicitly map compatible transitions.

When to choose this pattern

Choose it when

Actions require strict ordering and durable approval boundaries.
Callbacks and workers may race to update one business process.
Operators need clear recovery options for interrupted runs.

Avoid it when

A stateless read request has no meaningful lifecycle.
A simple DAG already describes all allowed execution paths.
No owner can define the business invariants for transitions.

Architecture checklist

Name terminal states and their business meaning.
Require expected versions on transition writes.
Deduplicate incoming events before transitions.
Test every forbidden transition explicitly.
Design recovery from action outcome uncertainty.
Define migration behavior for old running instances.