Skip to main content
A flow’s state machine is the lifecycle of the entity moving through it. The entity sits in exactly one stage at a time, and a handler moves it forward by setting advances_to. schema.yaml declares that lifecycle, along with the flow’s public pins and the agent roles it needs. The support-ticket flow has this lifecycle: Each arrow is a handler’s advances_to, and the label is the event that triggers it. The self-arrow on assigned is the escalation retry loop.

​
Stages

An entity is in exactly one stage, set by a handler’s advances_to. Terminal stages are absorbing: once reached, new events are rejected and timers are cancelled. A flow that declares no stages: is stateless. Stages are also where stage timers attach — a timers: block on a stage can advance or escalate an entity that has sat too long; see Stages, gates, and timers. Every declared stage must be reachable: it is either the initial stage or the target of some advances_to (including a stage timer’s). The analyzer flags stages that nothing reaches (see Analyzer checks).

​
Pins

Pins are the flow’s public interface. Event pins declare what it accepts and emits; data pins declare what entity fields it reads and writes.
No two flows may write the same data pin; that conflict is a boot error. Events not listed in pins stay inside the flow and are delivered by subscription. Output event pins are how a flow talks to other flows — see Composing flows for how edges are declared.

​
Required agents

Leave required_agents out and Swarm infers the roles from agents.yaml. Write it and your list wins — even an empty list, which means this flow requires no agents. Declare it when someone else will supply the agents.
Fulfillment has two conditions, both checked at boot:
  1. An agent in agents.yaml whose map key matches the role name.
  2. That agent’s subscriptions cover the required subscribes_to, and its emit_events cover the required emits.

​
Acquiring an entity

A stateful flow’s input-pin handler must say how it gets the entity to operate on. It declares exactly one acquisition mode:
  • create_entity: true: mint a new entity at the initial stage.
  • select_entity: resolve exactly one existing flow-owned entity by a field you nominate as its identity (an order id, a ticket id).
  • select_or_create_entity: resolve one existing, or deterministically mint one.
Omitting all three on a stateful input-pin handler is a boot error. See Composing flows for cross-flow handoff patterns.
Older flows may use initial_state/terminal_states/states:; stages: is the current form and new features attach only to it.