Swarm Canvas

The Swarm Canvas at /swarms is the screen where single agents become teams. It is a visual graph editor where each node is either an agent or a control-flow primitive, each edge is a message route between them, and the runtime can execute the whole graph for you, streaming every node's tokens, tool calls, and decisions live as the swarm runs. The canvas is built on React Flow with a custom runtime that we designed specifically for multi-agent systems, and the goal of every design decision was to make the failure modes of multi-agent systems visible — because those failure modes are the entire reason multi-agent systems are hard.

Why a visual canvas at all

Multi-agent systems can of course be built in code, and many excellent libraries — LangGraph, AutoGen, CrewAI, Strands — exist to do exactly that. The reason AgentSwarms ships a canvas in addition to code export is that the shape of a multi-agent system is the most important property of it, and shapes are far easier to reason about visually than as nested function calls. Looking at a swarm on the canvas tells you in a single glance which agents are involved, where the parallel paths are, where the bottlenecks are, and where the human-in-the-loop checkpoints sit. Reading the same swarm as Python takes ten times as long and is much more likely to mislead you about the actual control flow.

Building blocks

The canvas exposes a small, deliberately complete set of node types. Every multi-agent pattern we have seen in production — planner-executor, reflection loops, router-and-responder, debate, blackboard, hierarchical — can be expressed using combinations of the following primitives. Adding more primitives was a constant temptation during design, and we resisted it because the small set composes more reliably than a large set ever does.

• Agent node wraps any agent from your library and is the workhorse of the canvas. From inside the node you can either click "New agent" to open the full Agent Builder in a side drawer and create a brand-new agent without leaving the canvas, or click "Import existing" to attach one of your previously-saved agents. Once attached, the agent's prompt, model, and tools are all editable in place: small tweaks during canvas debugging do not require a context switch into the agent library.
• Trigger node is the entry point of the swarm. It can be a chat input (the swarm becomes chatable in the playground), a webhook (the swarm exposes a stable HTTPS URL external systems can POST to), a schedule (the swarm runs on a cron expression you configure), or a file upload (the swarm runs whenever a file is dropped into a configured inbox).
• Router or classifier node uses a small model to read the incoming payload and choose one of N downstream branches. The classification rubric is editable as a prompt and the decision is logged in the trace so you can debug mis-routings after the fact.
• Parallel fan-out node sends the same input down N branches concurrently. The runtime executes the branches in parallel where possible, which is the right choice for embarrassingly-parallel work like "summarise these five documents at the same time".
• Aggregator or join node waits for multiple upstream branches to complete and merges their outputs into a single payload using a configurable strategy: concatenate, take the highest-confidence result, run a small LLM-based merge, or vote. The aggregator is what closes the fan-out pattern.
• Loop node re-runs a sub-graph until a condition is met. The condition can be a critic agent passing a rubric, a structured-output validator succeeding, or a simple maximum-iteration count. This is the primitive that implements reflection and self-correction patterns.
• Human-in-the-loop approval node pauses the swarm and posts an approval card to your dashboard inbox containing the exact payload waiting on your decision. The swarm resumes within seconds of you approving, rejecting, or editing-and-approving the payload.
• Tool node is a raw callable — an HTTP request, a SQL query, a knowledge-base lookup — without a wrapping agent. Useful when you want deterministic behaviour at a particular step and do not need a model to decide anything.
• Output or sink node formats the final result of the swarm and returns it to whatever invoked the swarm: the playground UI, the webhook caller, or the schedule handler.

Canvas features

The canvas itself has the editing affordances you would expect from a graph editor, and a handful of agent-specific ones you would not. Every feature in the list below earned its place by being something a real user hit a wall without; the canvas was built iteratively against actual usage rather than designed in one shot.

