Skip to content

Multi-Agent Workflows

Understand how Claude Code uses subagents for complex tasks.

What You'll Learn

  • How subagents work
  • When subagents are used
  • Parallelization strategies
  • Observing agent behavior

What Are Subagents?

When Claude Code faces complex tasks, it can spawn specialized subagents. Each subagent focuses on a specific part of the problem, working independently and reporting back.

┌─────────────────────┐
│    Main Claude      │
│     (Orchestrator)  │
└──────────┬──────────┘
           │
     ┌─────┴─────┐
     ▼           ▼
┌─────────┐ ┌─────────┐
│ Agent 1 │ │ Agent 2 │
│ (Explore)│ │ (Plan)  │
└─────────┘ └─────────┘

Subagent Types

Claude Code has specialized agents for different purposes:

Type Purpose
Explore Quickly search and understand codebases
Plan Design implementation strategies
general-purpose Handle complex, multi-step tasks

Explore Agent

Used for codebase exploration: - Finding files by patterns - Searching for code - Understanding architecture

> How do API endpoints work in this project?

Claude might spawn an Explore agent to find and analyze relevant files.

Plan Agent

Used for designing approaches: - Creating implementation plans - Identifying critical files - Considering trade-offs

> I need to add user authentication. What's the best approach?

General Purpose Agent

Used for complex multi-step tasks: - Tasks requiring multiple operations - Research across many files - Complex refactoring

When Subagents Are Used

Claude automatically uses subagents when:

  1. Open-ended exploration - "Find all places where..."
  2. Complex planning - "Design an architecture for..."
  3. Parallel tasks - Multiple independent searches
  4. Deep research - Understanding large codebases

Example: Codebase Understanding

> Explain how error handling works throughout this app

Claude might: 1. Spawn Explore agent to find error handling patterns 2. Analyze multiple files in parallel 3. Synthesize findings into a coherent answer

Observing Agents

When Claude uses subagents, you'll see activity indicators:

> How does authentication work?

[Exploring codebase...]
 ├── Searching for auth patterns
 ├── Reading configuration files
 └── Analyzing middleware

Found authentication implementation in 5 files...

Parallel Execution

Claude can run multiple agents simultaneously for independent tasks:

> Find all deprecated functions AND list all TODOs

Two parallel agents: 1. Search for @deprecated patterns 2. Search for TODO comments

Results combine when both complete.

Agent Autonomy

Subagents work independently: - They receive a task description - They explore and gather information - They report findings back - They don't interact with you directly

The main Claude instance: - Orchestrates the agents - Combines their results - Presents unified answers

Controlling Agent Behavior

Throughness Level

When requesting exploration, you can indicate depth:

> Do a quick search for login-related files

> Thoroughly analyze all authentication code

Claude adjusts agent behavior accordingly.

Focused vs Broad

# Focused - single agent, specific task
> Find the file that handles password reset

# Broad - might use multiple agents
> Audit the entire auth system for security issues

Agent Communication

Agents receive context but work independently:

Main Claude: "Find all Express routes in this project"

Explore Agent receives:
- Working directory
- Task description
- File access

Explore Agent returns:
- List of route files
- Route patterns found
- Summary of findings

The main instance uses this to answer your question.

Multi-Agent Patterns

Pattern 1: Research Then Implement

> First understand how notifications work, then add email notifications

1. [Explore Agent] - Find notification code
2. [Main Claude] - Analyzes findings
3. [Main Claude] - Implements new feature

Pattern 2: Parallel Analysis

> Compare the auth implementation across web and mobile apps

1. [Agent 1] - Analyze web auth
2. [Agent 2] - Analyze mobile auth
3. [Main Claude] - Compare and contrast

Pattern 3: Planning Then Execution

> Design and implement a caching layer

1. [Plan Agent] - Design caching strategy
2. [Main Claude] - Review plan with you
3. [Main Claude] - Implement approved design

Agent Efficiency

Subagents are optimized for their tasks:

  • Explore agents use fast, targeted searches
  • Plan agents consider multiple approaches
  • General agents handle complex sequences

This division makes Claude more effective than trying to do everything in one context.

Limitations

Context Isolation

Subagents don't see the full conversation history:

> I prefer tabs over spaces

[later in conversation]

> Create a new file

# The subagent might not know your preference
# unless explicitly included in the task

One-Way Communication

You can't interact with subagents directly:

> [Agent exploring...]

# You can't give additional instructions mid-exploration
# Wait for it to complete, then refine

Best Practices

Be Specific About Scope

# Vague - might over-explore
> Look at the code

# Specific - focused agent work
> Find all SQL queries in the user module

Let Claude Decide

Don't try to manually orchestrate agents:

# Don't do this
> First use an explore agent, then use a plan agent...

# Do this
> I want to add caching. Help me understand the current state
  and design an approach.

Review Agent Findings

When Claude reports subagent findings, verify they're relevant:

> [Agent found 15 files related to auth]

You: Are all of these actually auth-related, or are some false positives?

Try It Yourself

Exercise: Watch Agent Behavior

  1. Open a moderately complex project
  2. Ask broad exploration questions: 
    > What are the main features of this application?

> How is data stored and retrieved?
  3. Notice when Claude uses agents vs handles directly
  4. Ask follow-up questions about the findings

Exercise: Parallel Exploration

  1. Ask a question that naturally parallelizes: 
    > Find all API routes AND all database models
  2. Observe the parallel execution
  3. Note how results are combined

What's Next?

You've completed advanced tutorials! Move on to Expert: SDK Integration to build on top of Claude.

Summary: - Claude uses subagents for complex tasks - Agent types: Explore (search), Plan (design), General (multi-step) - Agents work independently and report findings - Parallel execution for independent tasks - Let Claude orchestrate agents - focus on your goals, not the mechanism

Learning Resources

All About AI: MCP Server Workflows (Popular AI channel)

Multi-agent workflows - orchestrating subagents for complex tasks and parallel execution.

Additional Resources

Type Resource Description
🎬 Video Claude Code Agent Tips Edmund Yong - Agent patterns
📚 Official Docs Agent Documentation Subagent orchestration guide
📖 Tutorial Best Practices Agentic workflow patterns
🎓 Free Course Anthropic Academy Free agent courses
💼 Commercial AI Coding Course Multi-agent techniques