Problem
Agents attempt actions that are invalid in the current state, such as editing a submitted claim, because nothing tells them the rules in advance.
Context
Use this pattern when:
- Resources follow a lifecycle with rules about which transitions are allowed.
- Different actors (agent, human, system) may trigger different transitions.
Recommended solution
Document each resource's states and transitions as data. Include the current state and allowed transitions in every response, and reject illegal transitions with an error that names the current state and the allowed alternatives.
- 01Define states and transitions as data, not scattered conditionals.
- 02Include current state and allowed transitions in responses.
- 03Use optimistic concurrency (versions) to prevent conflicting transitions.
Interaction diagram
Example implementation
Illustrative exampleExamples use a fictional store and illustrative field names. Adapt the shape to your stack; the qualities matter more than the exact format.
export const claimMachine = {
initial: "draft",
states: {
draft: { on: { submit: "submitted", discard: "discarded" } },
submitted: { on: { withdraw: "draft", approve: "approved", reject: "rejected" } },
approved: { on: { pay: "paid" } },
rejected: { on: { appeal: "submitted" } },
paid: { final: true },
discarded: { final: true },
},
} as const;Accessibility and security
Accessibility
- State names exposed to agents should match the status labels people see in the UI.
Security
- Restrict which transitions agents may trigger; approval and payment transitions often belong to humans or systems.
Related patterns
DiscoveryAction DiscoveryExpose the actions available on a resource in its current state, alongside the resource itself.InteractionMulti-step WorkflowsModel long tasks as named workflows with explicit steps, persistent state, and resumable progress.FeedbackExecution StatusGive long-running actions a status resource that agents can poll or subscribe to.
Applies the principles Transparent State and Predictable Actions.