← All tutorials
Agent Topologies

Agent topologies

Once you have more than one thing doing work — an agent, a tool, another agent — you have to decide how they're wired together: who talks to whom, who decides what happens next, and where state lives. That wiring is the system's topology, and it matters more than the model choice. The same online-shopping assistant is a different product depending on whether one agent holds everything, agents form an assembly line, a manager delegates to specialists, or peers negotiate freely.

The one idea. A topology is the graph of an agentic system — the nodes (agents, tools, shared memory) and the edges (who can send a message or call whom), plus where control lives. Pick the simplest shape that fits the work; every extra node and edge you add is more latency, more tokens, and more ways to fail. We'll build the same shopping assistant five ways to feel the difference.

This page is about the shapes. For the decision logic that runs inside them — chaining, routing, orchestrator-workers, evaluator-optimizer — see Anthropic's agent patterns and Google's design patterns; for two frameworks that implement these shapes, AutoGen vs CrewAI.

Foundations  What is a topology?

Borrowed from networking, topology just means the arrangement of parts and their connections. For agents, three questions define it:

Nodes

Who does work?

Agents (LLM + instructions + memory), the tools they call, and any shared memory the system reads and writes.

Edges

Who can reach whom?

The allowed message paths and tool calls. A missing edge is a design decision — it's how you keep a peer from going rogue.

Control

Who decides next?

Fixed in code (deterministic), owned by one boss (centralised), or emergent from peers (decentralised).

Everything below is a different answer to those three questions. The running example: a user says “find me running shoes under $120 with good reviews and get them here by Friday.” That single request needs product search, review analysis, price/shipping comparison, cart, and checkout — and how you split and wire those jobs is the topology.

Topology ≠ framework. You can build any of these shapes in LangGraph, ADK, or Strands, in AutoGen or CrewAI, or in plain code. The shape is the architecture; the framework is just how you spell it.

Shape 1  Single agent (star)

One agent sits at the centre; tools radiate out like spokes. The agent reads the request, decides which tool to call, loops on the results, and answers. There are no other agents — just an augmented LLM with a toolbox.

Single-agent star topology One central agent connected by spokes to four tools: product search, reviews, cart, and checkout. Shoppingagent 🔎 search tool ⭐ reviews tool 🛒 cart tool 💳 checkout tool

Best for Most tasks, honestly. Start here. If one agent with clear tools and a good prompt can do the job, adding agents only adds cost and failure modes.

Breaks when The single prompt has to juggle too many unrelated responsibilities, the tool list grows past ~10–15 and the model picks wrong, or you need genuinely parallel work. That's the signal to split.

Don't multiply agents prematurely. A common mistake is jumping to a “crew” of agents when one agent with the right tools and context would be simpler, cheaper, and easier to debug. Each new agent is a new prompt to maintain, a new context window to fill, and another hop of latency. Split only when a single agent visibly strains.

Shape 2  Sequential pipeline (chain)

Fixed stages in a line: each agent (or step) does one job and hands its output to the next. Control is hard-coded — the order never changes. This is the agentic version of an assembly line, and the same idea as prompt chaining.

Sequential pipeline topology Four agents in a line: intake, research, compare, then purchase, each feeding the next. Intakeparse the need Researchfind products Comparerank on price+reviews Purchasecart & checkout

Best for Well-understood workflows with a natural order and no branching — ingest → transform → deliver. Deterministic, trivial to trace, cheap to reason about. Each stage can be tested in isolation.

Breaks when The task needs to loop back (“no shoe met the budget — search again with wider criteria”) or branch on content. A pure pipeline can't revisit an earlier stage without you bolting on control flow — at which point you're really building the next shape.

Add a validation gate. A cheap upgrade: after a stage, a lightweight check decides pass / retry / escalate before moving on — the evaluator–optimizer idea. It keeps the line's simplicity while catching the “zero results” and “over budget” cases.

Shape 3  Hierarchical supervisor (tree)

A supervisor (orchestrator, manager, router) owns the goal and delegates to specialist worker agents, then synthesises their results. Unlike a pipeline, the order isn't fixed — the supervisor decides at runtime who to call, how many times, and in what order. This is the workhorse of production multi-agent systems and matches orchestrator–workers and Google's coordinator/hierarchical patterns.

Hierarchical supervisor topology A shopping manager agent at the top delegating to three specialist worker agents below it. Shopping managerplans & delegates Product findersearch catalog Review analystsummarise ratings Deal & shippingprice + ETA

Best for Complex goals that decompose into distinct specialties, where you want central control and clean accountability. Workers can run in parallel (find products while another checks shipping windows), each with its own focused prompt and tools — smaller contexts, fewer wrong turns.

Breaks when The supervisor becomes a bottleneck or single point of failure, coordination overhead (its own tokens and latency) outweighs the parallel gains, or you stack too many layers of managers-managing-managers.

The supervisor is context glue, not a courier. Its job is to plan, route, and synthesise — not to shuttle every worker's full output through its own context window. Have workers return compact, structured results (a shortlist, a verdict), and keep bulky intermediate data in shared state or storage so the supervisor's window doesn't blow up.

