183 lines
5.0 KiB
Markdown
183 lines
5.0 KiB
Markdown
---
|
||
title: "Sub-Agents vs Agent Teams: The Architecture Decision That Changes Everything"
|
||
source: "https://x.com/Suryanshti777/status/2047694444787577236"
|
||
author:
|
||
- "[[@Suryanshti777]]"
|
||
published: 2026-04-24
|
||
created: 2026-04-26
|
||
description: "Most AI Systems Are Built WrongMost people reach for multi-agent systems the moment a task feels complex. That’s usually the wrong instinct...."
|
||
tags:
|
||
- "clippings"
|
||
---
|
||

|
||
|
||
Most AI Systems Are Built Wrong
|
||
|
||
Most people reach for multi-agent systems the moment a task feels complex. That’s usually the wrong instinct.
|
||
|
||
The real question isn’t “should I use multiple agents?” It’s “what kind of coordination does this task actually need?”
|
||
|
||
That answer determines everything about your architecture.
|
||
|
||
Claude-style systems give you two distinct approaches: sub-agents and agent teams. They may look similar, but they solve completely different problems.
|
||
|
||

|
||
|
||
Sub-Agents: Parallelism with Isolation
|
||
|
||
A sub-agent is a specialized instance that runs in its own isolated context. Think of it like delegation. You assign focused work, it returns a clean result.
|
||
|
||
Each sub-agent gets:
|
||
|
||
A system prompt defining its role
|
||
|
||
A limited set of tools
|
||
|
||
A completely isolated context
|
||
|
||
A single, well-scoped task
|
||
|
||

|
||
|
||
When it finishes, it returns only the final output, not reasoning or intermediate steps.
|
||
|
||
This matters because sub-agents are about compression, not just speed. They turn messy exploration into a clean signal.
|
||
|
||
There are strict constraints:
|
||
|
||
Sub-agents cannot talk to each other
|
||
|
||
Sub-agents cannot spawn new agents
|
||
|
||
Everything flows through the parent
|
||
|
||
This keeps the system predictable and clean.
|
||
|
||
Here’s what it looks like in practice:
|
||
|
||
```python
|
||
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition
|
||
|
||
async def main():
|
||
async for message in query(
|
||
prompt="Review the authentication module for issues",
|
||
options=ClaudeAgentOptions(
|
||
allowed_tools=["Read", "Grep", "Glob", "Agent"],
|
||
agents={
|
||
"security-reviewer": AgentDefinition(
|
||
description="Find vulnerabilities and security risks",
|
||
prompt="You are a security expert.",
|
||
tools=["Read", "Grep", "Glob"],
|
||
model="sonnet",
|
||
),
|
||
"performance-optimizer": AgentDefinition(
|
||
description="Identify performance bottlenecks",
|
||
prompt="You are a performance engineer.",
|
||
tools=["Read", "Grep", "Glob"],
|
||
model="sonnet",
|
||
),
|
||
},
|
||
),
|
||
):
|
||
print(message)
|
||
```
|
||
|
||
The key detail is the description field. It acts as a routing signal.
|
||
|
||
Agent Teams: Coordination Through Communication
|
||
|
||
Agent teams are built for collaboration. Instead of isolated workers, you have agents that maintain context, communicate, and adapt in real time.
|
||
|
||
They include:
|
||
|
||
A lead agent that assigns and synthesizes
|
||
|
||
Teammates that execute tasks
|
||
|
||
A shared task layer that tracks progress and dependencies
|
||
|
||

|
||
|
||
This allows real coordination. A frontend agent can signal backend changes and things update instantly.
|
||
|
||
The Core Difference
|
||
|
||
Sub-agents and agent teams are fundamentally different.
|
||
|
||
Sub-agents are execution-focused:
|
||
|
||
Isolated
|
||
|
||
Stateless
|
||
|
||
One-shot
|
||
|
||
Parent-controlled
|
||
|
||
Agent teams are collaboration-focused:
|
||
|
||
Persistent
|
||
|
||
Interactive
|
||
|
||
Context-sharing
|
||
|
||
Peer-to-peer
|
||
|
||
Use sub-agents when tasks are independent. Use teams when tasks depend on each other.
|
||
|
||
Where Most People Go Wrong
|
||
|
||
Most systems are split by roles like planner, developer, tester. This creates context loss at every handoff.
|
||
|
||
The implementer doesn’t know what the planner knew
|
||
|
||
The tester doesn’t know what the implementer decided
|
||
|
||
Quality drops at every boundary.
|
||
|
||
The better approach is context-based decomposition.
|
||
|
||

|
||
|
||
Ask: What information does this task actually need?
|
||
|
||
If two tasks share deep context, keep them in the same agent. Split only when context can be cleanly separated.
|
||
|
||
The 5 Patterns That Actually Matter
|
||
|
||
1\. Prompt chaining — sequential steps
|
||
|
||

|
||
|
||
2\. Routing — send tasks to the right agent
|
||
|
||
3\. Parallelization — run independent work together
|
||
|
||
4\. Orchestrator–worker — one agent delegates
|
||
|
||
5\. Evaluator–optimizer — generate and refine
|
||
|
||
When Not to Use Multi-Agent Systems
|
||
|
||
Sometimes a single agent is enough
|
||
|
||
Use multi-agent systems when:
|
||
|
||
You need context isolation
|
||
|
||
You have parallel tasks
|
||
|
||
You need specialization
|
||
|
||
Avoid them when:
|
||
|
||
Agents depend heavily on each other
|
||
|
||
Coordination overhead is too high
|
||
|
||
The task is simple
|
||
|
||
Final Principle
|
||
|
||
Design around context boundaries, not roles. Start simple and add complexity only when needed. |