Subagents: How Copilot Delegates Work in VS Code

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.

Agent vs subagent: the mental model

Think of the main agent as a project lead and subagents as focused contributors. The two differ on five axes that show up in everyday use:

Topic	Agent	Subagent
How it starts	Selected by the user or configured for the workflow	Launched by another agent or orchestrator
Lifetime	Persists across the main conversation or session	Temporary; exists only for the delegated task
Context	Carries the broader conversation and goals	Gets a narrower prompt and its own isolated context
Scope	Coordinates the whole task	Performs one focused piece of work
Output	Talks directly with the user	Reports back to the main agent, which synthesizes the result

That isolation is the main reason subagents can outperform a single monolithic agent on larger tasks: the parent keeps the big picture while the workers absorb the noisy intermediate work — research, code inspection, specialized review passes, or independent implementation tracks.

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 subagent
disable-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 quality

Orchestration: 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.

Beyond VS Code: `/fleet` in Copilot CLI

Subagents are not a VS Code-only idea. In GitHub Copilot CLI, the clearest end-user entry point is the /fleet command. Fleet acts as an orchestrator that decomposes a larger objective, launches multiple background subagents, respects dependencies between them, and synthesizes a single final result.

/fleet Update the auth docs, refactor the auth service, and add related tests.

For non-interactive runs (CI, scripts, headless usage):

copilot -p "/fleet Update the auth docs, refactor the auth service, and add related tests." --no-ask-user

The behavior differs from a single chat turn in four important ways:

The orchestrator plans work items first, before any execution.
Independent tasks run in parallel; dependent ones run in order.
Each subagent gets its own context window.
All subagents share the same filesystem, so overlapping writes should be avoided.

That makes /fleet a practical way to launch subagents even if you are not authoring custom .agent.md files yourself.

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.

Platform nuance: handoffs are not universal

VS Code documents both subagents and a handoffs frontmatter property for passing work between agents. GitHub's custom agent configuration reference, however, notes that handoffs and argument-hint are currently ignored for the Copilot cloud agent on github.com. Think about delegation features in product-specific terms:

VS Code — supports subagents, allowlists, and handoff-oriented composition.
Copilot CLI — exposes practical orchestration through commands like /fleet.
GitHub.com cloud agent — supports custom agents, but some VS Code-specific frontmatter is intentionally ignored.

If you share agent files across surfaces, document those differences so users know which behaviors are portable and which are editor-specific.

Repository examples worth inspecting

The github/awesome-copilot repository has concrete, copy-pasteable examples of every pattern above:

rug-orchestrator.agent.md — a strong coordinator example that enables the agent tool and restricts delegation with agents: ['SWE', 'QA'].
gem-orchestrator.agent.md — shows invocation control with user-invocable and disable-model-invocation.
context7.agent.md — a concrete VS Code-style handoffs definition that hands off work after research is complete.
custom-agent-foundry.agent.md — documents the VS Code handoffs shape, useful as a template before authoring your own coordinator.