Subagents in Visual Studio Code

When working on complex tasks, you can delegate subtasks to subagents. A subagent is an independent AI agent that performs focused work, such as researching a topic, analyzing code, or reviewing changes, and reports the results back to the main agent.

For background on subagent concepts (context isolation, synchronous and parallel execution), see Agents concepts.

This article explains how to use subagents in VS Code, including usage scenarios, invocation patterns, and how to run custom agents as subagents.

What the user sees

When a subagent runs, it appears in the chat as a collapsible tool call. By default, the subagent is collapsed and shows:

• The name of the custom agent (if you specify one)
• The currently running tool (for example, "Reading file..." or "Searching codebase...")

Select the subagent tool call to expand it and view the full details, including all tool calls the subagent made, the prompt passed to the subagent, and the returned result.

This visibility gives you control over how much detail you see without cluttering your main conversation with intermediate steps.

Usage scenarios

The following scenarios illustrate when subagents can improve your AI-assisted development workflow.

Use a subagent to research OAuth 2.0 implementation patterns for Node.js applications.
Compare passport.js vs auth0 vs custom implementation. Return a recommendation with pros and cons.

Analyze this codebase for refactoring opportunities. Use subagents to:
1. Find duplicate code patterns
2. Identify unused exports and dead code
3. Review error handling consistency
4. Check for security vulnerabilities

Compile the findings into a prioritized action plan.

I need to implement caching for this API. Run three subagents in parallel to:
1. Design a Redis-based caching solution
2. Design an in-memory caching solution with LRU eviction
3. Design a hybrid approach with tiered caching

Compare the results and recommend the best approach for our use case.

Review the changes in this PR using subagents:
- Run the security-reviewer agent to check for vulnerabilities
- Run the performance-reviewer agent to identify bottlenecks
- Run the accessibility-reviewer agent to verify a11y compliance

Consolidate findings into a single review summary.

Invoke a subagent

Agent-initiated vs. user-invoked

Subagents are typically agent-initiated, not directly invoked by users in chat. To allow the main agent to invoke subagents, make sure the runSubagent tool is enabled.

The main agent decides when context isolation helps. You don't need to manually type "run a subagent" for every task. The pattern works like this:

