--- 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" --- ![图像](https://pbs.twimg.com/media/HGrcfZPbQAATY9A?format=jpg&name=large) 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. ![图像](https://pbs.twimg.com/media/HGreTwvaMAA2pxv?format=jpg&name=large) 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 ![图像](https://pbs.twimg.com/media/HGret2raIAA_l3D?format=jpg&name=large) 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 ![图像](https://pbs.twimg.com/media/HGrez0UaEAAX9P2?format=jpg&name=large) 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. ![图像](https://pbs.twimg.com/media/HGre4EaawAECVXq?format=jpg&name=large) 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 ![图像](https://pbs.twimg.com/media/HGre8HpbkAAkYSx?format=jpg&name=large) 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.