A Deep Dive into Claude's Sub-Agents for Advanced AI Workflows

Let's explore the concept of sub-agents in Claude. With this feature, Anthropic aims to address two of the most significant challenges in any agentic system: context management and tool selection. In this article, we will delve into what these sub-agents are, their operational mechanics, and the ideal scenarios for their use. Later, we'll walk through a practical example of integrating them into your own workflows.

Understanding Sub-Agents in Claude

Consider sub-agents as specialized instances of Claude that your main orchestrator can utilize on demand. To grasp this concept better, let's examine the workflow. You have a main orchestrator, which is the primary Claude instance you interact with. Each sub-agent you define operates within its own distinct context window, separate from that of the main orchestrator. Furthermore, every sub-agent is guided by a custom system prompt that dictates its behavior. To carry out specific operations, each sub-agent is equipped with a unique set of tools. For instance, a code reviewer sub-agent would have a different toolkit than a front-end designer sub-agent. These specialized agents perform their designated tasks, and upon completion, they return only the final results to the main orchestrator. This mechanism ensures the main context window remains uncluttered with intermediate information.

The Core Benefits of Sub-Agents

The primary goal is effective context window management, and various approaches exist. While some advocate against building multi-agent systems, Anthropic is actively developing them. So, what are the precise advantages of employing sub-agents in such a system?

• Context Preservation: As mentioned, the separation of context windows is crucial.
• Flexible Permissions: It allows for granular control over what each agent can do.
• Improved Tool Selection: A state-of-the-art model can struggle when presented with a vast number of tools. By creating sub-agents with specific, limited toolsets, the probability of accurate tool selection increases significantly. This also promotes a separation of expertise.
• Reusability: A key benefit is the ability to reuse these agents. You can define them at a project level or a global system level, making them available across multiple projects.

Defining and Structuring Sub-Agents

To define a sub-agent, you must create a markdown file. Fortunately, Claude can assist in this process, as we'll demonstrate later. Each markdown file must contain the sub-agent's name, its purpose, its designated set of tools, and a system prompt.

Here are a few examples of how you might structure these sub-agents:

• Data Science Agent: This agent would have a description outlining its function, the specific data analysis tools it can use, and the types of operations it performs.
• Debugger Agent: This agent would be equipped with a specialized set of debugging tools and a precise set of instructions for identifying and fixing code issues.
• Code Reviewer Agent: This agent would be configured to analyze code for quality, consistency, and adherence to standards.

Creating and Using Sub-Agents

To create a sub-agent, you use the /agents command. You can define agents at either the project or user level. Claude can help generate the description and tool access configuration, though manual creation is also an option.

There are two primary ways to use them: 1. Explicit Invocation: You can directly call a specific sub-agent during your conversation with Claude. 2. Automatic Detection: Claude can automatically select the appropriate agent based on its description and the task you've provided.

Once the sub-agent completes its operation, it returns only the final results to the main orchestrator.

Building Complex Workflows

With sub-agents, you can construct highly sophisticated orchestration systems. They can be chained sequentially or executed in parallel, enabling the creation of numerous complex workflows. We will explore some of these advanced patterns in future articles.

A Practical Example: The Code Quality Auditor

Let's see how this works within Claude. In a running instance of Claude (which may require an update), typing /agents reveals the new command. This interface allows you to create a new agent or view existing ones. A built-in general-purpose agent, which acts as the main orchestrator, is always present.

Before creating a new agent, let's examine a pre-existing example. Depending on whether you created the agent at the project or user level, you will find a .claude folder containing an agents subfolder. Inside, each agent is defined by a markdown file.

Here is an example of a code-quality-auditor.md:

Description: Use this agent when you need a thorough, uncompromising review of code changes, particularly focusing on backward compatibility issues, unnecessary modifications, and functional consistencies. Claude automatically adds a few usage examples.

System Prompt: ``` You are a senior software engineering expert with decades of experience in enterprise systems, API designs, and maintaining large-scale codebases. You have zero tolerance for sloppy code, unnecessary changes, and backward-compatibility breaks. Your reviews are known for being brutally honest, technically precise, and uncompromising in maintaining code quality.

Your job is not to be liked but to prevent bad code from entering the codebase. Every unnecessary change is technical debt. Every breaking change is a future bug. Every duplicate feature is wasted effort. Be the guardian of the code quality that every team needs but few appreciate. ``` This prompt is designed to replicate the rigorous review process of a highly experienced senior engineer.

Creating a New Agent: The Unit Test Writer

Now, let's walk through creating a new agent. 1. Select Create new agent. 2. Choose the scope: Project level. 3. Opt to Generate with Claude. 4. Provide a description for the agent's purpose. This can be modified later in the markdown file. For this example, the description is: This agent is going to write unit tests for every change that the main agent makes. 5. After submitting the description, you are presented with a list of tools to assign to the agent. For a unit test writer, we can deselect unnecessary tools and keep the rest. 6. Assign a color to the sub-agent for easy identification in the interface (e.g., green).

Claude then generates the sub-agent's name, the list of available tools, a concise description for selection by the orchestrator, and the system prompt.

Here is the resulting prompt for our new unit-test-sub-agent: You are an expert test engineer specializing in writing comprehensive unit tests. This is accompanied by a more detailed description and several usage examples generated by Claude.

Invoking the Sub-Agent

Now, working within the Claude instance, we can issue a command like: write unit tests to test the current functionality.

Claude's orchestrator correctly identifies and invokes the unit-test-writer agent, indicated by the color change in the UI. The sub-agent then executes the task. In one such execution, it ran for over 8 minutes and generated more than 55,000+ tokens.

Since this entire process occurs within the sub-agent's context window, only the final result—the completed unit tests—is passed back to the main orchestrator. This keeps the primary context window clean. The system prompt could even be modified to have the sub-agent execute the tests and return only the pass/fail results. The power of this approach lies in creating numerous specialized sub-agents for various tasks.

A Note on Token Consumption

It's important to use this feature judiciously, as creating many sub-agents can lead to significant token consumption. For heavy users, a premium plan from Anthropic might be a worthwhile consideration.

I highly recommend exploring sub-agents within Claude to see what powerful, customized workflows you can build. I hope you found this article useful.