One-Line Summary: The shape of how agents connect — single, supervisor-led, mesh, hive mind, queen-led, or adaptive — is a deliberate design decision with concrete cost, latency, and reliability consequences, not an emergent property of running multiple agents.
Prerequisites: Sub-agents as primitives, agent-to-agent communication, what is an AI harness
Status: Module 03 anchor concept — first draft. Authoring backlog: bespoke
ExplorerAHOTopologyAsDesignDecisioninteractive (animated topology toggler) per the plan file.
What Is Topology in a Multi-Agent System?
Topology is the wiring diagram. It answers: which agent can talk to which, who can spawn whom, who decides when work is done, and who owns the shared state. The same set of three reviewer sub-agents can be wired as a supervisor pattern (one orchestrator, three workers, results aggregated), as a mesh (every agent talks to every other agent until consensus), or as a queen-led hierarchy (a "queen" agent allocates and arbitrates work). The choice changes everything about cost, latency, debuggability, and failure modes.
The vocabulary has consolidated around a handful of named topologies: single agent, supervisor / orchestrator, mesh, hive mind, queen-led hierarchy, adaptive / runtime-switching. Each is appropriate for different problem shapes.
How It Works
A topology is implemented in two layers. The first is who can call whom — enforced by which sub-agents the harness allows each agent to spawn, and which tools each can use to send messages. The second is who decides termination — supervisor (the orchestrator stops when satisfied), majority (the swarm votes), unanimous (every agent must agree), queen (a designated arbiter decides). Real systems combine these layers explicitly; the bugs in multi-agent demos almost always live in the combination, not in either layer alone.
Why It Matters
Cost scales with the number of agents that get invoked per turn. Latency scales with the longest path in the topology. Reliability is determined by who has veto power. Choosing a topology is choosing the shape of those trade-offs. A queen-led topology amortizes coordination cost across many workers but creates a single point of failure; a mesh has no SPOF but burns tokens on cross-talk; a supervisor pattern is the default because it is the cheapest topology that beats single-agent on quality for many tasks.
How Harnesses & Frameworks Implement This
| Harness / Framework | Built-in topologies | How you switch |
|---|---|---|
| Claude Code | Single + supervisor (via sub-agents) | Add sub-agent definitions in agents/ |
| Claude Agent SDK | Single, supervisor, hand-off chains | Agent.handoffs = [...] |
| ruflo | Queen-led, mesh, hive mind, adaptive | Plugin/topology config |
| LangGraph | Whatever you draw — graph is explicit | StateGraph edges |
| AutoGen | Conversational round-robin, group chat, hierarchical | GroupChatManager strategy |
| CrewAI | Sequential, hierarchical | process=Process.sequential / Process.hierarchical |
| OpenAI Agents SDK | Single + handoffs | Agent.handoffs |
| Codex CLI | Single | N/A |
| Cursor | Single (agent mode) | N/A |
Connections to Other Concepts
queen-led-hierarchy.md,mesh-topology.md,hive-mind-pattern.md,supervisor-pattern-deep-dive.md— The named topologies expanded.topology-selection-decision-tree.md— The how-to-choose flowchart.../../ai-agent-concepts/05-multi-agent-systems/hierarchical-agent-systems.md— Foundational coverage; this concept extends it with harness-level mechanics.../../ai-agent-concepts/05-multi-agent-systems/swarm-and-emergent-behavior.md— Foundational coverage of swarms; this course covers the harness-level affordances that make swarms practical.
Further Reading
- Anthropic, "Building Effective Agents" (2024) — Argues for the supervisor topology as the default.
- ruvnet, ruflo — The reference implementation of queen-led and adaptive topologies in production.