Skip to main content
Agents are the half of Swarm that reasons. They read events, think, call tools, and emit results — but they never change state themselves.

​
What an agent is

An agent is an LLM session. It receives events, reasons inside a scoped session, calls tools, and emits events. An agent is defined in agents.yaml: its subscriptions, the events it may emit, its tools, its model tier, and whether it keeps memory. Agents never write entity state directly. They emit events; a system node handler decides what gets written. So every state change stays in deterministic hands.
agents.yaml
This agent receives ticket.assigned, keeps one durable conversation per flow instance (in a per-ticket template flow, that means one per ticket), and may emit ticket.resolved (which gives it an auto-generated emit_ticket_resolved tool). Its entity_writes let it write the resolution field through a generated save_ticket_resolution tool, the only entity write it is allowed. memory: true needs something to key the conversation on — one conversation per flow instance. So the agent must live in a flow that has instances (a template flow), not at the root; a root-level agent with memory: true fails at boot with an error that says exactly this. (If “root” and “child” are new here: a Swarm system is a tree of flows. The top one is the root; a flow it nests is a child. Composing flows covers how flows nest; you only need the root-vs-child distinction for the rule above.)

​
Isolation and hierarchical addressing

Each agent runs in a scoped session and observes only the events it subscribes to. A coordinator addresses managers; managers address workers; workers do not share a context window. Messaging scope is enforced and flow-instance-local; there is no “message anyone” default. Per-workspace mounts extend the isolation to the filesystem and process level: each agent (or each flow instance) gets its own /workspace, invisible to the others. See Agent workspaces and isolation for the mounts and scoping.

​
One role, many instances

When a single agent would be a bottleneck (it has to score 52 categories, or review 200 files), you run the role in parallel — declaratively.
  1. Split the work — one event per item (fan_out).
  2. Each event gets its own flow instance, and each instance its own copy of the agent — its own session, workspace, and lifecycle.
  3. Results converge where a join decides when the batch is done, drops duplicates, and enforces a deadline.
You declare how to split and what counts as done; the platform handles dispatch and identity. Each instance’s agent is a separate runtime agent — one per (declaration, instance) — so one instance finishing never touches a sibling’s agent. This is parallelism within one run. All of this runs on one deployment; Swarm does not distribute flow instances across machines.

​
Memory

memory is the one field that controls conversation persistence:
  • memory: false (the default): a fresh conversation per task. The agent sees the triggering event and its tools, does its work, and the conversation ends.
  • memory: true: one durable conversation whose scope is derived from the flow’s instance model — exactly one conversation per (run, agent, flow instance). In a mode: template flow that means one conversation per instance/entity: the agent builds context for one ticket, one customer, one startup over multiple turns.
There is nothing else to configure: no mode enum, no scope field. The platform derives the memory identity from where the agent is declared, checks it at boot, and never guesses — an agent with memory: true in a flow with no per-instance identity fails with an error that says exactly this naming the fix.

​
The tools an agent can call

An agent only sees the tools it can use; the platform never injects the full registry. The surfaces are:
  • Declared tools: entries in the agent’s tools list, resolved against the registry (platform_builtin, mcp, http).
  • Universal tools: agent_message and mailbox_send, auto-granted to every agent.
  • Emit tools: emit_{event_name}, auto-generated from the agent’s emit_events.
  • Role-scoped entity tools: read_*/save_*/update_*, generated from the flow’s entity contract and the agent’s entity_writes declaration.
  • Native tools: bash, web_search, file_io, gated by the native_tools field.
Anything outside these surfaces is rejected (default-deny). See Defining agents and prompts and Tools.