Subagents and multi-agent systems: splitting work among several AIs

Based on: the Claude Code official documentation, Anthropic engineering posts (2024 and 2025), and the OpenAI Agents SDK documentation. Checked in September 2026.

A subagent is an "assistant AI" that the main AI hands side tasks to (small jobs that belong to a bigger job). The assistant digs through material and does the work at its own desk (its own working memory), then returns just a one-page summary report to the main AI. A setup with several of these assistants sharing the work is called a multi-agent system. This guide explains, in order, what a subagent is, why you use one, how teams are organized, when it actually costs you more, and how to make one yourself in Claude Code.

If the word "agent" is new to you, read How AI and AI agents differ first. If Claude Code is new to you, read Getting started with Claude Code first. It will make this guide easier to follow.

Quick comparison: an AI working alone vs an AI with assistants

Comparison: a team lead and assistants

Take a team lead at a company as an example. If the team lead does market research, competitor analysis, and legal review alone, the desk gets buried in papers, and when it is time to make the important decision, it is easy to lose track of what mattered.

So the team lead hands it to an assistant like this: "Research the pricing policies of three competitors and sum them up on one page." The assistant reads dozens of sources at their own desk, but the team lead only receives one tidy page. The team lead's desk stays clean, and the team lead gathers the reports from several assistants to reach a conclusion.

A subagent is exactly this assistant. Here, the "desk" is the AI's context window: the amount of conversation and material the AI can keep in mind and look at at once. What a context window is gets covered in detail in What tokens and context windows mean.

Subagents in Claude Code

In Claude Code, a subagent is a specialist AI helper that takes on a certain kind of task. Each subagent has its own context window, its own instructions (system prompt), and its own list of tools it can use.

Here is the typical use. When you work on a side task, search results, logs, and file contents pile up in the main conversation. When content you will never look at again seems about to fill the main conversation, you hand that task to a subagent. The subagent works in its own space and returns only a summary.

The same goes for the Claude Agent SDK (a set of tools developers use to put an agent like Claude Code into their own programs). A subagent is a separate agent that the main agent starts. The tools it used and the results along the way stay inside the subagent, and only the last message goes back to the main agent.

Why split the work: five benefits

For example, in a code review, if you run three subagents at once, one for style checks, one for security checks, and one for test coverage checks, it finishes faster than doing the three one after another. And if you give a subagent that only reviews documents just the "read" and "search" tools, it can never edit a file by mistake. A tool that is not on the tool list is as good as nonexistent for that subagent.

Multi-agent systems: three ways to organize a team

There are a few set shapes for making several AIs work together. Of the patterns Anthropic describes, these are the three closest to subagents.

1. Orchestrator-workers (conductor and players)

The main AI breaks up the work, hands it to worker AIs, and combines the results that come back. It suits complex tasks where you cannot know in advance how many pieces to split them into. The team lead comparison above is this pattern.

2. Parallelization (several at once)

You split the work into independent pieces and do them at the same time, or you run the same task several times and compare the results. Use it when you want more speed, or when you want to make the result more reliable by looking from several angles.

3. Evaluator-optimizer (a maker and a checker)

One AI makes the output, and another AI evaluates it and gives feedback, over and over. It works especially well for tasks with clear evaluation criteria, where the result improves with each round of fixes. Writing and revising is a good example.

