How Subagents Work?

Most subagent workflows follow an orchestrator-worker pattern. The orchestrator does not simply distribute prompts. It decides whether delegation is worthwhile, gives each worker an explicit contract, tracks completion, and consolidates the findings.

1. Receive the goal

The parent agent interprets the user's objective, constraints, and completion criteria.

2. Decompose the work

It separates the goal into independent or specialist tasks that can be delegated safely.

3. Select the worker

It chooses a predefined subagent or creates one with the right instructions, tools, model, and permissions.

4. Pass bounded context

The parent provides the facts, files, state, and expected output the subagent needs without transferring unnecessary noise.

5. Execute and verify

The subagent reasons, uses tools, and checks its work within the authority it has been given.

6. Return and synthesize

The subagent reports its result, evidence, and uncertainty. The parent compares, combines, escalates, or takes the next action.

This orchestration layer is what turns several isolated workers into an agentic AI workflow. Without task contracts, state handling, and a clear consolidation step, a group of agents is just a set of concurrent model calls.

Agent versus Subagent

The difference is mainly about responsibility and position in the workflow. Agent describes a system's ability to pursue a goal and take actions. Subagent describes an agent that has been delegated a limited part of another agent's goal.

A subagent can be technically as capable as the parent. It may even use a stronger model or a broader tool set for a specialist task. What makes it a subagent is not model size. It is the delegated scope and reporting relationship.

Examples of Subagents

Coding Example

A main coding agent is asked to prepare a release. It delegates repository exploration to one subagent, security review to a second, and test-failure analysis to a third. Each worker returns a concise report. The main agent decides which fixes to make, resolves conflicts, runs the final checks, and presents the release summary.

Enterprise Example

A procurement agent is asked to prepare a supplier-risk assessment. It delegates sanctions screening, financial-risk analysis, contract compliance, and news research to specialist subagents. The parent compares the evidence, flags disagreements, and sends high-risk decisions to a human approver. The subagents accelerate evidence gathering; they do not replace the accountable decision-maker.

Other Useful Subagent Roles

• Research subagent that searches a defined market, geography, or source set and returns cited findings.
• Reviewer subagent that checks an output against policy, quality, security, or brand criteria.
• Data subagent that queries approved sources, calculates a metric, and reports the assumptions used.
• Customer-support subagent that investigates account history while the parent manages the conversation and approval flow.
• Verifier subagent that independently reproduces a result before the parent accepts it.

If the same specialist role appears repeatedly, it is a candidate for a reusable subagent definition. If it is a one-step deterministic action, a normal tool or workflow function may be the better design.

Why Use Subagents?

Subagents are valuable when a larger task contains work that is independent, context-heavy, or best handled by a specialist. The gains come from architecture, not from multiplying agents for its own sake.

• Context isolation: Search results, logs, test output, and file contents can stay outside the main thread. The parent receives the useful conclusion instead of every intermediate token.
• Parallel execution: Independent tasks can run at the same time, reducing elapsed time when the critical path is truly parallel.
• Specialization: Each worker can have a focused prompt, model, memory, tool set, and domain policy.
• Permission boundaries: A reviewer can be read-only, a finance subagent can access approved systems, and an execution subagent can require confirmation before taking action.
• Independent verification: A second agent can challenge a result without inheriting the first agent's full reasoning path or assumptions.
• Reusable operating patterns: Teams can standardize roles such as researcher, evaluator, compliance reviewer, or database validator across workflows.
  

Anthropic reported that its lead-agent and parallel-subagent research system outperformed a single-agent setup by 90.2% on an internal research evaluation. The same report found that token usage alone explained 80% of performance variance on BrowseComp. The result is important, but it is not a universal promise: breadth-first research benefits from parallel search in a way that tightly coupled tasks may not.

When Not to Use a Subagent

A single agent is usually the better starting point. Add a subagent only when separation creates measurable value that exceeds the cost of another context, another handoff, and another failure surface.

• The task is quick, deterministic, or can be handled by a normal function call.
• The work requires constant back-and-forth with the user or shares nearly all of the main context.
• Several agents would edit the same files or records at the same time, creating conflicts.
• The workflow is sequential and every step depends on the detailed reasoning from the previous step.
• The output cannot be evaluated, traced, or reconciled when agents disagree.
• Token cost, latency, or operational complexity matters more than parallel capacity.
  

Start by testing the use case with one well-instrumented agent. Move to subagents when evaluation shows a persistent limitation in context, expertise, latency, permissions, or independent verification. That baseline makes it possible to prove whether the multi-agent design actually improved the outcome.

How Claude Code Sub Agents Work

People searching for Claude Code sub agents are referring to the feature Anthropic styles as subagents, one word. In Claude Code, a subagent is a specialized assistant that works inside a single session, uses its own context window, and returns its result to the main conversation.

Claude agents is a broader phrase. It can refer to agents built with Claude models, Agent SDK applications, Claude Code sessions, or coordinated agent teams. A Claude Code subagent is one specific delegation mechanism within that wider ecosystem.

