Documentation for multi-agents

Teach your agents how to build swarms and sub-agents.

One skill URL with graph topologies, workers, nested swarms, tools, and test runs — so coding agents know how to design and run multi-agent systems.

Copy the setup command into your agent.

set up https://agentatlas.network/skill.md

Your agent fetches the skill doc and learns the swarm workflow.

Supervisor / Router
Orchestration · Topology
Popular
One coordinator routes work to specialists and merges results.
A hub worker classifies or decomposes incoming work, delegates to specialist workers, and synthesizes their outputs. Edges fan out from the supervisor and converge on a merge or final responder.
Verify3/5
Trace4/5
Speed3/5
Cost3/5
Pattern guide
ProblemMonolithic prompts hide routing logic and make it hard to swap specialists without rewriting the whole system.
When to use
Tasks decompose into distinct specialist roles (research, code, review).
You need a single owner for routing, retries, and final packaging.
Specialists can run with different models or tool sets.
When not to use
Every step must run in strict order with no branching.
Routing is trivial enough for one worker with tools.
Latency-sensitive paths where parallel fan-out is mandatory from the start.
Forces
Clear ownership at the hub
Low coupling between specialists
Easy to add or replace a specialist node
Agents1 supervisor + 2–4 specialists (typical 3–8)
Graphsupervisor → specialist_a · supervisor → specialist_b · specialist_a → merge · specialist_b → merge
Framework notes
LangGraph: Supervisor node with conditional edges to worker subgraphs; merge via reduce or final LLM node.
AutoGen: Group chat with a manager agent delegating to nested chats or registered agents.
LangChain τ-bench: Maps to the supervisor / swarm routing benchmark topology.
EvidenceCommon default in LangGraph tutorials and τ-bench swarm comparisons.
Pipeline + Critic
Quality · Topology
Plan, execute, then verify — each stage owns a narrow job.
Workers run in series: plan or spec, execute the main task, then a critic or verifier gates output before release. Control flow is mostly linear with an optional loop back on failure.
Verify5/5
Trace5/5
Speed2/5
Cost4/5
Pattern guide
ProblemSingle-pass generation skips explicit quality gates and makes regressions hard to catch before users see output.
When to use
High traceability — each stage has a named artifact.
Outputs must pass checks (policy, tests, rubric) before shipping.
Errors should loop back to an earlier stage with structured feedback.
When not to use
Subtasks are fully independent and can run in parallel.
Verification is cheap enough to embed in one worker prompt.
End-to-end latency dominates and serial stages are too slow.
Forces
Strong stage boundaries and audit trail
Explicit verify / retry loop
Higher latency than parallel fan-out
Agentsplanner + executor + critic (typical 3–6)
Graphplan → execute · execute → critic · critic → output (pass) · critic → execute (revise)
Framework notes
LangGraph: Linear StateGraph with conditional edge from critic back to execute.
AutoGen: Sequential chat or nested critic agent after primary completion.
CrewAI: Task chain with explicit review task and output guardrails.
EvidenceAligns with plan–execute–verify loops in production coding agents.
Parallel fan-out
Throughput · Topology
Fan work out to parallel workers, then merge downstream.
A router or splitter sends independent subtasks to parallel workers. A synthesizer or reducer merges partial results into one response. Maximizes throughput when subtasks do not depend on each other mid-flight.
Verify3/5
Trace3/5
Speed5/5
Cost4/5
Pattern guide
ProblemSerial pipelines waste wall-clock time when subtasks could run concurrently with separate context windows.
When to use
Subtasks are independent (multi-source research, parallel tool calls).
Wall-clock latency matters more than minimum token spend.
Merge logic is well defined (concat, vote, LLM synthesize).
When not to use
Later steps need intermediate results from earlier parallel branches in real time.
Merge quality is fragile and needs heavy sequential refinement.
Cost budget is tight — parallel LLM calls multiply spend.
Forces
Best wall-clock latency for divisible work
Higher aggregate cost than a single worker
Merge step is a common failure point
Agentsrouter + 2–5 workers + merge (typical 3–10)
Graphrouter → worker_a · router → worker_b · router → worker_c · worker_a → merge · worker_b → merge · worker_c → merge
Framework notes
LangGraph: Send API or parallel branches from a fan-out node into a reduce node.
AutoGen: Concurrent agent replies collected by a synthesizer.
CrewAI: Parallel task execution with a final aggregation task.
EvidenceStandard pattern for map-reduce style agent workflows.
Dynamic and Bio-mimetic Roles
Swarm · Cooperation
Autonomous agents with specialized roles that shift dynamically based on context.
Decentralized agents follow simple bio-mimetic rules (inspired by ant or bee colonies). Communication is local and minimal to optimize collaboration without centralized control.
Verify3/5
Trace2/5
Speed4/5
Cost2/5
Pattern guide
ProblemRigid roles in changing environments create bottlenecks and vulnerability when key agents fail.
When to use
The environment is dynamic and requires task adaptability.
You need high scalability and tolerance to individual agent failures.
Global or centralized communication is inefficient.
When not to use
A strict, predictable sequence of actions is required.
Centralized supervision or real-time auditing is critical.
Forces
High fault tolerance
Low coupling and minimal communication
Dynamic specialization
Agents10–20 agents with fluid roles (typical 5–50)
Grapha → b · b → c · c → d · d → e · e → f · f → a · a → d · b → e
Embedded LLMs and Self-evolution
Cognitive · Cooperation
Each agent integrates a lightweight LLM for local reasoning and autonomous adaptation.
Each swarm member runs a local LLM to interpret its environment and make decisions. They use P2P protocols to share state and implement a self-evolution module that adjusts strategies through collective feedback.
Verify3/5
Trace3/5
Speed2/5
Cost5/5
Pattern guide
ProblemAgents with static rules cannot adapt to complex global objectives or unexpected changes in environmental semantics.
When to use
Agents must interpret natural language or complex global objectives.
Continuous learning and improvement in swarm behavior is required.
When not to use
Devices with extremely limited compute resources.
Deterministic, formal behavior guarantees are required.
Forces
Advanced local reasoning
Self-organized semantic coordination
High resource consumption (tokens/compute)
Agents5–8 cognitive agents (typical 3–15)
Graphllm_a → llm_b · llm_a → llm_c · llm_a → llm_d · llm_a → llm_e · llm_b → llm_c · llm_b → llm_d · llm_b → llm_e · llm_c → llm_d · llm_c → llm_e · llm_d → llm_e
ReAct / Agentic Tool Loop
Agentic · Topology
Foundation
Single agent iterates through Reason → Act (tool call) → Observe until goal is reached — the building block of most real agents.
One capable agent loops through a think-then-act cycle. At each step it chooses a tool (web search, code exec, scrape, etc.), observes the result, and reasons again. No parallel workers — all complexity lives in the tool selection and prompt. The agent decides when the goal is met.
Verify3/5
Trace4/5
Speed3/5
Cost3/5
Pattern guide
ProblemMulti-worker graphs add coordination overhead when a single goal only requires iterative tool use, not parallel specialization or distinct roles.
When to use
A goal is achievable by one capable agent with the right tools (search, code exec, scrape).
The number of steps is unknown upfront — the agent decides when done.
Adding a second worker would only fan out the same tool set, not add real specialization.
When not to use
Tasks decompose into genuinely different roles needing different models or prompts.
You need guaranteed parallel throughput — the loop is serial by nature.
The loop could iterate infinitely — add a While node with maxIterations.
Forces
Simplest possible graph: one worker node
All intelligence lives in the agent prompt and tool selection
Hard to parallelise; add fan-out if throughput matters
Agents1 agent + 2–5 tools (typical 1–1)
Graphagent → tool_web · agent → tool_code · agent → tool_scrape · tool_web → agent (observe) · tool_code → agent (observe) · tool_scrape → agent (observe)
Framework notes
LangGraph: Single StateGraph node with tools list; conditional edge loops back until agent emits final answer.
AutoGen: ConversableAgent with function_map; loops via reply until termination condition.
CrewAI: Single-agent task with tool list; Process.sequential with self-reflection enabled.
agentatlas: One worker node with agentTools configured. Add a While control node with maxIterations cap if infinite loops are a risk.
EvidenceFoundation of OpenAI function calling, Claude tool use, and most single-agent production deployments.
Debate / Multi-perspective Judge
Verification · Cooperation
Two agents argue opposing positions; an independent judge synthesizes and decides — surfaces blindspots systematically.
A router sends the same task to two agents with deliberately different framings (Pro vs Con, Method A vs Method B, or Red Team vs Blue Team). An independent Judge agent reads both arguments and renders a structured verdict. The adversarial framing forces surface of counterarguments before committing to an answer.
Verify5/5
Trace4/5
Speed2/5
Cost4/5
Pattern guide
ProblemSingle-agent responses can be confidently wrong. Parallel analysts with the same framing produce correlated errors. A structured adversarial setup surfaces counterarguments and edge cases that single-perspective evaluation misses.
When to use
High-stakes decisions with two valid framings (policy, fact-check, legal review).
You want to explicitly surface counterarguments before committing to an answer.
The judge can be prompted with a structured rubric for evaluation.
When not to use
The task has no meaningful opposing perspective — debate adds cost without benefit.
Latency is the primary constraint — minimum 3 serial LLM calls.
Both agents will hit the same retrieval source and produce correlated outputs.
Forces
Surfaces blindspots and counterarguments systematically
Judge prompt quality determines final output quality
3× minimum LLM cost vs. single-agent approach
Agents2 debaters + 1 judge (typical 3–5)
Graphrouter → agent_pro · router → agent_con · agent_pro → judge · agent_con → judge · judge → output
Framework notes
LangGraph: Fan-out from router node to two parallel agent nodes, reduce into judge node.
AutoGen: Two-agent debate chat; third judging agent reads the conversation history.
agentatlas: Parallel fan-out to two worker nodes with opposing system prompts, converge on judge worker.
EvidenceUsed in constitutional AI evaluation, red-teaming, and high-stakes document review workflows.