You can also split patterns by who holds control of the conversation (the OpenAI Agents SDK's distinction).

Subagents in Claude Code are the kind where the main agent receives and organizes the results, so they are close to the manager pattern.

When it costs you more

Having many assistants is not always better. The results Anthropic published when it built its own research feature as a multi-agent system show both the benefits and the costs.

• Benefit: A setup where the main (lead) agent makes a plan and subagents research different directions at the same time scored 90.2% better than a single agent on Anthropic's internal research evaluation (as of the June 2025 post, comparing a lead Claude Opus 4 + Claude Sonnet 4 subagents against Claude Opus 4 alone). It was especially strong on questions that need a broad search in many directions at once.
• Cost: Agents used about 4 times as many tokens (the units in which AI processes text) as a normal chat, and multi-agent systems used about 15 times as many. Each assistant calls the AI separately, so usage grows a lot.
• Tasks it does not suit: It does not suit tasks where all the agents must keep sharing the same context, or where they have a lot to pass back and forth. Tasks with few parts to split up and run at once, like many coding tasks, also fall here.

The numbers above are results Anthropic measured on its own system with its own evaluation. They do not apply as-is to every task. It is enough to understand it as: "it works very well for broad searches in many directions, but it costs a lot."

Start with the simplest approach, and add complexity only when you need it. If you split a task that one agent could handle well, you only add cost, and information can get lost in the handover.

Making a subagent in Claude Code

Claude Code comes with some subagents built in. There is Explore, which only reads code and searches quickly; Plan, which does research in plan mode; and general-purpose, which handles tasks with many steps, among others. Even if you make none yourself, Claude calls these when it needs them.

You make your own subagent like this.

1. Ask Claude: Say "Make a subagent that only does code review," and Claude writes the settings file for you.
2. Write the file yourself: Make a Markdown file in .claude/agents/ in the project folder (for this project only) or in ~/.claude/agents/ in your user folder (for all your projects). If you keep it in your user folder, you can reuse an assistant you made once in every project.

In the past, the /agents command opened a creation wizard. According to the official documentation, from v2.1.198 it no longer opens the wizard and only shows a message telling you to "ask Claude or edit .claude/agents/ directly." Command behavior like this can change with the Claude Code version.

The file has the settings at the top and the instructions below them. For example, it looks like this.

---
name: code-improver
description: Scans files and suggests improvements for readability, performance, and best practices. Use after writing or modifying code.
tools: Read, Grep, Glob
model: sonnet
---

You are a code improvement specialist. For each issue you find, explain
the problem, show the current code, and provide an improved version.

Put the most care into description. The last sentence in the example above, "Use after writing or modifying code.", is the part that tells Claude when to hand work over. Claude reads each subagent's description to decide when to use it, so if the description is vague, the assistant may never be called, or may be called at the wrong time. If you want to be sure it is used, call it by name in the conversation.

How to hand work to an assistant well

An assistant receives less information than you might think. The main conversation's history is not passed to the subagent, and the instructions you write when handing over the task are in practice the only channel. So you must write the needed file locations, error messages, and decisions already made directly into the instructions.

When you hand over a task, state these four things clearly.

• Goal: what it needs to find out or make
• Result format: the shape, such as a table, a three-line summary, or a list of file paths
• Tools and material: where to look and which tools to use
• Work boundary: the scope this assistant covers (so it does not overlap with other assistants)

Just as a human assistant brings back something off target if you only say "look into that for me," the same goes for an AI assistant. For tips on writing instructions, the principles in How to write good prompts apply as they are.

Example: splitting a writing AI from a grading AI

This example uses the evaluator-optimizer pattern from above for writing.

1. An agent in the writer role writes a draft based on official sources.
2. An agent in the supervisor role evaluates the draft with a separately prepared scoring sheet. The writer does not grade its own work.
3. If the draft does not pass the set threshold score, it is revised according to the supervisor's comments and submitted again.
4. Only drafts that pass the threshold are read by a person, and a person makes the final decision on whether to publish.

When makers check their own work, they easily miss things. When the evaluation criteria are clear, feedback from another set of eyes makes fixes easier. But an AI supervisor can be wrong too, so leave the final judgment to a person.

Common misunderstandings

"The more assistants you have, the smarter it gets." More assistants also means more cost, and for tasks that need a lot of information passed back and forth, it can actually cost you more. First think about whether the task can be split.

"A subagent knows everything in the main conversation." A typical subagent starts fresh and does not receive the main conversation's history. You need to write the information it needs when you hand over the task.

"Subagents are a feature you have to install separately." Claude Code comes with built-in subagents, and Claude uses them when needed even if you make none yourself. You only add files when you want to make your own assistant.

Summary

Read next

• How AI and AI agents differ: AI that answers, AI that works
• Getting started with Claude Code: from installation to your first conversation with an AI coding assistant in the terminal
• What tokens and context windows mean: why AI loses track of earlier content in long conversations
• How to write good prompts: five principles from the official guides

References

• Claude Code Docs, "Subagents": https://code.claude.com/docs/en/sub-agents
• Claude Code Docs, "Subagents in the SDK": https://code.claude.com/docs/en/agent-sdk/subagents
• Anthropic Engineering, "How we built our multi-agent research system" (2025-06-13): https://www.anthropic.com/engineering/multi-agent-research-system
• Anthropic Engineering, "Building effective agents" (2024-12-19): https://www.anthropic.com/engineering/building-effective-agents
• OpenAI Agents SDK, "Agent orchestration": https://openai.github.io/openai-agents-python/multi_agent/