Spring State Machine
Spring framework for implementing finite state machines in Java/Kotlin. Spring State Machine models: States (IDLE, RUNNING, FAILED, COMPLETED), Events (START, COMPLETE, FAIL, RESET), Transitions (IDLE → RUNNING on START event), Guards (conditional transitions), Actions (execute code on state entry/exit/transition), and hierarchical/orthogonal state machines. Supports persistence (JPA, Redis, MongoDB) for distributed stateful workflows. Spring Boot auto-configuration for stateMachineFactory bean. Used for modeling agent workflow states, order processing pipelines, document approval workflows, and any process with discrete states and transitions.
Score Breakdown
⚙ Agent Friendliness
🔒 Security
State machine library — no direct security concerns. Persisted state machine data may contain agent PII in state context; encrypt at persistence layer. Protect state machine event endpoints from unauthorized state transitions via Spring Security.
⚡ Reliability
Best When
Your agent workflow has clearly defined states, events, and transition rules that need to be enforced — Spring State Machine makes implicit agent state explicit, persistent, and observable.
Avoid When
Your process has fewer than 5 states (use enums), you don't need persistence or distributed state, or your team needs simpler workflow tooling (use Spring Batch or Temporal).
Use Cases
- • Model agent task lifecycle with Spring State Machine — states: QUEUED, PLANNING, EXECUTING, WAITING_TOOL, COMPLETED, FAILED; events: START, TOOL_CALLED, TOOL_RETURNED, COMPLETE, ERROR; guards prevent invalid transitions
- • Persist distributed agent workflow state — Spring State Machine with JPA/Redis persistence stores agent state machine state in database for multi-instance agent services with failure recovery
- • Implement agent approval workflow — document review state machine with states DRAFT, PENDING_REVIEW, APPROVED, REJECTED; transitions driven by agent review events with guard conditions on review completion
- • Orchestrate multi-step agent onboarding — stateful onboarding flow UNVERIFIED → EMAIL_SENT → EMAIL_CONFIRMED → PROFILE_COMPLETE → ACTIVE with event-driven transitions and entry actions that trigger agent onboarding tasks
- • Handle agent conversation states — GREETING, COLLECTING_INFO, PROCESSING, RESPONDING, WAITING_CLARIFICATION with transitions driven by NLU classification events for structured agent conversation management
Not For
- • Simple boolean flags — if your 'state machine' has 2-3 states with simple transitions, use enums and if/else; Spring State Machine complexity is justified only for non-trivial state models
- • Stream/batch processing — Spring State Machine is for stateful workflow orchestration; use Spring Batch for bulk data processing, Spring Cloud Stream for event stream processing
- • Teams unfamiliar with FSM concepts — state machine design requires upfront modeling; without understanding guards, actions, and transition semantics, Spring State Machine becomes a tangled mess; model the FSM on paper before coding
Interface
Authentication
State machine library — no auth concepts. Persistence backends (JPA, Redis) use application's auth configuration.
Pricing
Spring State Machine is Apache 2.0 licensed, maintained by Broadcom/VMware. Free for all use.
Agent Metadata
Known Gotchas
- ⚠ Guard failures are silent by default — when a guard returns false, the event is silently ignored and the state machine stays in current state; add StateMachineListener to detect and log declined agent transitions for debugging
- ⚠ StateMachine is not thread-safe — concurrent sendEvent() calls cause state corruption; use StateMachineFactory to create one state machine per agent conversation/request and don't share across threads
- ⚠ Persisted state machine requires synchronous context — JPA-persisted state machines need transaction context on each event; @Transactional on calling service; missing transaction causes LazyInitializationException when loading persisted agent state
- ⚠ Hierarchical states require careful initial state config — sub-states must define their own initial state; missing initial state in sub-state region causes NullPointerException on entry; always define initial state for every region in agent workflow hierarchical states
- ⚠ State machine factory vs singleton — @EnableStateMachine creates singleton state machine (single instance per context); @EnableStateMachineFactory creates per-call instances; agent workflows requiring isolated state per conversation must use factory, not singleton
- ⚠ Spring State Machine 3.x to 4.x migration removed UML support — if using Spring State Machine with UML diagram export in 3.x, 4.x removed this feature; agent workflow visualization requires alternative tooling or manual diagram maintenance
Alternatives
Full Evaluation Report
Detailed scoring breakdown, competitive positioning, security analysis, and improvement recommendations for Spring State Machine.
Scores are editorial opinions as of 2026-03-06.