agent-multi-agent-design

name: agent-multi-agent-design description: > Guide the design of multi-agent systems -- topologies (single agent, network, supervisor, hierarchical), supervisor patterns, control flow strategies, workflows as tools, combining patterns, and the A2A protocol for cross-framework agent communication. Use when the user is building systems with multiple cooperating agents, needs to coordinate specialized agents, wants to add a supervisor/orchestrator, or is connecting agents across different frameworks. Also use when user mentions "multi-agent", "supervisor agent", "agent orchestration", "A2A", "agent-to-agent", "agent coordination", "agent hierarchy", or asks how to make multiple agents work together.

Multi-Agent System Design

Think of multi-agent systems like a specialized team at a company. Different agents have specialized roles and work together to accomplish complex tasks. The challenge is organizational design: who does what, who talks to whom, and how decisions get made.

Multi-Agent Topologies

Six common arrangements, from simplest to most complex:

1. Single Agent

One LLM with multiple tools. Start here.

        [LLM]
       / | | \
     T1  T2 T3 T4   (tools)

2. Network (Peer-to-Peer)

Multiple specialized agents that gossip among themselves until consensus:

  [Agent A] <--> [Agent B]
       \           /
        [Agent C]

3. Supervisor

One agent coordinates and delegates to specialized agents:

        [Supervisor]
       /     |      \
   [Agent A] [Agent B] [Agent C]

4. Supervisor (Agents as Tools)

Specialized agents are wrapped as tools the supervisor can call:

    [Supervisor LLM]
     / |            \
   T1  T2  [Agent A as Tool]  [Agent B as Tool]

5. Hierarchical

Supervisors of supervisors. Fractal design:

          [Top Supervisor]
         /                \
  [Sub-Supervisor A]   [Sub-Supervisor B]
    /       \              /       \
[Agent 1] [Agent 2]   [Agent 3] [Agent 4]

6. Custom

Any arrangement of agents and workflows tailored to your specific needs.

Key principle: Start with the simplest topology (single agent) and add complexity only when needed.

The Supervisor Pattern

The most common multi-agent pattern. A supervisor agent coordinates specialists.

Implementation

Pass specialized agents in as tools that the supervisor can call:

const publisherAgent = new Agent({
  name: "publisherAgent",
  instructions: "You are a publisher that coordinates content creation.
    First call the copywriter for initial content.
    Then use the editor for refinement.",
  model: "claude-sonnet-4.6",
  tools: { copywriterTool, editorTool },
});

When to Use

• You have clearly separable sub-tasks
• Different tasks need different prompts, models, or tools
• You want a central point of coordination

Control Flow Strategies

Plan Before Executing

Just as a PM specs features before commissioning engineering work:

1. Agent creates an architectural plan
2. User reviews and approves the plan
3. Agent executes the plan step by step
4. Agent checks in at key milestones

This is critical for code generation tools (Replit, bolt.new, Lovable) and complex multi-step tasks.

Workflows as Tools

Turn deterministic processes into workflow tools the agent can call:

Agent has 3 tasks to accomplish.
Instead of one big LLM call:

Task 1 --> Workflow A (defined steps, order, structure)
Task 2 --> Workflow B
Task 3 --> Workflow C

Agent calls each workflow as a tool.

Advantage: More certainty. You can stipulate a workflow's order of steps and provide more structure than a free-form LLM call.

Combining Patterns

In practice, agents embody different steps in a workflow:

Planning Agent --> (user approval) --> Code Writing Agent
                                           |
                                    Code Reviewer Agent
                                           |
                                      (user sees result)

All primitives (agents, workflows, tools) can be rearranged to match the control flow you want.

A2A Protocol (Agent-to-Agent)

What A2A Solves

MCP connects agents to tools. A2A connects agents to other agents across different frameworks.

Without A2A: N different agents on M different frameworks = N x M custom integrations. With A2A: Each agent implements one protocol.

How It Works

1. Agent publishes a /.well-known/agent.json metadata file (capabilities, endpoint URL, auth)
2. After authorization, agents exchange tasks via a queuing system
3. Tasks have states: submitted, working, input-required, completed, failed, canceled
4. Communication over HTTP + JSON-RPC 2.0
5. Streaming via Server-Sent Events for longer tasks

A2A vs. MCP

Current Status

A2A is Google-originated and younger than MCP. Microsoft supports it, but OpenAI and Anthropic have not yet adopted it. MCP may evolve to cover agent-to-agent use cases. Expect consolidation.

Decision Framework

Gotchas

• Designing multi-agent systems is organizational design. Think job descriptions, not code modules.
• Start with a single agent. Split into specialists only when the single agent becomes unwieldy.
• A hierarchy is just a supervisor of supervisors. Start with the simplest version first.
• Workflows as tools give you more certainty than free-form agent calls.
• The plan-then-execute pattern is critical for complex tasks. Don't skip the planning step.
• A2A is early and adoption is uncertain. Build with MCP today; watch A2A for cross-framework needs.
• Network (peer) topologies sound cool but are hard to debug. Supervisor topologies are more predictable.

For detailed implementation examples, see references/multi-agent-examples.md.