Skip to content
AX Framework
Interaction pattern

State Transitions

Publish the state machine for important resources so agents know which changes are legal.

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.

  1. 01Define states and transitions as data, not scattered conditionals.
  2. 02Include current state and allowed transitions in responses.
  3. 03Use optimistic concurrency (versions) to prevent conflicting transitions.

Interaction diagram

Interaction diagram for State Transitions. 1. AI agent to Product · AX layer: PATCH claim (version 3). 2. Product · AX layer to AI agent: 409 invalid_transition: submitted. 3. AI agent to Product · AX layer: POST withdraw_claim. 4. Product · AX layer to AI agent: status: draft, version 4.AI agentProduct · AX layerPATCH claim (version 3)1409 invalid_transition: submitted2POST withdraw_claim3status: draft, version 44
request response internal step

Example implementation

Illustrative example

Examples use a fictional store and illustrative field names. Adapt the shape to your stack; the qualities matter more than the exact format.

claim-states.tsts
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.

Applies the principles Transparent State and Predictable Actions.