Extended patterns

Series (pipeline)
Refinement · Topology
Sequential refinement — each worker passes output to the next (`A → B → C → D`).
Workers run in a strict chain with no parallel branches. Each stage transforms or enriches the artifact from the previous step. Simpler than Pipeline + Critic when you do not need an explicit verify loop.
Verify3/5
Trace4/5
Speed2/5
Cost3/5
Pattern guide
ProblemOne-shot generation cannot iteratively refine context — later steps lack structured handoffs from earlier specialists.
When to use
Work naturally decomposes into ordered phases (draft → expand → polish).
Each stage needs the full prior artifact, not partial parallel results.
Branching and merge logic would add complexity without benefit.
When not to use
Subtasks are independent and could run concurrently.
You need explicit quality gates or revision loops between stages.
A single worker with tools can cover the whole chain cheaply.
Forces
Maximum traceability per stage
Wall-clock time sums across stages
Easy to reason about and debug
Agents3–4 chained specialists (typical 2–6)
Grapha → b · b → c · c → d
Framework notes
LangGraph: Linear StateGraph — each node reads prior state and writes the next field.
AutoGen: Sequential chat or chained agent handoffs.
CrewAI: Tasks with explicit `context` from prior task outputs.
EvidenceBaseline pattern in CSIRO sequential workflow catalogue.
Parallel + synthesizer
Analysis · Topology
Independent analyses in parallel, then one synthesizer merges perspectives.
A router fans out to parallel analyst workers (research, code review, risk, etc.). A dedicated synthesizer worker merges divergent outputs into one coherent answer — stronger emphasis on merge quality than raw throughput fan-out.
Verify4/5
Trace4/5
Speed4/5
Cost5/5
Pattern guide
ProblemSingle-perspective analysis misses contradictions; concatenating parallel outputs produces incoherent bundles.
When to use
You need multiple independent lenses on the same input.
Merge quality matters — synthesis is a first-class step, not an afterthought.
Analysts can disagree; the synthesizer resolves or ranks findings.
When not to use
Parallel branches produce identical artifact types that only need concatenation.
Synthesis is trivial enough for the router to handle inline.
Cost of N analysts plus a synthesizer exceeds budget.
Forces
Richer coverage than one monolithic analyst
Synthesizer is the quality bottleneck
Higher cost than parallel fan-out without dedicated merge
Agentsrouter + 2–4 analysts + synthesizer (typical 4–10)
Graphrouter → analyst_a · router → analyst_b · router → analyst_c · analyst_a → synthesizer · analyst_b → synthesizer · analyst_c → synthesizer
Framework notes
LangGraph: Map-reduce with a dedicated reduce/s synthesizer node and structured analyst outputs.
AutoGen: Parallel nested chats feeding a summarizer agent.
CrewAI: Parallel tasks converging on a final aggregation task with rubric.
EvidenceCommon in multi-source research and due-diligence agent demos.
Hybrid
Complex workflows · Topology
Mixed control flow — parallel branches, conditionals, and sequential stages in one graph.
Combines routing, parallel fan-out, if/else control nodes, and serial refinement in a single swarm. Use when real tasks need different shapes in different phases — not one pure topology end to end.
Verify4/5
Trace4/5
Speed3/5
Cost4/5
Pattern guide
ProblemForcing a pure supervisor, pipeline, or fan-out pattern onto heterogeneous workflows creates awkward workarounds and hidden state.
When to use
Phases differ: e.g. parallel research → sequential draft → conditional deploy path.
Control nodes (if/else, while) belong between worker stages.
You have test traces proving which branches fire in production.
When not to use
A simpler topology covers 90% of runs — start there first.
Team cannot maintain or debug multi-shape graphs yet.
No observability — hybrid flows fail silently in unexpected branches.
Forces
Highest expressiveness for real-world tasks
Hardest to test and document
Requires strong trace inspection in agentatlas test panel
Agentsrouter + parallel block + serial tail + controls (typical 5–12)
Graphrouter → parallel_block · parallel_block → ifelse · ifelse → serial_tail (pass) · ifelse → router (retry) · serial_tail → output
Framework notes
LangGraph: Compose subgraphs — parallel Send blocks, conditional edges, nested StateGraphs.
AutoGen: Mix group chat routing with nested sequential teams.
agentatlas: Use control nodes (if/else, while) between worker nodes; validate `sourceHandle` on branch edges.
EvidenceProduction swarms often evolve into hybrid graphs after v1 linear or supervisor designs.
Centralized LLM and Distributed Agents
Orchestration · Topology
A central LLM as cognitive orchestrator for simple executor agents.
A single LLM hub interprets global state and dispatches adaptive directives to lightweight executor nodes. Unlike Supervisor/Router — where workers are full LLM agents with their own reasoning — executors here can be APIs, scripts, or physical actuators that only carry out instructions. All cognition is centralized; use this when you want cheap or zero-LLM executors.
Verify4/5
Trace4/5
Speed3/5
Cost3/5
Pattern guide
ProblemGiving every agent an LLM is costly and inefficient, but a purely reactive swarm lacks strategic direction.
When to use
Complex centralized planning is required with distributed physical or local execution.
A limited budget prevents running LLMs on every node.
When not to use
Environments with critical latency or frequent loss of connectivity to the central node.
A single point of failure (the central LLM) is unacceptable.
Forces
Coherent centralized planning
Low cost on executor nodes
Vulnerability to single point of failure
Agents1 controller + 5–10 executors (typical 4–20)
Graphcentral_llm → executor_1 · central_llm → executor_2
Cohesion Control and Formal Guarantees
Control · Verification · Research only
Research
Nonlinear control models and formal algorithms to ensure stability under noise.
Uses control layers based on nonlinear dynamics and mathematical algorithms to ensure global cohesion and dynamic stability of the swarm in noisy environments with changing topologies.
Verify5/5
Trace3/5
Speed4/5
Cost2/5
Pattern guide
ProblemPurely heuristic or learning-based swarms can diverge or become unstable under real-world perturbations.
When to use
Critical physical systems (such as UAVs or mobile robotics) where collision or dispersion is catastrophic.
Environments with high communication noise and highly dynamic topologies.
When not to use
Purely software or data processing tasks without physical dynamics.
Early exploration phases where stability metrics have not been defined.
Forces
Mathematical stability guarantees
Robustness against environmental noise
High mathematical and modeling complexity
Agents20–50 controlled nodes (typical 5–100)
Graphn1 → ctrl · n2 → ctrl · n3 → ctrl · n4 → ctrl · n5 → ctrl · ctrl → n1 (adjust) · ctrl → n3 (adjust) · n1 → n2 · n2 → n3 · n3 → n4 · n4 → n5 · n5 → n1
Compact Representation and Learning (MARL)
Learning · Cooperation · Research only
Research
State compression via mean embeddings or tensor factorization for reinforcement learning.
Agents use compact representations of their neighbors to reduce communication overhead. Employs multi-agent reinforcement learning (MARL) and separates centralized training from distributed/asynchronous execution.
Verify3/5
Trace2/5
Speed5/5
Cost4/5
Pattern guide
ProblemExponential growth of state space and communication saturates the system as the number of agents scales.
When to use
Large-scale systems (hundreds of agents).
A simulation environment is available for offline training.
When not to use
Systems with few agents where compact representation loses useful precision.
Prior or simulated training is not feasible.
Forces
Massive theoretical scalability
Drastic bandwidth reduction
Costly and complex training phase
Agents50–100 agents with MARL (typical 10–1000)
Graphtr1 → tr2 · tr2 → tr3 · tr1 → ex1 (policy) · tr1 → ex2 (policy) · tr2 → ex2 (policy) · tr2 → ex3 (policy) · tr3 → ex3 (policy) · tr3 → ex4 (policy)
Minimalist Homogeneous Swarm
Bio-inspired · Cooperation · Research only
Research
Identical agents with simple binary or single-bit communication.
Simple, homogeneous agents interact locally through minimalist communication protocols (such as WOSP). Based on emergent collective behavior without requiring global synchronization or complex messages.
Verify2/5
Trace2/5
Speed5/5
Cost1/5
Pattern guide
ProblemHeavy communication protocols cause network collisions and high energy consumption on constrained hardware.
When to use
Extremely simple or inexpensive hardware.
Area coverage, patrol, or simple dispersion tasks.
When not to use
Complex plan coordination or symbolic reasoning is required.
Forces
Minimal hardware cost
Ultra-light collision-free protocol
Extremely simple individual behavior
Agents100+ homogeneous agents (typical 10–10000)
Graphh1 → h2 · h2 → h3 · h4 → h5 · h5 → h6 · h1 → h4 · h2 → h5 · h3 → h6
Hierarchical Swarm with Metaheuristics
Optimization · Cooperation · Research only
Research
Dynamic hierarchies and hybrid optimization via PSO and genetic algorithms.
Forms temporary hierarchies by assigning leaders based on context. Combines swarm behavior with optimization metaheuristics (such as Particle Swarm Optimization and genetic algorithms) to solve complex tasks in 3D spaces.
Verify4/5
Trace3/5
Speed3/5
Cost3/5
Pattern guide
ProblemLack of temporal structure makes it hard to solve complex subtasks that require sequencing.
When to use
Route optimization in 3D spaces (e.g. UAV swarms).
Tasks that benefit from temporary hierarchical division.
When not to use
Flat two-dimensional environments or simple text processing.
Forces
Efficient global optimization
Adaptable leadership without rigidity
Complexity in synchronizing leaders
Agents12–24 agents with sub-leaders (typical 6–40)
Graphl0 → l1 · l0 → l2 · l1 → l2 (peer) · l1 → f1 · l1 → f2 · l2 → f3 · l2 → f4
Asynchronous Modular Swarm
Modular · Cooperation
Modular roles (explorers, gatherers, coordinators) with asynchronous messaging.
Based on SwarmSys, agents are divided into specialized modules for specific roles. They operate in iterative phases for continuous adaptation and communicate via asynchronous messages for flexibility and scalability.
Verify3/5
Trace4/5
Speed4/5
Cost3/5
Pattern guide
ProblemSynchronous communication blocks agents and reduces exploration and gathering speed.
When to use
Search, exploration, or distributed resource gathering tasks.
Systems where temporal decoupling of tasks is beneficial.
When not to use
Systems that require immediate synchronous consensus at every step.
Forces
Clear task specialization
Complete temporal decoupling
More complex global monitoring
Agents3 roles × 4 agents each (typical 6–30)
Graphsc1 → coord (async) · sc2 → coord (async) · coord → ga1 (task) · coord → ga2 (task) · coord → sc1 (feedback) · sc1 → sc2 · ga1 → ga2
Human-in-the-loop Gate
Safety · Verification
A human approval checkpoint pauses the swarm until a person approves, rejects, or redirects — essential for irreversible actions.
An approval gate node interrupts execution flow and waits for human input before continuing. On approval the graph proceeds to the action node; on rejection it loops back to a revision worker. Adds an explicit human control point without changing the rest of the graph structure.
Verify5/5
Trace5/5
Speed1/5
Cost2/5
Pattern guide
ProblemFully autonomous swarms can confidently take irreversible actions (send emails, deploy code, charge cards) with no checkpoint. Adding explicit gates makes risk visible, auditable, and controllable.
When to use
Actions are irreversible: send, publish, deploy, charge, delete.
Regulatory or compliance requirements mandate human sign-off.
Output quality variance is high enough that human review adds reliable value.
When not to use
Humans are unavailable in the time window required by the task.
The action is fully reversible and cost of error is low.
Full automation is the explicit product requirement.
Forces
Makes irreversible risk explicit and auditable
Blocks throughput — latency is bounded by human response time
Adds compliance-grade accountability trail
Agents1–2 workers + 1 approval gate + human (typical 2–6)
Graphworker → gate · gate → continue (approve) · gate → revise (reject) · revise → worker
Framework notes
LangGraph: langgraph.interrupt() blocks execution and waits for external resume signal.
AutoGen: Human proxy agent in the chat loop with reply=human_input.
agentatlas: Use the built-in user_approval control node — sources: approve → continue, reject → revise loop.
EvidenceStandard safety pattern in production agentic workflows handling financial, legal, or irreversible operations.
Nested Swarm Delegation
Composition · Topology
An orchestrator delegates complex subtasks to specialized child swarms as callable black boxes — enables reusable modular composition.
A top-level orchestrator agent decomposes work and invokes child swarms as tools (run_swarm). Each child swarm encapsulates a full multi-step workflow; the parent only sees inputs and outputs. Enables modular composition of complex systems without exposing internal graph structure across boundaries. Child swarms can be developed and tested independently.
Verify4/5
Trace3/5
Speed2/5
Cost5/5
Pattern guide
ProblemA single flat graph becomes unmanageable as task complexity grows. Nesting swarms as black-box tools enables reuse, independent testing, and team ownership of sub-workflows without coupling internal state.
When to use
A subtask is complex enough to warrant its own multi-worker graph.
The same child workflow is reused across multiple parent swarms.
Teams own different swarms independently — loose coupling is required.
When not to use
The subtask is simple enough for one worker with tools.
Cross-swarm real-time state sharing is required — nesting hides internal state.
Latency budget is tight — each nested run adds call overhead.
Forces
Maximum composability — child swarms are reusable, independently testable
Clean boundary: parent only sees swarm input/output
Debugging requires tracing into child run history separately
Agents1 orchestrator + 2–3 child swarms (3–5 workers each) (typical 4–20)
Graphorchestrator → sub_a · orchestrator → sub_b · sub_a → merge · sub_b → merge · merge → output
Framework notes
LangGraph: Subgraph nodes compiled separately; parent graph invokes them as nodes with their own state schemas.
AutoGen: Nested GroupChat or ConversableAgent wrapping an inner chat manager.
agentatlas: Add swarm control node to parent graph; configure swarmTools on the orchestrator worker to expose child swarms as callable tools.
EvidenceCommon in production agentic systems: a research swarm feeds a drafting swarm, each independently versioned.

Teach your agents how to build swarms and sub-agents.

Supervisor / Router

Pipeline + Critic

Parallel fan-out

Dynamic and Bio-mimetic Roles

Embedded LLMs and Self-evolution

ReAct / Agentic Tool Loop

Debate / Multi-perspective Judge

Series (pipeline)

Parallel + synthesizer

Hybrid

Centralized LLM and Distributed Agents

Cohesion Control and Formal Guarantees

Compact Representation and Learning (MARL)

Minimalist Homogeneous Swarm

Hierarchical Swarm with Metaheuristics

Asynchronous Modular Swarm

Human-in-the-loop Gate

Nested Swarm Delegation