DEV Community

Cover image for Subagents: The Building Block of Agentic AI
AK DevCraft
AK DevCraft Subscriber

Posted on

Subagents: The Building Block of Agentic AI

#ai #claude #machinelearning #llm

Problem to Solve

Most developers' first encounter with AI is a single prompt, a single response. It feels powerful — until the task gets complex. Ask an AI to research three competitors, synthesize the findings, and format them as a report, and a single context window starts to feel very small. This is the problem subagents solve.

Demo

demo

In the demo above, I'm invoking the agent explicitly by name. In orchestrated workflows, Claude can invoke multiple agents like this automatically — in parallel or sequentially — based on the task structure.

Skills GitHub Repo - .claude/agents/code-quality-reviewer.md

What Is a Subagent?

A subagent is an AI instance invoked by an orchestrating AI to handle a specific subtask within a larger workflow. In multi-agent systems broadly — whether built on Claude, GPT, Gemini, or open-source models — the core pattern is the same: rather than a single model doing everything sequentially, an orchestrator breaks work into pieces and delegates them. Much like a technical lead assigning work to specialists rather than writing every function themselves.

According to Anthropic's Claude Agent SDK documentation, subagents serve two core purposes: parallelization (running multiple tasks simultaneously) and context isolation (each subagent uses its own context window, returning only relevant results to the orchestrator rather than its full context).[^1]

Within their assigned scope, subagents are active execution units — they can browse the web, execute code, read and write files, and call external APIs. They don't just reason; they act.

How a Subagent Workflow Works

Subagent Workflow

The orchestrator doesn't do the heavy lifting — it coordinates. Each subagent receives a focused prompt with a clear objective, output format, and tool access, then returns a concise result. The orchestrator aggregates those results into the final deliverable.

Anthropic's internal research system uses exactly this pattern: a lead agent spawns subagents to explore different aspects of a query in parallel, then compiles their findings into a coherent answer. Their evaluations found this approach outperformed a single Claude Opus 4 by 90.2% on internal research benchmarks.[^2]

Orchestration Patterns

Not all subagent workflows are structured the same way. Three patterns cover most real-world cases:

parallel pipeline

Sequential-pipeline

Hierarchical-delegation

  • Parallel fan-out — Independent subtasks launch simultaneously. Best for tasks like analyzing multiple documents at once.
  • Sequential pipeline — Each subagent's output feeds the next. Best when there's a dependency chain (research → draft → edit → format).
  • Hierarchical delegation — A subagent itself becomes an orchestrator for deeper subtasks. Powerful, but adds coordination complexity.

Choosing the wrong pattern is a common mistake. Parallelizing a sequential task adds overhead without benefit; sequentializing an independent task wastes time.

Creating Subagents with Claude Code CLI

Claude Code gives you two ways to create subagents: interactively via the /agents command, or manually as markdown files. Both result in the same thing — a .md file in a .claude/agents/ directory.

The Interactive Way 

/agents create
Enter fullscreen mode Exit fullscreen mode

This walks you through a guided setup: name, description, tools, model, and scope. At the end, it saves the file, and the agent is available immediately.

The Manual Way

Create a markdown file directly — the frontmatter defines behavior, the body is the system prompt:

---
name: security-reviewer
description: "Expert security reviewer. Use PROACTIVELY after any changes to auth, data handling, or API endpoints."
tools: Read, Grep, Glob
model: haiku
permissionMode: plan
---

You are a senior security engineer reviewing code for vulnerabilities.
When invoked:
1. Identify recently changed files
2. Analyze for OWASP Top 10 vulnerabilities
3. Check for secrets, SQL injection, and hardcoded credentials
4. Report findings with severity levels and remediation steps
Enter fullscreen mode Exit fullscreen mode

Where the File Lives

Subagent scope is determined by which directory the file is placed in:

Scope Path When to use
Project .claude/agents/ in project root Team-shared agents, commit to version control
User ~/.claude/agents/ in home dir Personal agents available across all projects

Project scope is the recommended default — it makes subagent definitions shareable via version control. Use user scope for general-purpose agents you want available everywhere, regardless of which repo you're in.

Best Practices

  • Write descriptions that trigger correctly. Claude uses the description field to decide when to invoke a subagent automatically. Be specific and include PROACTIVELY if you want it auto-triggered — for example: "Use PROACTIVELY after any changes to authentication or data handling."

  • Restrict tools intentionally. The tools field restricts what the agent can do — a security auditor only needs Read, Grep, and Glob, and has no business writing files. That restriction is worth being explicit about.

  • Match model to task complexity. Route subagent exploration to cheaper, faster models like Haiku and reserve Opus for genuine architectural reasoning. A read-only code scanner doesn't need the same model as an agent writing production code.

  • Keep system prompts focused. A subagent with a narrow, well-defined role outperforms a generalist one. If the prompt starts covering many different concerns, split it into two agents.

The Practical Challenge: Context Management

Each subagent starts fresh with no shared memory. This means:

  • The orchestrator must craft every subagent prompt with all the context it needs to succeed
  • Subagent outputs must be concise enough to fit back into the orchestrator's context alongside everything else
  • If outputs are large, the orchestrator must summarize before aggregating

Good subagent design is largely information architecture: what does each agent need to know, what must it produce, and how does that output flow back into the whole.

Safety Considerations

When subagents can take real-world actions, safety boundaries matter more than in single-agent systems:

  • Least privilege — Give each subagent only the tools it actually needs. A research agent doesn't need write access to a production database.
  • Output validation — Don't blindly pass subagent outputs downstream. Even lightweight sanity-checking reduces blast radius.
  • Prompt injection — Subagents that browse the web or read external files can encounter content designed to manipulate their behavior. This is a real attack surface in agentic systems.

When to Use Subagents

Use subagents when… Avoid subagents when…
Task has clearly separable subtasks Task is straightforward for one agent
Parallel execution saves meaningful time Subtasks share too much state to delegate
Total work exceeds one context window Coordination overhead exceeds the benefit
Different subtasks need different tools You're still prototyping — stay simple first

Start with a single-agent approach and introduce orchestration when it genuinely starts to strain. Complexity has a cost.

Subagents vs. Skills: A Quick Note

These two terms sometimes get conflated, but they operate at completely different layers. A skill is a passive instruction document — a markdown file Claude reads before a task to understand best practices, available libraries, and output conventions. A subagent is an active execution unit that runs, uses tools, and returns results.

The honest relationship: a subagent might read a skill before doing its work. One shapes knowledge; the other executes.

skills-subagent

Final Thoughts

The broader Claude stack can be conceptualized as five layers: MCP for connectivity, Skills for task-specific knowledge, Agent as the primary worker, Subagents as parallel independent workers, and Agent Teams for coordination.[^3] These building blocks are shipping in rapid succession, and the pattern is maturing fast.

For developers just entering this space: don't need to build full orchestration systems on day one. But understanding the pattern — how delegation works, what subagents can and can't do, where the sharp edges are — will shape how you think about AI architecture from the start.

Subagents aren't a feature. There's a shift in how we think about what AI can be tasked with doing.

References

If you have reached this point, I have made a satisfactory effort to keep you reading. Please be kind enough to leave any comments or share any corrections.

My Other Blogs:

Top comments (0)