Shape 4  Network / mesh (peer-to-peer)

No boss. Agents are peers that message each other directly and decide among themselves what to do next. The review analyst can ping the deal-finder without asking permission; control is decentralised and behaviour is emergent. This is the shape behind agent-to-agent protocols like A2A and “swarm” patterns.

Network / mesh topology Four peer agents each connected to the others with two-way links, no central controller. Productfinder Reviewanalyst Dealfinder Checkoutagent

Best for Open-ended, exploratory problems where the path can't be planned up front, and — increasingly — systems built by different owners: your shopping agent negotiating with a merchant's agent it has never met, discovered and called over A2A.

Breaks when You need predictability. Meshes are the hardest to debug (any path is possible), prone to chatter and infinite loops, costly (every hop is tokens), and hard to secure — a peer with a bad edge can drag the whole system off course. Most single-team products do not need a full mesh.

Bound the freedom. If you go peer-to-peer, add hard limits: a max message/turn budget, a stop condition (loop guardrails), and per-agent authority scopes so no peer can, say, actually place an order without a human or a supervisor signing off. Cross-owner meshes also need identity, auth, and trust — see agent security.

Shape 5  Shared-state blackboard (hub)

Agents don't message each other at all — they read from and write to a shared workspace (the “blackboard”): the current cart, candidate products, budget, constraints, deadlines. Each agent watches the board, contributes when it has something to add, and the board is the coordination. It decouples agents completely — they only need to agree on the shape of the shared state.

Shared-state blackboard topology Four agents around a central shared-state workspace, each with a two-way link to the workspace only. Shared workspacecart · candidates · budget Product finder Review analyst Deal finder Checkout agent

Best for Parallel contributors to one evolving artifact, and long-running or resumable sessions — the board is durable state you can persist, inspect, and pick back up. Great when many agents each own a slice of the same “shopping basket.”

Breaks when Concurrent writes collide (two agents editing the cart at once), the board grows into an unbounded dumping ground, or nothing decides the session is done. You've traded message-routing for state-management problems.

This is a concurrency problem in disguise. A shared board needs the same care as shared data anywhere: versioning or locking to avoid lost updates, a schema so writes stay structured, and a controller that decides when the goal is met. See concurrency design for idempotency and safe concurrent writes.

Reality  Hybrids & the real world

These five are primitives, not rival religions. Real systems compose them:

  • Supervisor of single-agents. The most common production shape: a hierarchical supervisor whose workers are each a single-agent-with-tools (Shape 3 wrapping Shape 1).
  • Pipeline with a smart stage. A deterministic line where one stage is itself a supervisor that dynamically decides how to research (Shape 2 containing Shape 3).
  • Supervisor over a blackboard. Workers write findings to shared state; the supervisor reads the board to decide the next move and when to stop (Shape 3 + Shape 5).
  • Mesh at the boundary. Your system is a tidy hierarchy internally, but talks peer-to-peer (A2A) to other organisations' agents at the edge (Shape 3 inside, Shape 4 outside).
The scaling instinct: start as a single agent; when it strains, promote the biggest sub-job to a supervisor+workers; reach for a blackboard when several agents share one artifact; use a mesh only where you truly can't predict the path or you're crossing an ownership boundary. Grow the topology to match the problem — don't pre-build the org chart.

The decision  Choosing a topology

Match the shape to the work along a few axes — chiefly how much control vs autonomy the task needs, and whether the path is known in advance.

TopologyControlBest whenMain cost
Single (star)Total, one promptOne agent + tools can do it — the defaultOverloaded prompt if scope grows
SequentialHard-coded orderFixed, well-understood, no branchingCan't loop or branch on content
HierarchicalCentral, dynamicDecomposable goals, parallel specialistsSupervisor bottleneck & overhead
Network / meshDecentralisedUnplannable paths; cross-owner agentsHard to debug, secure & bound
BlackboardVia shared stateParallel edits to one artifact; resumableConcurrency & state management
A three-question shortcut. (1) Can one agent with the right tools do it? → single. (2) If not, is the order fixed? → sequential; is it dynamic but you want one owner? → hierarchical. (3) Do agents need to contribute to one shared artifact (→ blackboard) or negotiate freely / across owners (→ mesh)? Answer top-down and stop at the first “yes.”

Watch out  Pitfalls & guardrails

💸 Token & latency blow-up

Every extra agent re-reads context and adds a round-trip. A five-agent mesh can cost 10× a single agent for the same result. Prefer the smallest topology; pass compact structured results between agents, not raw transcripts.

🔁 Loops & chatter

Decentralised shapes can ping-pong forever (“you decide” / “no, you decide”). Always set a turn/message budget and an explicit stop condition — the loop disciplines apply to every topology.

🧩 Context fragmentation

