State Machines

Understanding how AgentML uses deterministic state machines to govern agent behavior.

Agent Behavior as a State Machine

At its heart, an AgentML agent is a deterministic state machine. Each possible situation the agent can be in is a state, and you explicitly define how the agent transitions between states in response to events. This contrasts with systems that rely purely on the LLM's response to determine what happens next.

Benefits of State Machines

Determinism & Predictability

All transitions are pre-defined, so the agent's behavior is not left to chance. Given the same sequence of events, the agent will always follow the same path.

Formal Semantics

Built on the W3C SCXML standard, inheriting well-defined semantics for concurrency, event queuing, etc. You can even formally verify properties of the agent if needed.

Clear Separation of Concerns

The LLM is responsible only for generating structured events (data) and not for controlling the flow. The state machine logic controls the flow.

How It Works

In practical terms, this means you design how an agent should behave (states and transitions) and use the LLM to handle unstructured input or complex decision-making within the guardrails of those transitions.

AgentML's <transition> can specify which event name triggers it, and if that event requires certain data payload.

Example: Flight Booking State

<transition event="intent.flight.search"
            event:schema='{
              "type": "object",
              "properties": {
                "category": {"const": "flight"},
                "action": {"const": "search"}
              }
            }'
            target="handle_flight_search"/>

In this example, you might have event="intent.flight.search" trigger a transition to a flight booking state, only if the event data includes a "flight" category and proper structure. The LLM's job would be to produce an event matching one of the expected names/structures.

Key Concepts

States

Each state represents a distinct situation or phase in your agent's workflow. States can be nested hierarchically and can have entry/exit actions.

Transitions

Transitions define how the agent moves from one state to another in response to events. They can have conditions and execute actions during the transition.

Events

Events trigger transitions. They can come from the LLM, external systems, or be raised internally by the agent itself.

Best Practices

Design Tip

Always ensure each state has a clear purpose. If you find yourself with an explosion of states for every tiny variation, consider using the LLM's output to differentiate within a state. Conversely, if a single state's logic is getting too implicit, break it into states for clarity.

Next Steps

Now that you understand state machines, learn how events and schemas work together to constrain LLM outputs.

Events & Schemas →