Ever asked Copilot to do something complex and noticed it slowing down, losing track, or repeating itself? That happens when the agent's context window fills up with intermediate research. Subagents solve this by letting the main agent hand off focused subtasks to independent workers — each with their own clean context — and get back only a summary.
Availability: All GitHub Copilot paid plans (Pro, Pro+, Business, and Enterprise). Subagents run inside agent mode in VS Code.
The problem subagents solve
Think of it like a lead engineer working on a feature. Without subagents, that engineer does all the research, reads every file, checks every library — and keeps all of that in their head while also writing code. Eventually, the important stuff gets crowded out.
With subagents, the lead assigns research tasks to team members. Each one investigates independently and reports back a summary — not their entire notebook. The lead stays focused on the big picture.
How they work
Subagents are agent-initiated, not something you type manually. Here's the flow:
- You describe a complex task
- The main agent recognizes which parts benefit from context isolation
- It spawns a subagent, passing only the relevant subtask
- The subagent works autonomously in a separate context window
- Only the final result comes back — intermediate steps stay hidden
In VS Code, subagent runs appear as collapsible tool calls in the chat. You see the agent name and current tool ("Reading file…", "Searching codebase…"). Expand to see the full details, or keep it collapsed and stay focused.
Four key properties
| Property | What it means |
|---|---|
| Context isolation | Each subagent gets its own context window — no inherited history or instructions, just the task prompt |
| Synchronous execution | The main agent waits for results before continuing (findings usually inform the next step) |
| Parallel execution | Multiple subagents can run at the same time — security, performance, and accessibility reviews simultaneously |
| Focused results | Only the summary comes back, keeping the main context lean and token usage low |
When to use subagents
You don't invoke subagents directly — you hint at them by describing tasks that benefit from isolation or parallelism. Here are four patterns that work well:
Research before implementation. Ask the agent to investigate approaches before writing code. A subagent evaluates options and returns a recommendation, keeping the main context clean for the actual implementation.
Parallel code analysis. Need to find duplicate code, unused exports, error-handling inconsistencies, and security issues? Each analysis runs as its own subagent — faster and independently.
Explore multiple solutions. Comparing Redis caching vs. in-memory LRU vs. a hybrid approach? Subagents prototype each option in isolation, then the main agent compares results without bias.
Multi-perspective code review. Run specialized reviewers (security, performance, accessibility) in parallel. Each approaches the code fresh, and findings are synthesized into a single prioritized summary.
Custom agents as subagents
By default, subagents inherit the main session's model and tools. But you can point to
a custom agent (a .prompt.md file) with its own model,
tools, and instructions — perfect for specialized workers.
Two frontmatter properties control visibility:
user-invocable: false— hides the agent from the dropdown; it can only be used as a subagentdisable-model-invocation: true— prevents other agents from invoking it as a subagent
You can also restrict which agents a coordinator can delegate to using the
agents frontmatter property:
---
name: TDD
tools: ['agent']
agents: ['Red', 'Green', 'Refactor']
---
Implement using test-driven development:
1. Use the Red agent to write failing tests
2. Use the Green agent to make them pass
3. Use the Refactor agent to improve code qualityOrchestration: coordinator + workers
The most powerful pattern is a coordinator agent that manages the high-level flow and delegates to specialized workers. Each worker gets tailored tool access — planning agents get read-only, implementers get edit — and can even use a faster, cheaper model since their scope is narrow.
The built-in Plan agent already works this way: it uses subagents internally for its four-phase research workflow (discovery, alignment, design, refinement) before any code gets written.
Nested subagents
By default, subagents cannot spawn further subagents — this prevents infinite recursion.
For divide-and-conquer patterns, enable
chat.subagents.allowInvocationsFromSubagents in VS Code settings.
Maximum nesting depth is 5 levels.