Split work across agents and no one holds the whole picture; decisions get made on partial views. Keep a source of truth (a supervisor's summary or a blackboard) and give each agent exactly the slice it needs — see context engineering.

🛡️ Authority & safety

The more autonomous the shape, the more an errant or injected agent can do. Scope each agent's tools to least privilege, and gate irreversible actions — placing the order, spending money — behind a human or a hard check, exactly as the self-restocking fridge gates auto-purchasing. Prompt injection travels between agents too; see AI/agent security.

End to end  Worked example: the shopping assistant, evolved

Watch the topology grow only as the problem forces it — the healthy path.

Stage 1 · Start as a single agent

“Find running shoes under $120 with good reviews, delivered by Friday.” One agent, four tools, a loop. Ships in an afternoon and handles the happy path.

# Single agent (star) — one loop, four tools
agent = Agent(
  instructions="You are a shopping assistant. Find items matching the "
               "user's budget, quality and delivery constraints, then buy.",
  tools=[search_products, get_reviews, compare_prices, checkout],
)
agent.run(user_request)   # model decides which tool, when, how often

Stage 2 · It strains — promote to a supervisor + workers

Users now want the assistant to weigh dozens of products, cross-check reviews, and compare shipping across sellers — all at once. One prompt juggling everything picks the wrong tool and blows its context. Split the specialties and let a supervisor delegate, in parallel.

# Hierarchical — supervisor delegates to focused workers (parallel)
finder   = Agent("Find candidate products for a query", tools=[search_products])
analyst  = Agent("Summarise review sentiment for given products", tools=[get_reviews])
deals    = Agent("Compare price + shipping ETA per product", tools=[compare_prices])

supervisor = Supervisor(
  instructions="Plan the search, delegate to workers, synthesise a shortlist.",
  workers=[finder, analyst, deals],
)
shortlist = supervisor.run(user_request)   # finder → (analyst ∥ deals) → merge
Why this and not a pipeline? Because the order is dynamic: sometimes the supervisor re-runs the finder with looser criteria when nothing fits the budget. A fixed line couldn't loop back; the supervisor decides at runtime.

Stage 3 · Long, resumable sessions — add a blackboard

Sessions now span days (“keep watching for a price drop”). Workers write candidates, prices, and the cart to durable shared state so the session survives restarts and multiple agents build one basket.

ConcernChoiceWhy
ShapeSupervisor + blackboardCentral control, but state outlives any single turn
Shared writesVersioned cart, per-field locksTwo agents editing the basket won't clobber each other (concurrency)
Stop conditionBudget met & in stock & ETA okSomething must decide the session is done
Irreversible stepCheckout gated on confirmationNo agent spends money without a hard check

Stage 4 · Cross the boundary — mesh only at the edge

To negotiate with a merchant you don't control, your supervisor talks peer-to-peer to the merchant's agent over A2A — a mesh edge bolted onto an otherwise tidy hierarchy. Internally you stayed centralised; you only went decentralised where ownership actually splits.

The lesson. The system ended up hybrid — single-agent workers, under a supervisor, over a blackboard, with a mesh edge — but each shape earned its place by solving a concrete problem the previous shape couldn't. That's topology done right: grown, not pre-designed.

Cheat sheet

QuestionShort answer
What's an agent topology?The graph of a system — nodes (agents, tools, shared state), edges (who reaches whom), and where control lives.
Where do I start?A single agent with tools. Add agents only when it visibly strains.
Fixed order, no branching?Sequential pipeline — deterministic, easy to trace.
Dynamic order, one owner?Hierarchical supervisor + workers — the production workhorse.
Parallel edits to one artifact?Shared-state blackboard — decoupled agents, one durable workspace.
Unplannable path / cross-owner?Network / mesh (A2A) — powerful but hardest to control & secure.
Biggest hidden cost of more agents?Tokens & latency — every hop re-reads context and adds a round-trip.
Universal guardrails?Turn budget + stop condition; least-privilege tools; gate irreversible actions.
How should topology evolve?Grown to fit the problem, not pre-built. Stop at the first shape that fits.

Knowledge check

Six questions. Pick an answer for each, then check your score.

1. What does an agent “topology” describe?

2. What's the recommended default shape for most tasks?

3. The key difference between a sequential pipeline and a hierarchical supervisor is…

4. In a shared-state blackboard topology, agents coordinate by…

5. When is a network / mesh topology most justified?

6. Which guardrail applies to every multi-agent topology?

Next steps

🔁 Anthropic agent architectures

The logic inside the shapes — chaining, routing, orchestrator-workers, evaluator-optimizer.

🧭 Google agent patterns

Predetermined vs dynamic routing — coordinator, hierarchical & swarm topologies.

🤝 AutoGen vs CrewAI

Two frameworks that implement these shapes — conversable agents vs role-based crews.

🕸️ WebMCP & A2A

The mesh edge — how agents discover and delegate to each other across owners.

🧵 Concurrency design

Safe shared state — the blackboard's real problem: concurrent writes & idempotency.

📡 IoT × Agents

A topology in the wild — a device event triggers an agent that reasons and buys, with guardrails.