Skip to content
⚠️ Before You Start
Risk: Medium
Duration: 3-4 hours
Last Validated: Not yet validated (draft)
Kind: Decision guide
Risk Note: Medium (wrong topology multiplies tokens and failure modes)

Choose a multi-agent topology: sequential, parallel, supervisor, handoff or debate

Draft outline: not validated

Drafted with AI from official sources on 16 Oct 2026. Do not use on a live system until it is written, dry-run by someone other than the author and signed off (planned 2026-12-14). Author: Sivaraj · dry-run: Yogeshwaran · sign-off: James. Work items: AGT-06-T01, AGT-06-T02, AGT-06-T03, AGT-06-T04.

1. Summary

When a use case seems to need more than one agent, or an existing multi-agent system is slow, costly or unreliable.

Risk: Medium (wrong topology multiplies tokens and failure modes). Typical duration: 3-4 hours.

2. When to use and when not to

Use it when: When a use case seems to need more than one agent, or an existing multi-agent system is slow, costly or unreliable.

Do not use it when: to be written by the author.

3. What you must know first

  • One agent with skills or routing often beats several agents
  • Subagents, handoffs, skills and router patterns trade off parallelism, user interaction and cost
  • Agent Framework ships sequential, concurrent, handoff, group chat and Magentic orchestrations
  • Group chat and Magentic need hard termination limits
  • Shared state needs a single writer or a merge rule

4. Options

Outline of the decision process; the author describes each option.

  1. Test whether a single agent with routing meets the need
  2. Map tasks to the topology rows in the decision YAML
  3. Estimate model calls per task for the chosen topology
  4. Define who owns shared state and how conflicts merge
  5. Set hop, round and token limits
  6. Prototype on ten tasks and compare with the single-agent baseline
  7. Record the decision

Draft snippet: Topology decision record with limits

# docs/decisions/multi-agent-topology.yaml
use_case: ${USE_CASE}
first_question: can one agent with skills or routing do this?
topologies:
  sequential:
    choose_when: fixed order of specialist steps, each output feeds the next
    stop_rule: last agent finishes
  parallel:
    choose_when: independent subtasks, latency matters
    stop_rule: all branches return or timeout; aggregator merges
  supervisor:
    choose_when: mixed tasks, central routing, one owner of the answer
    stop_rule: supervisor emits FINISH or hop limit reached
  handoff:
    choose_when: the active specialist talks to the user for several turns
    stop_rule: termination condition or user ends
  debate_group_chat:
    choose_when: quality gains from critique outweigh extra tokens
    stop_rule: approval phrase or max rounds
chosen: supervisor
limits:
  max_hops: 6
  max_tokens_per_task: ${TOKEN_BUDGET}
shared_state_owner: supervisor (workers return results, never write shared fields directly)

Snippets to add:

  • snippets/docs/decisions/multi-agent-topology.yaml: Topology decision record (yaml)
  • snippets/docs/design/state-ownership.md: State ownership table (markdown)

5. Decision table

Situation Choose Why
to be written

To be written by the author from the outline above.

7. Known issues and fixes

Symptom Likely cause Fix
Debate adds cost but not quality No measurable critique benefit Drop to a single reviewer pass or none
Agents overwrite each other's results No single writer Make the supervisor the only writer of shared fields
Users bounced between specialists Handoff used where routing fits Route once at the start

8. Monitoring and alerts

Signal Alert when Action
Agent invocations per task More than 2x the design estimate weekly Review the topology

9. AWS and open-source equivalents

Bedrock Agents multi-agent collaboration (supervisor with collaborators) is now classic; AWS points new work to AgentCore. OpenAI Agents SDK offers handoffs and agents as tools.

10. Validation record

Pending. Planned dry-run scenario: A second engineer applies the guide to three sample use cases and must reach the agent lead's topology and limits, including choosing a single agent for at least one.

11. Sources