Multi-Agent Systems With Claude: The Coordinator Pattern That Powers Everything

Agent Teams, subagents, coordinator-subagent — everyone's confused. Here's the foundational pattern with working code, and when each approach actually makes sense.

---

Claude shipped Agent Teams. Everyone is excited.

Nobody is explaining the foundational pattern that makes all of it work.

Before you use Agent Teams or Claude Code subagents, you need to understand the coordinator-subagent pattern at the API level.

This is the mental model everything else is built on — and it works in production today.

---

The Core Idea

A single agent handling everything is inefficient.

It has to:

• Research
• Write
• Review
• Decide

This leads to context overload and weaker outputs.

The coordinator-subagent pattern solves this.

One coordinator agent:

• Receives the task
• Breaks it down
• Delegates to specialists
• Synthesizes results

Each subagent:

• Has its own context window
• Has its own system prompt
• Has its own tools

The coordinator doesn’t do the work.

It decides who does.

---

Pattern 1 — Coordinator-Subagent (Pure API)

Flow:

• User request → Coordinator
• Coordinator → tool_use → routes to subagent
• Subagent executes task
• Result → back to coordinator
• Coordinator → end_turn → final answer

Key rule: Subagents never talk to each other. Everything routes through the coordinator.

---

Working Example (Python)

import boto3

client = boto3.client("bedrock-runtime", region_name="us-east-1")

SUBAGENT_PROMPTS = {
"research_agent": "You are a research specialist. Be factual.",
"writer_agent": "You are a writing specialist. Use only provided context.",
"reviewer_agent": "You are a reviewer. Return APPROVED or NEEDS_REVISION."
}

def run_subagent(agent_name, **kwargs):
content = "\n".join(f"{k}: {v}" for k, v in kwargs.items())
response = client.converse(
modelId="anthropic.claude-3-sonnet-20240229-v1:0",
system=[{"text": SUBAGENT_PROMPTS[agent_name]}],
messages=[{"role": "user", "content": [{"text": content}]}]
)
return response["output"]["message"]["content"][0]["text"]

def run_coordinator(user_request):
messages = [{"role": "user", "content": [{"text": user_request}]}]

for _ in range(15):
response = client.converse(
modelId="anthropic.claude-3-sonnet-20240229-v1:0",
messages=messages
)

stop_reason = response["stopReason"]
output = response["output"]["message"]
messages.append(output)

if stop_reason == "end_turn":
return output["content"][0]["text"]

elif stop_reason == "tool_use":
# Example routing logic
result = run_subagent("research_agent", task="example")
messages.append({
"role": "user",
"content": [{"text": result}]
})

return "Safety cap reached"

---

Pattern 2 — Claude Code Subagents

Same concept, different environment.

Inside Claude Code:

• Main agent spawns subagents via Task tool
• Each subagent runs in isolated context
• Results return to main agent only

Key rule: Subagents report upward — no sideways communication.

Best for: local development workflows like testing, security checks, documentation.

---

Pattern 3 — Agent Teams (Experimental)

Agent Teams introduce peer-to-peer communication.

Agents can talk directly to each other:

• Researcher → Writer
• Writer → Reviewer

Tradeoffs:

• More powerful collaboration
• 3–4x higher token cost
• Experimental, not production-ready

---

Pattern Comparison

Pattern	Peer Communication	Production Ready	Best Use Case
Coordinator-Subagent	No	Yes	Production API agents
Claude Code Subagents	No	Yes	Developer workflows
Agent Teams	Yes	Experimental	Collaborative agents

---

The Critical Mistake

Subagents share nothing.

You must explicitly pass context.

# WRONG
research = run_subagent("research_agent", task="research AWS")
writer = run_subagent("writer_agent", task="write blog")

# RIGHT
research = run_subagent("research_agent", task="research AWS")
writer = run_subagent("writer_agent", task="write blog", context=research)

This isolation prevents context pollution — but requires deliberate design.

---

What Comes Next

Once you understand this pattern, advanced systems become straightforward:

• Retry logic controlled by coordinator
• Parallel subagent execution
• Dynamic routing based on results
• Human-in-the-loop escalation

Everything builds on the same loop.

---

Build It Hands-On

This pattern is covered in the Claude Certified Architect (CCA-001) track.

22 hands-on labs, real AWS Bedrock sandboxes, automated validation.

Start building multi-agent systems →

---

What are you building — production API agents or Claude Code workflows?