According to the official Claude Code subagent documentation, custom subagents can define their own system prompt, tool access, model, permissions, hooks, skills, memory, effort, maximum turns, and isolation settings. Claude can delegate automatically when a task matches the subagent description, or the user can request the subagent directly.

A basic project-level definition is stored in the .claude/agents directory as a Markdown file with YAML frontmatter. The exact fields may change as Claude Code evolves, so teams should validate configuration against the current official documentation before rollout.

---
name: security-reviewer
description: Review changed code for security risks after implementation
tools: Read, Grep, Glob
model: sonnet
---
Inspect the changed files for injection, access-control, data-exposure,
and secret-management risks. Return findings with evidence, severity,
and a recommended fix. Do not edit files.

This example is deliberately narrow. It tells Claude when to use the subagent, limits the tool set to read-only operations, defines the model, names the risks to inspect, and specifies the expected output. A vague description such as helps with security would give the parent too little routing signal.

Claude Code Subagents Versus Agent Teams

Claude Code distinguishes subagents from agent teams. Subagents report back to the main agent, which coordinates the work. Agent teams are separate Claude Code sessions with shared tasks and direct communication between teammates. Teams suit work that requires debate or ongoing coordination; subagents suit focused work where the parent mainly needs the result.

There is also a third pattern: an agent used as a tool. In Google ADK's terminology, that is a self-contained specialist called through a strict input-output contract, while a sub-agent participates in a more stateful workflow. This vocabulary is framework-specific. When comparing platforms, ask how context, state, permissions, and control actually move, not only what the component is called.

How to Design Subagents for Production

A production subagent needs more than a role prompt. It needs a contract that the orchestrator, operators, and evaluators can understand. The following design choices determine whether delegation remains useful as volume and risk increase.

• Define one bounded responsibility: State the trigger, objective, inputs, expected output, and stopping condition.
• Pass the minimum necessary context: Include authoritative facts and task constraints, but keep irrelevant history out of the worker's context.
• Restrict tools and permissions: Default to read-only access and grant write authority only where the business outcome requires it.
• Use structured outputs: Require evidence, confidence, assumptions, status, and error fields so the parent can evaluate the result consistently.
• Plan for disagreement: Decide whether the parent votes, asks a verifier, retries, escalates to a human, or stops the workflow.
• Instrument every handoff: Log the task, context reference, tool calls, output, latency, cost, model version, approvals, and final decision.
• Evaluate the whole system: Measure task success, error severity, completion time, cost per outcome, escalation rate, and human correction, not just answer quality.
• Version and retire agents: Treat prompts, tools, policies, and model choices as production components with owners, testing, rollback, and retirement criteria.
  

These controls should sit inside the wider AI agent lifecycle management process. A subagent that performs well in a demo can still drift, overuse tools, expose data, or become uneconomic when upstream systems and models change.

If you are moving from architecture to implementation, JADA's guide on how to build an AI agent covers outcomes, integrations, approvals, testing, and production readiness. Map the handoffs before choosing how many agents to build.

Build the Right Agent Architecture with JADA

The hard part is not creating more agents. It is deciding what should be delegated, what context and authority each worker needs, how results are verified, and where people stay in control.

JADA designs, builds, and manages production-grade AI agents around real business workflows. We define the architecture, connect agents securely to your systems, build human approval and escalation points, instrument the full workflow, and transfer the code, configurations, and operating knowledge to your team. You get a working system you can own, govern, and improve, not a collection of demos.

Considering a subagent or multi-agent workflow? Talk to JADA's AI agent team to scope the smallest architecture that can deliver the outcome reliably.

Frequently Asked Questions

What Is a Subagent?

A subagent is a specialized AI agent that a parent or orchestrator agent delegates to perform a bounded task and return a result for the parent to evaluate, combine, or act on.

A subagent might research one market, inspect one part of a codebase, validate one risk, or draft one component of a response. The parent remains accountable for the end-to-end objective. This separation makes the system easier to specialize, parallelize, and control, but only when the task boundaries are clear.

What Is an Example of a Subagent?

A security-review subagent is a clear example. A main coding agent delegates changed files to it after implementation. The subagent inspects the code using read-only tools, returns evidence-ranked vulnerabilities and recommended fixes, and leaves the main agent to decide what to change and how to verify the release.

What Is the Difference Between an Agent and a Subagent?

An agent may own the user's end-to-end objective and decide how the work should proceed. A subagent owns only a delegated portion of that objective and reports its result to a parent or orchestrator. The distinction is about scope and coordination, not necessarily model capability.

How Do Claude Code Subagents Work?

Claude Code subagents run as specialized assistants within a session. They use separate context, can be configured with their own prompt, model, tools, permissions, hooks, and limits, and return their result to the main conversation. They are best suited to focused tasks such as exploration, review, debugging, testing, or data analysis.