Agents, Subagents and Agent Teams in Claude Code
The confusion slowing teams down
When developers start exploring Claude Code seriously, a question comes up fast — one that looks simple but isn't: what's the difference between an agent, a subagent, and an Agent Team? All three terms coexist in the documentation, in forums, and in technical conversations, but they're rarely explained together with concrete examples.
Understanding this distinction isn't an academic exercise. It's what separates basic Claude Code usage — where all work runs in a single linear session — from advanced usage where tasks are distributed, parallelized, and specialized to achieve results impossible with a single execution thread.
What Is an Agent in Claude Code?
In the context of Claude Code, an agent is any model instance that operates with autonomy: it receives a goal, can use tools (read files, run commands, search the web, call APIs), and makes iterative decisions until the task is complete or human input is needed.
When you open Claude Code and describe a task like "refactor this module to use the repository pattern", you're activating the main agent. It decides which tools to invoke, in what order, and when it's done. This autonomy is the core of the concept.
What sets Claude Code apart from a conventional chatbot is precisely this capacity for agency: the model doesn't just respond — it acts. It can modify files, run tests, fix errors in real time, and deliver a complete result without you having to guide every step.
The main agent's work cycle
The main Claude Code agent follows an internal loop:
- Observe current state (files, context, instructions)
- Reason about which action to take next
- Act by invoking a tool
- Evaluate the result and decide whether to continue or stop
This cycle can repeat dozens of times in a single task. And that's exactly where the need for subagents emerges.
Subagents: Delegate to Scale
A subagent is a secondary model instance launched by the main agent to solve a subtask independently. In practice, Claude Code creates them using the Agent tool available in its native toolset.
The core idea: instead of the main agent doing everything sequentially, it delegates parts of the work to subagents that can run in parallel or in isolated contexts.
// How the main agent launches a subagent (Claude Agent SDK)
{
"type": "tool_use",
"name": "Agent",
"input": {
"description": "Analyze the authentication module's performance",
"prompt": "Read src/auth/*.ts and generate a report identifying performance bottlenecks. Return only the report — do not modify anything.",
"subagent_type": "general-purpose"
}
}
The subagent has its own context, its own tools, and works in an encapsulated way. The main agent receives the result when it finishes and continues its own logic.
When to launch a subagent
Subagents are especially useful when:
- The search is open-ended: you need to explore multiple paths before knowing which is right. Instead of polluting the main context, the subagent explores and summarizes.
- Work is parallelizable: you have four independent modules to analyze. Launch four subagents in parallel and get all four results simultaneously.
- Context needs protecting: a long operation could fill the main agent's context window. The subagent works in its own space and delivers only the relevant result.
- Specialization matters: you can configure subagents with specific types (
Explore,Plan,claude-code-guide) that have different capabilities.
// Parallel subagents: the agent launches both at once
// Single message with multiple Agent tool_use blocks
[
{
"name": "Agent",
"input": {
"description": "Accessibility audit",
"prompt": "Review src/components/**/*.tsx for WCAG 2.1 AA accessibility issues",
"subagent_type": "Explore"
}
},
{
"name": "Agent",
"input": {
"description": "Performance audit",
"prompt": "Review src/components/**/*.tsx for unnecessary re-renders and optimization opportunities",
"subagent_type": "Explore"
}
}
]
The key to parallelism: both subagents run simultaneously. Total time equals the slower one — not the sum of both.
Agent Teams: Structured Coordination at Scale
An Agent Team goes one step further: it's not just launching several subagents ad hoc, but designing a system of agents with defined roles, a structured workflow, and stable division of responsibilities.
In an Agent Team, each agent has:
- A fixed role (orchestrator, researcher, writer, reviewer, validator...)
- A toolset suited to that role
- A communication protocol with the other agents on the team
While an agent with subagents is a dynamic, ad-hoc relationship (the agent decides at runtime whether to launch subagents), an Agent Team is a pre-designed architecture where work distribution is planned from the start.
Real example: content publication pipeline
In one of our AI integration projects, we use an Agent Team to automate the generation and publication of technical content:
| Agent | Role | Tools |
|---|---|---|
| Orchestrator | Coordinates the flow and makes routing decisions | State management, subagent launching |
| Researcher | Finds up-to-date information on the topic | WebSearch, WebFetch, Grep |
| Writer | Drafts content following the style guide | Read, Write, article history |
| Reviewer | Checks quality, SEO, and coherence | Read, Grep, structured checklist |
| Publisher | Formats content and executes commit/push | Bash, Git tools |
The orchestrator doesn't do the work directly: it directs. It receives the goal, assigns tasks to each specialized agent based on progress, and manages intermediate results.
// Schematic configuration of an Agent Team with the Claude Agent SDK
const contentTeam = {
orchestrator: {
role: "Coordinates the full content generation pipeline",
tools: ["Agent", "TodoWrite"],
instructions: "Never write content directly. Always delegate to the Writer."
},
researcher: {
role: "Researches the given topic and returns structured data",
tools: ["WebSearch", "WebFetch", "Grep"],
subagent_type: "general-purpose"
},
writer: {
role: "Drafts the article following blog guidelines",
tools: ["Read", "Write"],
subagent_type: "general-purpose"
},
reviewer: {
role: "Reviews quality, SEO, and article coherence",
tools: ["Read", "Grep"],
subagent_type: "Explore"
}
};
Comparison: Agent, Subagent, or Agent Team?
This table summarizes when to use each approach:
| Criterion | Single Agent | Subagents | Agent Team |
|---|---|---|---|
| Task complexity | Simple or medium | Medium, parallelizable | High, multi-phase |
| Parallelism | No | Yes (ad-hoc) | Yes (structured) |
| Specialization | No | Partial | Full |
| Upfront design | Not needed | Minimal | Essential |
| Typical use cases | Refactoring, debugging | Multi-target audits | Pipelines, continuous automation |
| Overhead | None | Low | Medium-high |
The practical rule is straightforward: always start with a single agent. If the task grows and you need occasional parallelism, add subagents. If the system will run repeatedly with a complex, well-defined flow, design an Agent Team from the beginning.
The most common mistake
The typical mistake is the opposite: designing a complex Agent Team for tasks that a single agent with two subagents would solve faster and with fewer failure points. Architectural complexity has a cost: more configuration, more failure points, harder to debug.
Agent Teams shine when a task is recurring, predictable in structure, and complex enough to justify the design investment. They're not the default solution — they're the tool for when the others fall short.
Conclusion
The three concepts form a coherent hierarchy within Claude Code:
- The agent is the base unit: autonomous, tool-equipped, capable of completing whole tasks on its own.
- Subagents are dynamic extensions of the main agent for parallelizing or isolating subtasks without upfront design.
- Agent Teams are planned architectures where multiple specialized agents collaborate in complex, recurring workflows.
Mastering this distinction is what enables you to scale AI in real projects: not as a one-off assistance tool, but as infrastructure that operates autonomously and in coordination.
If you're exploring how to implement agents or Agent Teams in your company and want a solid starting point, we can help you design the right architecture for your use case: