Loading patterns…

🔄

Graph State Machines

Finite state machines implemented as graphs for workflow control

Complexity: mediumWorkflow Orchestration

In 30 seconds

What: Models workflow as states connected by guarded transitions, executing deterministic paths based on events and validation rules.
When to use: Multi-stage processes with clear state boundaries, rollback needs, and conditional branching based on step outcomes.
Watch out: State explosion and maintenance burden grow quickly as edge cases and error paths multiply beyond initial design.

Ask the AI expert about this pattern

Opens the assistant with your question prefilled. You review it before sending.

Get this catalog as an MCP server Tune a prompt for this pattern

Finite state machines implemented as graphs for workflow control

State transition management
Event-driven execution
Deterministic flow control
State validation and guards
Rollback capabilities
Visual workflow representation

The Agent Architect

One pattern, one tradeoff, one production failure story. A short weekly briefing for people building agentic systems.

Weekly email, one-click unsubscribe. We only use your address to send the briefing.

References

The papers, specifications, and repositories this pattern is based on.

Harel (1987): Statecharts - A Visual Formalism for Complex Systems
Murata (1989): Petri Nets - Properties, Analysis and Applications
Workflow Patterns (van der Aalst et al.)

From the engineer behind this catalog

Get your agent architecture reviewed

This page documents one pattern. Your system runs dozens, and most failures live in how they fit together. Have the whole design reviewed against the 288 patterns in this catalog: architecture, reliability, evaluation and cost, every finding mapped to the pattern that fixes it.

€750 instead of €1,500, one week, written report and walkthrough call, until 30 September

See the review

Patterns

Loading patterns…

Design Patterns & Techniques

Loading patterns…

🔄

Graph State Machines

Finite state machines implemented as graphs for workflow control

Complexity: mediumWorkflow Orchestration

In 30 seconds

What: Models workflow as states connected by guarded transitions, executing deterministic paths based on events and validation rules.
When to use: Multi-stage processes with clear state boundaries, rollback needs, and conditional branching based on step outcomes.
Watch out: State explosion and maintenance burden grow quickly as edge cases and error paths multiply beyond initial design.

Ask the AI expert about this pattern

Opens the assistant with your question prefilled. You review it before sending.

Get this catalog as an MCP server Tune a prompt for this pattern

Core Mechanism

Graph State Machines represent control flow as states (nodes) and event-driven transitions (edges) with guard conditions and actions. Statecharts augment this with hierarchical states, orthogonal regions (parallelism), and history to capture complex real-world behavior. This gives deterministic, auditable flow control for agent/tool invocations, approvals, retries, and human-in-the-loop checkpoints.

Workflow / Steps

Enumerate states (initial, intermediate, terminal) and define state/context schema.
List events; define transitions with guards and actions (include error/timeouts as events).
Design the graph: priorities/defaults per state; add hierarchy/parallel regions if using statecharts.
Implement pure transition logic; run side effects in effect handlers with retries and idempotency.
Persist state + minimal context; version the machine; enable visualization from source.
Test transitions (table-driven), fuzz guards, and validate invariants; add observability.

Best Practices

Minimize state explosion: encode data checks in guards, not separate states.

Use statecharts for hierarchy/parallelism; leverage history for resumption.

Keep transition functions pure; isolate I/O and side effects with idempotency keys.

Model failures/timeouts explicitly; add compensations and rollback paths.

Source-of-truth diagrams from machine definition; review diffs in PRs.

Persist only necessary context; externalize large artifacts via URIs; protect sensitive data.

Comprehensive tests for guards/transitions; property tests for safety invariants.

When NOT to Use

Simple linear flows where a straight-line function or DAG is clearer and cheaper.

Heavy dataflow/ETL where stream/DAG engines fit better than event-guard machines.

Ultra low-latency paths sensitive to event loop/guard evaluation overhead.

Strict ACID cross-service transactions; prefer workflow engines with sagas/transactions.

Common Pitfalls

State explosion from encoding fine-grained data conditions as states rather than guards.

Ambiguous or overlapping guards; missing default transitions → nondeterminism.

Embedding side effects inside transitions → non-determinism and retry hazards.

Missing persistence/idempotency → unrecoverable or duplicated effects on retry.

Parallel regions without proper isolation → races and deadlocks.

Key Features

Deterministic event→transition semantics with guards and actions

Hierarchical and parallel states (statecharts); history/restoration

Explicit error/timeout and compensation transitions

Visual models and formal reasoning about reachability/invariants

Composable submachines; reuse via regions and invoked machines

KPIs / Success Metrics

Transition coverage and unreachable-state detection in tests.

Mean steps-to-completion; time-in-state distributions; p50/p95 per transition.

Failure/compensation transition rates; replay/resume success rates.

For LLM steps: tokens per state and per run; cost per run; cache hit rate.

Token / Resource Usage

Drivers: per-state LLM/tool calls, validation/self-check prompts, and context growth in state data.

Controls: per-state token budgets; summarize/trim context; cache deterministic steps; bound concurrency.

Storage/CPU: persist minimal state + references; avoid logging sensitive context; instrument per-transition cost.

Best Use Cases

Order/approval/fulfillment flows with retries, compensations, and human approvals.

Agent/dialog controllers gating tool calls and safety checks per step.

Compliance workflows requiring deterministic replay and audit trails.

Device/process controllers with hierarchical/parallel modes.

References & Further Reading

Academic Papers

Implementation Guides

Tools & Libraries

XState/Statecharts, AWS Step Functions, Temporal, Camunda BPMN 2.0
LangGraph, LlamaIndex Workflows

Community & Discussions

Finite state machines implemented as graphs for workflow control

State transition management
Event-driven execution
Deterministic flow control
State validation and guards
Rollback capabilities
Visual workflow representation

The Agent Architect

One pattern, one tradeoff, one production failure story. A short weekly briefing for people building agentic systems.

Weekly email, one-click unsubscribe. We only use your address to send the briefing.

References

The papers, specifications, and repositories this pattern is based on.

Harel (1987): Statecharts - A Visual Formalism for Complex Systems
Murata (1989): Petri Nets - Properties, Analysis and Applications
Workflow Patterns (van der Aalst et al.)

From the engineer behind this catalog

Get your agent architecture reviewed

€750 instead of €1,500, one week, written report and walkthrough call, until 30 September

See the review

Loading patterns…

Graph State Machines

In 30 seconds

Ask the AI expert about this pattern