Subagents in the Claude Agent SDK - When and How to Use Them

I've been working with the Claude Agent SDK across several projects now, and one of the features that keeps proving its value is subagents. The concept is straightforward - instead of one agent doing everything, you spin up specialised sub-processes that handle specific parts of a task. But knowing when to use them, and which type to use, makes a real difference in how well your agents perform.

The Claude Agent SDK subagents documentation covers the technical reference. Here's what I've learned about using them effectively in production.

Why Subagents Exist

The core problem subagents solve is context management. When you're building agents that handle complex, multi-step tasks, a single agent trying to do everything runs into issues. Its context window fills up with intermediate results. It loses track of where it was in a multi-part task. It tries to do three things at once and does all of them poorly.

Subagents let you decompose work. A main agent coordinates the overall task, and subagents handle the individual pieces. Each subagent gets its own context window, its own focus, and its own set of tools appropriate to its job. When it's done, it returns a result to the parent agent, which decides what to do next.

If you've used Claude Code, you've already seen subagents in action. When Claude Code launches a Task to explore a codebase or run tests, that's a subagent. It runs independently, does its work, and reports back. The main conversation stays clean and focused while the subagent handles the deep work.

The Available Subagent Types

The SDK provides several specialised subagent types, each designed for a different kind of work. Picking the right type matters - it determines what tools the subagent has access to and how it approaches the task.

Bash agents are command execution specialists. They run shell commands, handle git operations, execute scripts, and deal with terminal tasks. When your agent needs to build a project, run a test suite, or interact with system tools, a Bash subagent is the right choice.

Explore agents are optimised for codebase exploration. They can search files by patterns, grep for keywords, and read files to answer questions about the code. They're fast and focused on research rather than modification. Use them when your agent needs to understand existing code before making changes.

Plan agents handle architectural planning. They can explore the codebase but can't edit files. They're designed to think through implementation strategy, identify critical files, and produce step-by-step plans. When you want your agent to plan before coding, a Plan subagent forces that discipline.

General-purpose agents have access to the full range of tools. They handle complex, multi-step tasks that don't fit neatly into one of the specialised categories. Use these when you need flexibility, but be aware that with great power comes a greater chance of the agent going off on tangents.

Code reviewer agents are built for reviewing code against plans and standards. They look at what was written, compare it to what was intended, and flag issues. If you're building a development workflow where quality checks happen automatically, these are the subagent type to use.

When Subagents Actually Help

Not every task needs subagents. Overusing them adds overhead - each subagent launch has a cost in terms of latency and tokens. Here's where they genuinely earn their keep.

Parallelising independent work. This is the most obvious win. If your agent needs to search three different codebases, check two APIs, and validate a configuration file, those tasks don't depend on each other. Launch them as parallel subagents, and the total time is roughly the time of the slowest task rather than the sum of all tasks. We've seen 3-4x speedups on research-heavy tasks with parallel subagents.

Protecting the main context. When a task requires reading dozens of files or analysing large outputs, doing all that in the main agent's context window uses up space quickly. A subagent handles the heavy lifting in its own context and returns just the findings. The main agent stays lean and focused.

Enforcing task boundaries. Subagents don't have access to each other's work unless you explicitly pass information between them. This isolation is actually a feature. It prevents an agent working on task A from getting confused by the intermediate state of task B.

Specialisation through tool restriction. An Explore subagent can't edit files. A Plan subagent can't run commands. These restrictions aren't just safety measures - they shape how the agent approaches the problem. A subagent that can only read code tends to be more thorough in its analysis than one that might jump straight to editing.

When Not to Use Them

Simple, sequential tasks. If the main agent can handle the task in a few steps without filling up its context, adding a subagent just adds latency.

Tasks with tight dependencies. If step B requires the full output of step A, and step C requires the full output of step B, parallelising doesn't help. You'll spend more time marshalling data between subagents than you'd save.

When you need conversational continuity. Subagents start fresh. They don't share conversation history with the main agent or with each other. If a task requires understanding the full history of a conversation, keep it in the main agent.

Practical Patterns We Use

Here are a few patterns that have worked well in our projects.

Research then act. Launch an Explore subagent to investigate the codebase or gather information. Wait for the result. Use that result to make decisions in the main agent, then act on them. This is the most common pattern we use - it keeps research separate from action and gives the main agent clean, summarised findings to work with.

Parallel investigation. When you're debugging an issue and need to check multiple potential causes, launch several Explore subagents in parallel. One checks the database configuration, another checks the API logs, another checks the deployment settings. The main agent collects the findings and synthesises them.

Plan then execute. Use a Plan subagent to design an implementation approach. The plan comes back to the main agent, which then executes it step by step. This forces a thinking-before-coding discipline that produces better results, especially on larger tasks. You can even have the main agent present the plan for human review before proceeding.

Build and verify. After a code change, launch a Bash subagent to run the test suite while the main agent moves on to the next task. When the test results come back, the main agent checks them and decides whether to continue or fix issues.

Configuration and Control

When you launch a subagent, you can control several things.

Maximum turns. This limits how many API round-trips the subagent can make before stopping. Useful for preventing runaway subagents that get stuck in loops. We typically set this to somewhere between 5 and 15 turns, depending on the expected complexity of the task.

Model selection. You can override the model for individual subagents. Use a faster, cheaper model for simple research tasks and a more capable model for complex analysis. This is a meaningful cost optimisation. Not every subtask needs your most powerful model.

Prompting. Give subagents clear, specific instructions. They don't have the conversation context that the main agent has, so you need to include all relevant details in the prompt. Vague prompts lead to vague results. Be explicit about what you want the subagent to find, do, or produce.

Building with Subagents

If you're building AI agents using the Claude Agent SDK, subagents are one of the features that separate a demo from a production system. They let you handle complexity without drowning in it.

The key insight is that subagents aren't just about performance. They're about structure. They force you to break problems into pieces, define clear interfaces between those pieces, and handle each piece with the right tool for the job.

At Team 400, we've been building agent systems for Australian organisations using the Claude Agent SDK, OpenAI's framework, and other platforms. The ability to decompose work across specialised subagents is one of the patterns that works well regardless of which SDK you're using. The Claude Agent SDK just happens to make it particularly clean.

If you're exploring how AI agents could work for your organisation, whether it's automating internal workflows, building customer-facing assistants, or creating development tools, our AI consulting team can help you figure out the right architecture. And if you want hands-on help building and deploying agent systems, our AI development practice has the experience to take it from prototype to production.

The best agents aren't the ones that try to do everything in a single loop. They're the ones that know when to delegate.