1. You (or your custom agent's instructions) describe a complex task.
2. The main agent recognizes the part of the task that benefits from isolated context.
3. The agent starts a subagent, passing only the relevant subtask.
4. The subagent works autonomously and returns a summary.
5. The main agent incorporates the result and continues.

You can hint that you want subagent delegation by phrasing your prompt to suggest isolated research or parallel analysis. The main agent will start a subagent, pass the task to it, and receive only the final result.

To optimize subagent performance, clearly define the task and expected output. This helps the subagent focus on the specific goal without passing unnecessary context back to the main agent.

See the usage scenarios section for examples of how to structure prompts that invoke subagents.

Invoke a subagent in a prompt file

To invoke a subagent inside a prompt file, ensure that the runSubagent or agent tool is included in the tools frontmatter property:

---
name: document-feature
tools: ['agent', 'read', 'search', 'edit']
---
Run a subagent to research the new feature implementation details and return only information relevant for user documentation.
Then update the docs/ folder with the new documentation.

In the prompt instructions, you can then hint the agent to use subagents by suggesting isolated research or parallel analysis for specific subtasks.

Run a custom agent as a subagent (Experimental)

By default, a subagent inherits the agent from the main chat session and uses the same model and tools. To define specific behavior for a subagent, use a custom agent. Custom agents can specify their own model, tools, and instructions. When used as a subagent, these settings override the defaults inherited from the main session.

Control subagent invocation

You can control how a custom agent can be invoked by using two frontmatter properties:

• user-invocable: controls whether the agent appears in the agents dropdown in chat (default is true). Set to false to create agents that are only accessible as subagents.
• disable-model-invocation: prevents the agent from being invoked as a subagent by other agents (default is false). Set to true when agents should only be triggered explicitly by users.

For example, to create an agent that can only be used as a subagent (not visible in the dropdown):

---
name: internal-helper
user-invocable: false
---

This agent can only be invoked as a subagent.

To run a custom agent as a subagent, prompt the AI to use a custom or built-in agent for the subagent. For example:

• Run the Research agent as a subagent to research the best auth methods for this project.
• Use the Plan agent in a subagent to create an implementation plan for myfeature. Then save the plan in plans/myfeature.plan.md

Restrict which subagents can be used (Experimental)

By default, all custom agents that don't have disable-model-invocation: true are available to be used as subagents. If two or more agents have similar names or descriptions, the AI might select an unintended agent.

You can restrict which custom agents can be used as subagents by specifying the agents property in the main agent's frontmatter, and providing a list of allowed custom agents.

The agents property accepts:

• A list of agent names (for example, ['Edit', 'Search']) to allow only specific agents
• * to allow all available agents (default behavior)
• An empty array [] to prevent any subagent use

For example, a test-driven development (TDD) agent should only use the Red, Green, and Refactor agents as subagents. If not restricted, the TDD agent might select a more generic coding agent for implementing the tests instead of the specialized TDD agents.

---
name: TDD
tools: ['agent']
agents: ['Red', 'Green', 'Refactor']
---
Implement the following feature using test-driven development. Use subagents to guide the following steps:
1. Use the Red agent to write failing tests
2. Use the Green agent to implement code to pass the tests
3. Use the Refactor agent to improve the code quality

Orchestration patterns

Subagents enable orchestration patterns where a coordinator agent delegates work to specialized worker agents. This approach helps you build sophisticated workflows while keeping each agent focused on what it does best.

Coordinator and worker pattern

A coordinator agent manages the overall task and delegates subtasks to specialized subagents. Each worker agent can have a tailored set of tools. For example, planning and review agents need only read-only access, while the implementer needs edit capabilities.

---
name: Feature Builder
tools: ['agent', 'edit', 'search', 'read']
agents: ['Planner', 'Plan Architect', 'Implementer', 'Reviewer']
---
You are a feature development coordinator. For each feature request:

1. Use the Planner agent to break down the feature into tasks.
2. Use the Plan Architect agent to validate the plan against codebase patterns.
3. If the architect identifies reusable patterns or libraries, send feedback to the Planner to update the plan.
4. Use the Implementer agent to write the code for each task.
5. Use the Reviewer agent to check the implementation.
6. If the reviewer identifies issues, use the Implementer agent again to apply fixes.

Iterate between planning and architecture, and between review and implementation, until each phase converges.

The worker agents each define their own tool access and can pick a faster or more cost-effective model since they have a narrower focus:

---
name: Planner
user-invocable: false
tools: ['read', 'search']
---
Break down feature requests into implementation tasks. Incorporate feedback from the Plan Architect.

---
name: Plan Architect
user-invocable: false
tools: ['read', 'search']
---
Validate plans against the codebase. Identify existing patterns, utilities, and libraries that should be reused. Flag any plan steps that duplicate existing functionality.

---
name: Implementer
user-invocable: false
model: ['Claude Haiku 4.5 (copilot)', 'Gemini 3 Flash (Preview) (copilot)']
---
Write code to complete assigned tasks.

This pattern keeps the coordinator's context focused on the high-level workflow while each worker agent has a clean context and appropriate permissions for its specific job.

Multi-perspective code review

Code review benefits from multiple perspectives. A single pass often misses problems that become obvious when you look through a different lens. Use subagents to run each review perspective in parallel, then synthesize the findings.

---
name: Thorough Reviewer
tools: ['agent', 'read', 'search']
---
You review code through multiple perspectives simultaneously. Run each perspective as a parallel subagent so findings are independent and unbiased.

When asked to review code, run these subagents in parallel:
- Correctness reviewer: logic errors, edge cases, type issues.
- Code quality reviewer: readability, naming, duplication.
- Security reviewer: input validation, injection risks, data exposure.
- Architecture reviewer: codebase patterns, design consistency, structural alignment.

After all subagents complete, synthesize findings into a prioritized summary. Note which issues are critical versus nice-to-have. Acknowledge what the code does well.

This pattern works because each subagent approaches the code fresh, without being anchored by what other perspectives found. In this example, the orchestrator shapes each subagent's focus area through its prompt. This is a lightweight approach that requires no additional agent files.

Related resources

• Agents overview - Learn about the different types of agents in VS Code
• Custom agents - Create your own AI agents
• Chat sessions - Manage chat sessions in VS Code