Skip to main content

The Agent Tool

Module: Agents & Subagents | Lesson: 2 of 4 | Time: ~10 minutes

What You Will Learn​

  • What the Agent tool is and how it works
  • How to delegate subtasks to a subagent
  • When to use the Agent tool vs doing things directly

Prerequisites​

What Is the Agent Tool?​

The Agent tool is a built-in capability of Claude Code that lets it spawn a subagent — a separate, focused Claude instance that handles a specific subtask. The main Claude (the one you are chatting with) acts as a manager, delegating work to subagents and combining their results.

Think of It Like Delegating Tasks

Imagine you are a project manager. Instead of doing everything yourself, you assign specific tasks to team members. Each team member works independently and reports back. The Agent tool lets Claude work the same way — it assigns subtasks to subagents who handle them and report their findings.

How Subagents Work​

When Claude decides a task would benefit from delegation, it uses the Agent tool to spawn a subagent. Here is the flow:

You ask Claude a complex question
  |
Claude decides to delegate a subtask
  |
Claude spawns a subagent with a specific task
  |
The subagent works independently:
  - Reads files
  - Searches code
  - Analyzes patterns
  |
The subagent returns a summary to Claude
  |
Claude uses the summary to continue helping you

Context Isolation​

Each subagent has its own isolated context. This means:

  • The subagent starts fresh — it does not see your full conversation history
  • The subagent only knows about the specific task it was given
  • The subagent cannot see what other subagents are doing
  • When the subagent finishes, only a summary of its work comes back to the main Claude

This isolation is a feature, not a limitation. It means:

  1. Subagents stay focused — they are not distracted by unrelated conversation
  2. Context is used efficiently — each subagent has its full context window for the subtask
  3. Work can happen in parallel — multiple subagents can work on different parts of a problem at the same time
note

You do not control when Claude spawns subagents. Claude decides on its own when delegation would be helpful. Typically this happens with complex tasks that have multiple independent parts.

When Claude Uses Subagents​

Claude tends to spawn subagents for tasks like:

TaskWhy a Subagent Helps
Exploring a large codebaseA subagent can dive deep into one area without cluttering the main conversation
Researching a questionA subagent can search through many files and return a focused summary
Working on multiple filesMultiple subagents can each handle a different file or component
Analyzing complex codeA subagent can read and understand a complex module in isolation

What Gets Returned​

When a subagent finishes, it does not send back everything it read or did. Instead, it returns a summary — a concise report of its findings or the work it completed. This keeps the main conversation clean and focused.

For example, if you ask Claude to "explain how the authentication system works in this project," Claude might spawn a subagent to explore the auth-related files. The subagent reads through several files, traces the flow, and returns a summary like:

"The authentication system uses JWT tokens stored in HTTP-only cookies. Login is handled in src/auth/login.ts, which validates credentials against a PostgreSQL database via src/db/users.ts. Tokens are verified by middleware in src/middleware/auth.ts on every protected route."

Claude then uses that summary to give you a clear answer.

Cost Implications​

Subagents use tokens just like the main conversation. Each subagent has its own context window and processes tokens independently. This means:

  • More subagents = more token usage — each subagent's work counts toward your usage
  • Complex tasks cost more — a task that spawns three subagents uses more tokens than a simple direct answer
  • Summaries help — because only summaries come back, the main conversation stays efficient
Be Aware of Costs

You do not need to worry about this for most tasks. But if you are working on a very large project and ask Claude to do something broad like "review the entire codebase," it may spawn many subagents and use significant tokens. Be specific about what you need to keep costs reasonable.

Try It Yourself​

Trigger subagent usage by giving Claude a multi-part task:

  1. Start Claude Code in a project that has at least several files (a real project works best)
  2. Ask a question that requires exploring multiple areas:
How is error handling done across this project? Check the API routes,
the database layer, and the utility functions. Give me a summary of
the patterns used in each area.
  1. Watch Claude's output. You may see it mention that it is using the Agent tool or spawning a subagent to investigate each area.
  2. Notice how the final answer is a consolidated summary, not a file-by-file dump.
tip

If you are working with a small project (just a few files), Claude may not use subagents because it can handle everything directly. Use a larger project or ask about multiple distinct areas to see subagents in action.

What You Learned​

  • The Agent tool lets Claude spawn subagents — separate instances that handle subtasks
  • Subagents have isolated context — they start fresh and only know about their assigned task
  • Subagents return summaries, not their full work, keeping the main conversation clean
  • Claude decides on its own when to use subagents — typically for complex, multi-part tasks
  • Subagents use tokens independently, so complex tasks with many subagents cost more
Help Us Improve

How was this lesson? Take 2 minutes to share your feedback — it helps us make the tutorials better for everyone.

Give Feedback →

Next Up​

Next: Subagent Types