| title | Agents and Subagents | ||||
|---|---|---|---|---|---|
| description | Learn how delegated subagents differ from primary agents, when to use them, and how to launch them in VS Code and Copilot CLI. | ||||
| authors |
|
||||
| lastUpdated | 2026-04-02 | ||||
| estimatedReadingTime | 9 minutes | ||||
| tags |
|
||||
| relatedArticles |
|
||||
| prerequisites |
|
We're familiar with agents, but there is another aspect to agentic workflows that we need to consider, and that is the role of subagents. An agent is the primary assistant you choose for a session or workflow while a subagent is a temporary worker that the main agent launches for a narrower task, usually to keep context clean, parallelize work, or apply a more specialized set of instructions.
This distinction matters more as you move from simple chat prompts to orchestrated agentic workflows.
Think of the main agent as a project lead and subagents as focused contributors:
| 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 |
In practice, the main agent keeps the big picture while subagents absorb the noisy intermediate work: research, code inspection, specialized review passes, or independent implementation tracks.
Subagents are useful because they are not just "the same agent in another tab." They usually change the shape of the work in a few important ways:
- Context isolation: the subagent gets only the task-relevant prompt, which reduces distraction from earlier conversation history.
- Focused instructions: the subagent can use a tighter role, such as planner, implementer, reviewer, or researcher.
- Parallelism: multiple subagents can work at the same time when tasks do not conflict.
- Controlled synthesis: the parent agent decides what gets brought back into the main conversation.
- Alternative model selection: the subagent can use a different AI model to perform a task, so while our main agent might be using a generalist model, a subagent could be configured to use a more specialized one for code review or research.
That isolation is one of the main reasons subagents can outperform a single monolithic agent on larger tasks.
Subagents work especially well when you need to:
- research before implementation
- compare multiple approaches without polluting the main thread
- run parallel review perspectives, such as correctness, security, and architecture
- split large work into independent tracks with explicit dependencies
- keep an orchestrator agent focused on coordination rather than direct execution
- compare multiple approaches across different models
If all of the work happens in one small file and does not need decomposition, a subagent may be unnecessary. The benefit appears when delegation reduces context pressure or lets multiple tracks run independently.
In VS Code, subagents are typically agent-initiated. You usually describe the larger task, and the main agent decides when to delegate a focused subtask. To make that possible, the agent needs access to the subagent tool.
Use the agent tool in frontmatter so the main agent can launch other agents:
---
name: Feature Builder
tools: ['agent', 'read', 'search', 'edit']
agents: ['Planner', 'Implementer', 'Reviewer']
---The agents property acts as an allowlist for which worker agents this coordinator can call.
Worker agents are often hidden from the picker and reserved for delegation:
---
name: Planner
user-invocable: false
tools: ['read', 'search']
---You can also use disable-model-invocation: true to prevent an agent from being used as a subagent unless another coordinator explicitly allows it.
You do not always need to say "run a subagent," but prompts that describe isolated research or parallel tracks make delegation easier. For example:
Analyze this feature in parallel:
1. Research existing code patterns
2. Propose an implementation plan
3. Review likely security risks
Then summarize the findings into one recommendation.
By default, subagents do not keep spawning additional subagents. In VS Code, recursive delegation is controlled by the chat.subagents.allowInvocationsFromSubagents setting, which is off by default.
In GitHub Copilot CLI, the clearest end-user entry point is /fleet. Fleet acts as an orchestrator that decomposes a larger objective, launches multiple background subagents, respects dependencies, and then synthesizes the final result.
/fleet Update the auth docs, refactor the auth service, and add related tests.
For non-interactive execution:
copilot -p "/fleet Update the auth docs, refactor the auth service, and add related tests." --no-ask-userThe important behavior is different from a single chat turn:
- the orchestrator plans work items first
- independent tasks can run in parallel
- each subagent gets its own context window
- 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 files yourself.
One agent owns the workflow and delegates to narrower specialists such as planner, implementer, and reviewer. This keeps the coordinator lightweight and makes the worker prompts more precise.
Run parallel subagents for different lenses - correctness, security, code quality, architecture - and combine the results after they finish.
Use one subagent to gather facts and another to implement with those facts. This pattern is especially helpful when you want the main thread to stay free of exploratory noise.
This repository already includes a few useful examples of delegation-related syntax:
agents/context7.agent.mdis a concrete example of VS Code-stylehandoffs. It defines a handoff button that can pass work to another agent after research is complete.agents/rug-orchestrator.agent.mdis a strong coordinator example. It enables theagenttool and restricts delegation withagents: ['SWE', 'QA'].agents/gem-orchestrator.agent.mdshows invocation control withuser-invocableanddisable-model-invocation, which is useful when deciding whether an orchestrator should be directly selectable, delegatable, or both.agents/custom-agent-foundry.agent.mddocuments the VS Codehandoffsshape in its guidance section, which is helpful if you want a template before creating your own coordinator workflow.
VS Code documentation describes both subagents and the handoffs frontmatter property. GitHub's custom agent configuration reference, however, notes that handoffs and argument-hint are currently ignored for Copilot cloud agent on GitHub.com.
That means you should think about delegation features in product-specific terms:
- VS Code: supports subagent concepts, allowlists, and handoff-oriented agent composition
- Copilot CLI: exposes practical orchestration through commands like
/fleet - GitHub.com coding agent / 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.
Do users always invoke subagents directly?
No. Most of the time the main agent launches them when it decides the task benefits from context isolation or parallelism.
Can a subagent use a different model or tool set?
Yes, when the delegated worker is a custom agent with its own frontmatter.
Are subagents always parallel?
No. They can run sequentially when one step depends on another, or in parallel when work items are independent.
- Read Building Custom Agents to design coordinator and worker agents.
- Revisit What are Agents, Skills, and Instructions for the broader customization model.
- Keep the GitHub Copilot Terminology Glossary nearby when comparing terminology across products.