Module 6: Subagents: delegating work to specialized agents
Introduction to Agent Teams: multi-agent orchestration
Introduction to Agent Teams: multi-agent orchestration
Overview
⚠️ Agent Teams is currently in research preview/experimental. The APIs, commands, and behaviors described in this capsule may change significantly. This capsule focuses on concepts and mental models, not step-by-step implementation. Check Anthropic's official documentation for the feature's current state.
Until now you've worked with subagents — child agents that the main agent creates, delegates to, and destroys. Subagents are ephemeral: they're born for a task, they complete it, and they disappear. That's an efficient model for one-off tasks, but it has limits when a project requires sustained coordination between multiple agents.
Agent Teams introduces a different model: a persistent team of agents working together on a shared project. Instead of a parent that creates ephemeral children, you have a team lead coordinating autonomous teammates, each with their own context, responsibilities, and ability to make decisions. They share a task board where tasks are assigned, tracked, and completed with dependency resolution.
This capsule is conceptual. It won't ask you to implement Agent Teams (because it's in preview and the API may change), but it will ask you to understand the mental model, the differences from subagents, and when to scale from one to the other. When Agent Teams is stable, you'll have the conceptual base to adopt it immediately.
From subagents to Agent Teams: the evolution
The delegation spectrum
Claude Code offers a continuous spectrum of delegation, and each level adds capabilities:
LEVEL 1 LEVEL 2 LEVEL 3 LEVEL 4
No Skills Subagents Agent Teams
delegation (experimental)
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
│ One agent│ │ One agent│ │ Parent + │ │ Team lead│
│ does │ │ with │ │ ephemeral│ │ + persis-│
│ it all │ │ extra │ │ children │ │ tent │
│ │ │ instruc- │ │ │ │ team- │
│ │ │ tions │ │ │ │ mates │
└──────────┘ └──────────┘ └──────────┘ └──────────┘
│ │ │ │
▼ ▼ ▼ ▼
Simple Repetitive Parallel Complex
1 file 1 task N subtasks N workstreams
1 session N sessions 1 session N sessions
Each level suits a type of project:
| Level | Example | Complexity |
|---|---|---|
| No delegation | Fix a typo, change a color | Trivial |
| Skills | Create a component, write a test | Repetitive |
| Subagents | Refactor a module, migrate a dependency | Complex, one session |
| Agent Teams | Implement a complete feature end-to-end with backend, frontend, tests, docs | Complex, multi-session |
Why subagents aren't enough for everything
Subagents have three fundamental limits that Agent Teams addresses:
1. Ephemeral
Subagents are created and destroyed on every invocation. If an Explore subagent analyzed your codebase and found important patterns, that information is lost when it finishes. On the next invocation, a new subagent has to start from zero.
Agent Teams: teammates persist. A teammate that analyzed the architecture retains that knowledge for future tasks.
2. No autonomy
Subagents do exactly what the parent tells them. They don't take initiative or identify work that needs doing. If the parent doesn't ask "analyze the tests", nobody analyzes them.
Agent Teams: teammates can identify work, propose it to the task board, and execute it autonomously (with the team lead's approval).
3. No coordination with each other
Subagents don't know that other subagents exist. If you launch an Explore subagent and a General-purpose subagent in parallel, each operates in total isolation.
Agent Teams: teammates see the shared task board, know what the others are doing, and can coordinate (e.g. "wait for the backend teammate to finish the endpoint before running the integration test").
Key Agent Teams concepts
1. Team Lead
The team lead is the orchestrating agent. It's analogous to the main agent in the subagent model, but with extra capabilities:
┌────────────────────────────────────────────────────────────┐
│ TEAM LEAD │
│ │
│ Responsibilities: │
│ ├── Break the project down into tasks │
│ ├── Assign tasks to teammates │
│ ├── Resolve dependencies between tasks │
│ ├── Review teammate outputs │
│ ├── Integrate partial results │
│ └── Communicate progress and decisions │
│ │
│ Exclusive tools: │
│ ├── Create/modify the task board │
│ ├── Assign/reassign teammates │
│ └── Approve/reject teammate outputs │
│ │
└────────────────────────────────────────────────────────────┘
The team lead doesn't implement directly — it coordinates. If a teammate is blocked, the team lead unblocks or reassigns. If a teammate's output isn't acceptable, the team lead asks for corrections.
2. Teammates
Teammates are specialized agents that execute assigned tasks. Unlike subagents, teammates:
- Persist between tasks (they aren't destroyed when one completes)
- Have a defined specialization (e.g. "backend developer", "test engineer")
- Can propose extra work to the task board
- See the task board and know what the others are doing
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ TEAMMATE 1 │ │ TEAMMATE 2 │ │ TEAMMATE 3 │
│ Backend │ │ Frontend │ │ QA/Testing │
│ Developer │ │ Developer │ │ Engineer │
│ │ │ │ │ │
│ Skills: │ │ Skills: │ │ Skills: │
│ - API design│ │ - React │ │ - Test plans│
│ - DB queries│ │ - CSS │ │ - E2E tests │
│ - Auth │ │ - A11y │ │ - Coverage │
└─────────────┘ └─────────────┘ └─────────────┘
│ │ │
└─────────────────┼─────────────────┘
│
┌─────────────┐
│ TASK BOARD │
│ (shared) │
└─────────────┘
3. Task Board
The task board is the shared space where the project's tasks live. It's visible to the team lead and every teammate:
┌──────────────────────────────────────────────────────────┐
│ TASK BOARD │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ BACKLOG │ │ IN PROGRESS │ │ DONE │ │
│ ├─────────────┤ ├─────────────┤ ├─────────────┤ │
│ │ #4 Write │ │ #2 Implement│ │ #1 Design │ │
│ │ API docs │ │ endpoints│ │ schema ✓ │ │
│ │ [unassig]│ │ [BE dev] │ │ [BE dev] │ │
│ │ │ │ │ │ │ │
│ │ #5 E2E tests│ │ #3 Build UI │ │ │ │
│ │ [blocked │ │ [FE dev] │ │ │ │
│ │ by #2] │ │ │ │ │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │
│ Dependencies: #5 blocked by #2, #3 depends on #1 │
│ │
└──────────────────────────────────────────────────────────┘
The task board isn't just a list — it has:
- States: backlog, in progress, in review, done
- Assignments: which teammate is working on what
- Dependencies: which tasks block others
- Priorities: execution order
4. Dependency resolution
The team lead handles the dependencies between tasks. If task #5 (E2E tests) depends on task #2 (implement endpoints), the team lead:
- Assigns #2 to the backend teammate
- Marks #5 as blocked
- When #2 completes, unblocks #5
- Assigns #5 to the QA teammate
- The QA teammate can see #2's output to write the tests
This dependency flow is automatic — the team lead doesn't need manual micromanagement.
Subagents vs Agent Teams: when to use each
Comparison table
| Criterion | Subagents | Agent Teams |
|---|---|---|
| Duration | Ephemeral (one task) | Persistent (the whole project) |
| Coordination | The parent controls everything | Shared task board |
| Autonomy | Zero — they do what the parent says | Partial — they can propose work |
| Number of tasks | 1-5 subtasks | 10+ organized tasks |
| Sessions | Inside a single session | Multiple sessions |
| Complexity | An isolated module/feature | An end-to-end feature or a whole project |
| Overhead | Low | Higher (setup, coordination) |
| Status | Stable (GA) | Experimental (research preview) |
Decision tree
Does the task cross multiple domains (backend + frontend + tests)?
├── NO → Can it be done in a single session?
│ ├── YES → SUBAGENTS (one-off delegation)
│ └── NO → Does it need coordination between workstreams?
│ ├── NO → SUBAGENTS (multiple sequential sessions)
│ └── YES → AGENT TEAMS ⚠️ (experimental)
└── YES → Are the domains interdependent?
├── NO → SUBAGENTS (parallel, no coordination)
└── YES → AGENT TEAMS ⚠️ (task board + dependencies)
Concrete examples
Use subagents:
- "Refactor the authentication service" → one domain, one session
- "Analyze the tests and the coverage" → one-off analysis
- "Generate documentation for the payments module" → a bounded task
Use Agent Teams (when it's available):
- "Implement the reports module: API, UI, tests, docs" → multiple domains, cross-cutting dependencies
- "Migrate from Express to Fastify while keeping backward compatibility" → multiple coordinated workstreams
- "Build a real-time chat feature end-to-end" → WebSocket backend + React frontend + integration tests + docs
The practical rule
If you can describe the task in a single instruction and you'd expect a result in one session → subagents. If you need a "project with multiple tasks that coordinate" → Agent Teams.
How Agent Teams works (conceptual model)
⚠️ The implementation details may change. This section describes the conceptual model based on Anthropic's preview documentation.
The lifecycle of an Agent Team
1. SETUP
┌─────────────────────────────────────────┐
│ Team lead receives the user's objective │
│ → Breaks it into tasks │
│ → Defines the teammates it needs │
│ → Creates the task board + dependencies │
└─────────────────────────────────────────┘
│
▼
2. EXECUTION
┌─────────────────────────────────────────┐
│ Teammates work on assigned tasks │
│ → Each one in its own context │
│ → They report progress to the board │
│ → Team lead resolves blockers │
└─────────────────────────────────────────┘
│
▼
3. INTEGRATION
┌─────────────────────────────────────────┐
│ Team lead integrates the results │
│ → Reviews each teammate's output │
│ → Resolves conflicts │
│ → Verifies the result is coherent │
└─────────────────────────────────────────┘
│
▼
4. DELIVERY
┌─────────────────────────────────────────┐
│ Complete result delivered to the user │
│ → Summary of what was implemented │
│ → Status of each task │
│ → Decisions taken and trade-offs │
└─────────────────────────────────────────┘
A conceptual example: implementing a notifications module
Imagine you ask Claude Code for:
Implement a notifications system for the app:
- Backend: notification service with a queue (Redis)
- Frontend: real-time notifications component
- Tests: unit and integration
- Docs: API documentation and a usage guide
With Agent Teams, the flow would be:
TEAM LEAD analyzes and decomposes:
Task Board:
┌──────────────────────────────────────────────────────────┐
│ #1 [BE] Create NotificationService (Redis pub/sub) │
│ → Assigned: Backend teammate │
│ → Dependencies: none │
│ │
│ #2 [BE] Create REST endpoints for notifications │
│ → Assigned: Backend teammate │
│ → Dependencies: #1 │
│ │
│ #3 [FE] Create the NotificationPanel component │
│ → Assigned: Frontend teammate │
│ → Dependencies: #2 (needs to know the API) │
│ │
│ #4 [FE] Wire up WebSocket for real time │
│ → Assigned: Frontend teammate │
│ → Dependencies: #1, #3 │
│ │
│ #5 [QA] Unit tests for NotificationService │
│ → Assigned: QA teammate │
│ → Dependencies: #1 │
│ │
│ #6 [QA] Backend-frontend integration tests │
│ → Assigned: QA teammate │
│ → Dependencies: #2, #4 │
│ │
│ #7 [DOC] API documentation + usage guide │
│ → Assigned: Team lead (or any free teammate) │
│ → Dependencies: #2, #4 │
└──────────────────────────────────────────────────────────┘
Parallel execution:
- Backend starts with #1 (no dependencies)
- QA starts with #5 once #1 completes
- Frontend starts with #3 once #2 completes
- And so on.
What used to take multiple manual coordination sessions gets orchestrated automatically.
Comparisons and decisions
Agent Teams vs project management tools
Agent Teams doesn't replace Jira, Linear, or GitHub Projects. It's a coordination system between AI agents, not between humans:
| Aspect | Jira/Linear | Agent Teams |
|---|---|---|
| Who uses it | Humans | AI agents |
| Duration | Sprints (weeks) | Minutes to hours |
| Tasks | Defined by humans | Decomposed by the team lead |
| Assignment | Manual, by a PM | Automatic, by the team lead |
| Execution | Humans implement | Agents implement |
Agent Teams is micro-project-management for agents, inside one or a few Claude Code sessions.
Agent Teams vs CI/CD pipelines
CI/CD pipelines run predefined steps in sequence. Agent Teams runs tasks with reasoning:
| Aspect | CI/CD pipeline | Agent Teams |
|---|---|---|
| Flexibility | Fixed steps | Adaptive tasks |
| Reasoning | No | Yes (each teammate reasons) |
| Dependencies | Linear | A complex graph |
| Error handling | Fails and notifies | Retries or reassigns |
Is Agent Teams always better than subagents?
No. Agent Teams adds coordination overhead. For tasks that fit in one session with subagents, Agent Teams is overengineering:
Task: "Add pagination to the products endpoint"
→ Subagents (Explore + parent). Agent Teams is overkill.
Task: "Implement a chat module with WebSocket, UI, tests, and docs"
→ Agent Teams (multiple workstreams with dependencies).
The rule: if coordination between tasks is trivial, use subagents. If it's the main challenge, Agent Teams makes sense.
Common patterns (conceptual)
Pattern 1: End-to-end feature
The most natural case for Agent Teams: implementing a complete feature that spans backend, frontend, and tests.
Objective: "Implement product search with filters"
Teammates:
- Backend: API endpoints with filters and pagination
- Frontend: search UI with dynamic filters
- QA: unit and E2E tests
Dependencies:
- Frontend depends on Backend (it needs to know the API)
- QA depends on both (it tests the integration)
Pattern 2: Coordinated migration
Large migrations where the changes have to be coordinated so the system doesn't break:
Objective: "Migrate from REST to GraphQL while keeping backward compat"
Teammates:
- Schema designer: defines the GraphQL schema
- Backend migrator: implements the resolvers
- Frontend migrator: updates the calls
- Compat checker: verifies REST still works
Dependencies:
- Everything depends on the schema
- Frontend depends on Backend
- Compat checker runs after every change
Pattern 3: Code review + fix
A team where one teammate reviews and another fixes:
Objective: "Improve the quality of the payments module"
Teammates:
- Reviewer: analyzes and produces an issue report
- Fixer: fixes issues based on the report
- Tester: verifies the fixes don't introduce regressions
Flow:
Reviewer → report → Fixer → changes → Tester → validation
Current limitations
⚠️ These limitations reflect the current state (research preview) and may change.
Technical limitations
- It requires specific configuration: Agent Teams isn't on by default. It requires flags or special configuration.
- Model compatibility: It may not work with every available model. Opus 5 is the recommended model.
- Resource consumption: Multiple teammates = multiple context windows = higher API consumption.
- Unstable API: The commands and configuration may change between versions.
Practical limitations
- Coordination overhead: For small projects, coordination costs more time than it saves.
- Complex debugging: When something fails in a team of 4 agents, pinpointing the problem is harder.
- Inconsistent results: Because it's experimental, results can vary between runs.
- No persistence between sessions: Even though teammates persist within a run, closing Claude Code destroys them.
What to expect in the future
Based on the direction of Anthropic's research:
- Real persistence: Teammates that survive between sessions
- Deeper specialization: Teammates that learn the project over time
- CI/CD integration: Agent Teams triggered from pipelines
- Multi-repo: Teammates working across different repositories in coordination
- Human-in-the-loop: Checkpoints where the team lead asks for human approval before continuing
Pitfalls and edge cases
Pitfall 1: Using Agent Teams for everything
Agent Teams isn't always the answer. Most day-to-day tasks are handled well by the main agent or by subagents:
❌ Agent Teams to change a CSS color
❌ Agent Teams to add a field to a form
✅ Agent Teams to implement a complex multi-domain feature
Pitfall 2: Not defining dependencies clearly
If the dependencies between tasks aren't clear, teammates can work with stale information:
❌ "Implement the chat backend and frontend" (no order specified)
✅ "Implement the backend first (endpoints + WebSocket).
Once it's ready, the frontend consumes that API."
Pitfall 3: Assuming stability
Agent Teams is in preview. Don't build production workflows that depend on this feature. Use it to experiment and to learn the mental model.
Pitfall 4: Ignoring the cost
Every teammate consumes context window and API calls. A team of 4 teammates can burn 4x the tokens of a single agent. Weigh whether the benefit justifies the cost.
Edge case: Conflicts between teammates
If two teammates modify the same file, there can be conflicts. The team lead has to resolve them. In practice, a good task decomposition minimizes conflicts (each teammate works on different files).
Edge case: A blocked teammate
If a teammate is blocked by a dependency that's taking a while, the team lead can:
- Reassign the blocking task
- Unblock by providing partial information
- Reorganize the task board to maximize parallel work
Complete worked example
Conceptual scenario: building a reports module end-to-end
Imagine you want to build a reports module for an e-commerce site. With Agent Teams, the conceptual flow would be:
The instruction to the team lead
Build a reports module for the e-commerce site:
- Backend: endpoints that generate sales reports
(daily, weekly, monthly) with filters by category
and date range
- Frontend: a dashboard with charts (Chart.js or Recharts)
- Tests: unit tests for the aggregation logic,
integration tests for the endpoints
- Docs: API documentation in OpenAPI format
The task board generated by the team lead
TASKS (generated automatically):
#1 [BE] Create ReportService with the aggregation logic
Status: todo | Assigned: BE teammate | Deps: -
#2 [BE] Create ReportRepository with optimized queries
Status: todo | Assigned: BE teammate | Deps: -
#3 [BE] Create GET /reports/{type} endpoints
Status: todo | Assigned: BE teammate | Deps: #1, #2
#4 [FE] Create the ReportDashboard component
Status: todo | Assigned: FE teammate | Deps: #3
#5 [FE] Wire up Recharts for the charts
Status: todo | Assigned: FE teammate | Deps: #4
#6 [QA] Unit tests for ReportService
Status: todo | Assigned: QA teammate | Deps: #1
#7 [QA] Integration tests for the endpoints
Status: todo | Assigned: QA teammate | Deps: #3
#8 [DOC] OpenAPI spec for the reports endpoints
Status: todo | Assigned: team lead | Deps: #3
Execution (conceptual)
Phase 1 (parallel):
BE teammate: #1 ReportService + #2 ReportRepository
Phase 2 (parallel):
BE teammate: #3 Endpoints (depends on #1, #2)
QA teammate: #6 ReportService tests (depends on #1)
Phase 3 (parallel):
FE teammate: #4 ReportDashboard + #5 Recharts
QA teammate: #7 Integration tests (depends on #3)
Team lead: #8 OpenAPI spec (depends on #3)
Final result:
Complete module: backend + frontend + tests + docs
All coordinated automatically
This scenario illustrates the power of Agent Teams: what would manually require 4-6 sessions with explicit coordination instructions gets organized automatically.
Connection to the rest of the guide
Looking back
- Module 04 (Workflow): The Explore → Plan → Code cycle is still the foundation. Agent Teams scales it to multiple agents running the cycle in parallel.
- Module 05 (Skills/Hooks): Teammates can use skills defined in
.claude/skills/. Hooks keep firing on every action. - Capsule 02 (Built-in subagents): Built-in subagents are the base building blocks. Agent Teams orchestrates them at a larger scale.
- Capsule 03 (Custom subagents): Custom subagents can evolve into teammate definitions in Agent Teams.
Looking forward
- Module 07 (Integrations): Git workflows, headless SDK, and Remote Control integrate with Agent Teams (e.g. a teammate that commits while another implements).
- Module 08 (Capstone project): You can tackle the project with subagents (recommended, given that Agent Teams is experimental) or with Agent Teams (for the adventurous).
- Guide #9 (Advanced Claude Code Workflows): The advanced guide will cover Agent Teams in depth once it's GA (Generally Available).
Practice exercises
These exercises focus on the Agent Teams mental model, not on implementation (since the feature is experimental).
Exercise 1: Decompose into tasks
Take a feature from your project (real or hypothetical) and decompose it the way a team lead would. Define:
- 6-8 tasks with clear descriptions
- Dependencies between tasks (what blocks what)
- Assignment to teammates (backend, frontend, QA, docs)
- The optimal execution order (maximize parallelism)
Example solution
Feature: "Add a comment system to a blog"
Tasks:
- [BE] Create the Comment model with relations (User, Post) → Deps: -
- [BE] Create CRUD endpoints for comments → Deps: #1
- [BE] Implement automatic moderation (spam filter) → Deps: #1
- [FE] Create the CommentSection component → Deps: #2
- [FE] Create the new-comment form with validation → Deps: #2
- [QA] Unit tests for the model and the service → Deps: #1, #3
- [QA] E2E tests for the full flow → Deps: #4, #5
- [DOC] Document the comments API in OpenAPI → Deps: #2
Optimal order:
- Phase 1: #1 (no deps)
- Phase 2: #2, #3, #6 (parallel, depend on #1)
- Phase 3: #4, #5, #8 (parallel, depend on #2)
- Phase 4: #7 (depends on #4, #5)
Exercise 2: Subagents vs Agent Teams
For each scenario, decide whether you'd use subagents or Agent Teams, and justify it:
- Add dark mode to the app
- Implement an authentication system with OAuth
- Refactor a 500-line file
- Migrate the database from MongoDB to PostgreSQL
- Add internationalization (i18n) across the whole app
- Fix a production bug
Solution
- Subagents — a single domain (frontend), changes to CSS/theme. It doesn't need complex coordination.
- It depends — if it's backend only → subagents. If it includes the frontend login flow + backend + tests → Agent Teams could be justified by the cross-cutting dependencies.
- Subagents (or even just the parent) — one file, no coordination needed.
- Agent Teams — a migration that touches models, queries, migrations, tests, and potentially the frontend. Multiple workstreams with strong dependencies.
- Agent Teams — it affects every file with strings, and requires string extraction + translation + testing + configuration. Multiple domains.
- The parent directly — urgency, a single problem, iterative debugging. Neither subagents nor Agent Teams.
Exercise 3: Design an Agent Team
Pick the most complex scenario from the previous exercise (or one of your own) and design the complete Agent Team:
- Define 3 teammates with a name, a specialization, and tools
- Create the task board with 8+ tasks
- Define every dependency
- Identify the critical path (the longest chain of dependencies)
Evaluation criteria
A good Agent Team design has:
- Clearly differentiated teammates (no overlapping responsibilities)
- Minimal dependencies (maximize parallel work)
- An identified critical path (know which task to optimize first)
- No circular dependencies (#A depends on #B which depends on #A → error)
- Tasks at the right granularity (neither "implement everything" nor "change this line")
Exercise 4: Simulate Agent Teams with subagents
Since Agent Teams is in preview, simulate the model using subagents:
- Define the tasks the way a team lead would
- Run each "phase" as a separate prompt to Claude Code
- Use subagents (Explore, Plan) for the analysis tasks
- Run the implementation tasks sequentially, respecting the dependencies
Phase 1: "Explore the project and design the schema for
the new feature" (Explore + Plan subagents)
Phase 2: "Implement the backend based on the plan"
(Parent agent)
Phase 3: "Implement the frontend that consumes the API"
(Parent agent, with context from step 2)
Phase 4: "Generate tests for the complete feature"
(Parent agent or custom subagent)
What to learn from this exercise
This exercise teaches you:
- The difference between manual coordination (subagents) and automatic coordination (Agent Teams)
- How much coordination effort Agent Teams would save
- The points where information needs to flow between phases (and why the Agent Teams task board is valuable)
- That the Agent Teams mental model can be applied even without the feature
Summary
Agent Teams represents the next step in Claude Code's evolution: from an agent that delegates one-off (subagents) to a persistent team of agents that coordinate autonomously. Even though it's still in research preview, understanding the mental model prepares you to adopt it when it's stable.
What you learned in this capsule:
- Agent Teams introduces: a team lead, teammates, a task board, and dependency resolution
- The key difference from subagents: persistence, autonomy, and coordination
- Subagents are enough for most tasks; Agent Teams is for complex multi-domain projects
- The overhead of Agent Teams only pays off when coordination is the bottleneck
- The mental model (decomposition, dependencies, parallelism) applies even without the feature
- Agent Teams is in research preview — experiment, but don't build production workflows on top of it
Module complete. You've covered the full spectrum of delegation in Claude Code: built-in subagents, custom subagents, and Agent Teams. In Module 07 you'll learn integrations (Git workflows, headless SDK, Remote Control) that expand what your agents can do.
Additional resources
Official documentation
- Sub-agents — Subagent and Agent Teams architecture
- Claude Code Overview — Product capabilities and roadmap
- Best Practices — Recommended multi-agent workflows
Multi-agent systems
- Anthropic Research: Multi-agent coordination — Papers and blog posts on multi-agent orchestration
- Plugins Reference — Skills, agents, hooks: the full ecosystem
Complementary
- Interactive Mode — Task management and coordination
- CLI Reference — Flags and configuration for Agent Teams
- Settings — Permission configuration for agent teams