• Drag-to-connect ports support type-checked edges in four flavours: plain text, structured JSON, lists, and images. The runtime refuses to start a run with mismatched edge types and the connecting port flashes red when you try.
• Live run mode lights up each node as it executes, with the model's token stream visible inside the node. Tool calls appear as smaller sub-nodes that animate into existence as the agent decides to call them. This is the best way to watch how an unfamiliar swarm actually behaves.
• Step-through debugger can be enabled before a run, in which case the runtime pauses between every node and lets you inspect the payload, edit it in place, and resume. Invaluable for understanding exactly where a swarm is going wrong without sprinkling print statements throughout.
• Mini-map, snap-to-grid, multi-select drag, and grouping are the table-stakes editor affordances. Groups can be collapsed and expanded, which keeps large swarms readable on a single screen.
• Version history records every save as a named version with a diff against the previous one. Rolling back is one click and never destructive: rolling back creates a new version on top of history rather than discarding the work in between.
• Templates are the recommended starting point for any new swarm. Loading a template instantiates a fully- wired canvas you can run immediately, with the guided tour available from the toolbar.
• Pattern tour is an animated overlay that identifies and explains each recognised pattern in the current swarm: "this is a planner-executor", "this is a reflection loop", "this is a router-and-responder". The tour is particularly useful when remixing a community swarm whose design intent is not obvious from the node names.
• Variables panel defines named inputs the whole swarm shares. Trigger nodes can populate variables from their incoming payload, and any agent node can reference variables in its prompt with the standard double-brace template syntax.
• Test runner stores a set of named inputs and their expected outputs and can replay them on demand, flagging any regression in cost, latency, or output content against a reference run. This is the closest thing AgentSwarms has to unit tests for agentic systems.
• Export can produce LangGraph code, Strands code, portable AgentSwarms JSON, or a tools-only export that packages the swarm's tool surface as a standalone toolbelt you can call from any framework.
• Publish sends the swarm to /community/swarms after running the publish quality check (no plaintext secrets, a description above the minimum length, at least one screenshot, no PII detected in any node's prompt).

Building a new swarm from scratch

Building a swarm from a blank canvas is something we generally recommend you put off until you have remixed two or three templates first, but when the time comes the workflow is designed to be as forgiving as possible. The recommended order of operations is to drop a trigger node first, then sketch the happy path with agent nodes connected end to end, then add branching (routers, fan-outs) where the happy path needs to diverge, then close the branches with aggregators, and only finally add reflection loops and human-in-the-loop checkpoints. Adding the loops and HITL nodes last keeps the topology readable while you are still figuring out the basic shape.

Adding agents inside the canvas

Two paths exist for putting an agent into a node, and the right choice depends on whether the agent is reusable beyond this swarm. Both paths feel native inside the canvas; you do not have to navigate away to the agents page in either case.

• "New agent" on an agent node opens the full Agent Builder in a side drawer overlaid on the canvas. You configure the agent exactly as you would on the agents page, and on save the agent is created in your library and immediately attached to the canvas node. This is the right path when the agent is generic enough that you might want to reuse it in another swarm or chat with it directly in the playground.
• "Import existing agent" opens a picker listing every agent in your library, with filters by model, provider, and tags. Selecting one attaches it to the node; subsequent edits to the agent from the canvas propagate back to the canonical agent in the library, so changes you make while debugging a swarm carry over.

Recommended workflow on the canvas

Independent of which pattern you are building, the most effective day-to-day workflow on the canvas tends to follow the same sequence. Adopting it explicitly will save you a lot of accidental complexity.

• Start from a template, run it once unmodified with the guided tour open, and read the trace produced by that run end-to-end before changing anything. You are calibrating your mental model of the swarm against reality.
• Replace exactly one agent with a candidate of your own (right-click the node → "Replace with agent from library"), run the swarm again with the same input, and diff the two traces. This is the cheapest way to learn what your agent actually does in this context.
• Add a critic loop using a Loop node and a small critic agent before doing anything else. Almost every multi-agent system in production has some flavour of critic loop, and adding one early shapes the rest of the design.
• Wrap any external write (an outbound email, a refund, a database insert) with a human-in-the-loop approval node well before you start considering the swarm ready for anyone else to use.
• Open Swarm Observability after a representative run and use the critical-path highlight to find the slow node and the expensive node. Those are nearly always the next things to optimise.

 [trigger]──▶ [router]──▶ [research agent]──┐
                  │                          │
                  └──▶ [classifier agent]──▶ [aggregator]──▶ [critic loop]──▶ [HITL]──▶ [sink]
                                              ▲                  │
                                              └──── fail ────────┘