Concepts overview

This section explains what Swarm is, independent of how you author any one contract. Read it once to build the mental model; the Build a flow and Reference sections show the exact syntax.

​

Two kinds of actor, and only one changes state

Every actor you declare is one of two kinds, and the split is the whole idea:

• A system node is deterministic code, no prompt and no model. It owns state: it advances the entity, sets gates, writes fields, and emits events.
• An agent is an LLM session. It reasons inside a scoped session, calls tools, and emits events carrying its results. It never writes state directly.

Both communicate the same way, by emitting typed events. What differs is what each is trusted with. An agent can propose an outcome by emitting an event; a system node decides what that event actually changes. So an agent can never leave the entity in a state it only claimed to reach, the way it could if it were also the bookkeeper. Reading it: an event routes to its subscribers by their declared subscriptions, never by an LLM. A subscribing system node runs its handler and commits the state change in one transaction; a subscribing agent reasons and emits its own event. Notice that only the system node touches state. Both kinds of emitted event re-enter the loop and route to their own subscribers. A third kind of actor is the human: a stage can wait on a typed decision gate, and the verdict — decided from the CLI, the API, or a chat channel on a phone — is just another event entering the same loop, with every outcome declared in the contract. The split holds even here: the human supplies the judgment, but the state change is still committed by the gate’s declared outcome running through a deterministic handler — a person decides, a node writes. And a fourth is implicit: the runtime itself handles transitions you never declare, such as a stage timer firing or a flow’s own lifecycle.

​

The nouns to keep separate

​

The runtime in six sentences

1. A flow declares its stages, pins, and agents.
2. System nodes subscribe to events and own deterministic transitions.
3. Agents subscribe to events and handle reasoning work.
4. Events move work through the system: they are the only communication mechanism.
5. Each handler execution commits atomically.
6. The platform stores everything itself: entity state, every event, every field change, agent sessions, timers, and runs.

​

How a transition executes

When an event reaches a system node, its handler runs through a fixed dependency graph, not the order you wrote the fields in, and commits in one transaction. Grouped into stages: No LLM decides what fires next. Routing is derived from declared subscriptions, and every step commits together, so a crash mid-handler leaves no partial state. For the exact stage order and the short-circuits that stop a handler early, see System nodes and handlers.