|
|
|
|
@@ -0,0 +1,190 @@
|
|
|
|
|
---
|
|
|
|
|
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:
|
|
|
|
|
- GitHub Copilot Learning Hub Team
|
|
|
|
|
lastUpdated: 2026-04-02
|
|
|
|
|
estimatedReadingTime: '9 minutes'
|
|
|
|
|
tags:
|
|
|
|
|
- agents
|
|
|
|
|
- subagents
|
|
|
|
|
- orchestration
|
|
|
|
|
- fundamentals
|
|
|
|
|
relatedArticles:
|
|
|
|
|
- ./building-custom-agents.md
|
|
|
|
|
- ./what-are-agents-skills-instructions.md
|
|
|
|
|
- ./github-copilot-terminology-glossary.md
|
|
|
|
|
prerequisites:
|
|
|
|
|
- Basic understanding of GitHub Copilot agents
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
We're [familiar with agents](./what-are-agents-skills-instructions.md), 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.
|
|
|
|
|
|
|
|
|
|
## Start with the mental model
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
## What changes when work moves to a subagent
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
## When to use subagents
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
## Launch subagents in VS Code
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
### 1. Enable the agent tool
|
|
|
|
|
|
|
|
|
|
Use the `agent` tool in frontmatter so the main agent can launch other agents:
|
|
|
|
|
|
|
|
|
|
```yaml
|
|
|
|
|
---
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
### 2. Define worker agents with clear boundaries
|
|
|
|
|
|
|
|
|
|
Worker agents are often hidden from the picker and reserved for delegation:
|
|
|
|
|
|
|
|
|
|
```yaml
|
|
|
|
|
---
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
### 3. Prompt for isolated or parallel work
|
|
|
|
|
|
|
|
|
|
You do not always need to say "run a subagent," but prompts that describe isolated research or parallel tracks make delegation easier. For example:
|
|
|
|
|
|
|
|
|
|
```text
|
|
|
|
|
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.
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### 4. Know the nesting rule
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
## Launch subagents in Copilot CLI
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
```text
|
|
|
|
|
/fleet Update the auth docs, refactor the auth service, and add related tests.
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
For non-interactive execution:
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
copilot -p "/fleet Update the auth docs, refactor the auth service, and add related tests." --no-ask-user
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
The 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.
|
|
|
|
|
|
|
|
|
|
## Orchestration patterns that work well
|
|
|
|
|
|
|
|
|
|
### Coordinator and worker
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
### Multi-perspective review
|
|
|
|
|
|
|
|
|
|
Run parallel subagents for different lenses - correctness, security, code quality, architecture - and combine the results after they finish.
|
|
|
|
|
|
|
|
|
|
### Research, then act
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
## Repository examples you can inspect
|
|
|
|
|
|
|
|
|
|
This repository already includes a few useful examples of delegation-related syntax:
|
|
|
|
|
|
|
|
|
|
- [`agents/context7.agent.md`](https://github.com/github/awesome-copilot/blob/main/agents/context7.agent.md) is a concrete example of VS Code-style `handoffs`. It defines a handoff button that can pass work to another agent after research is complete.
|
|
|
|
|
- [`agents/rug-orchestrator.agent.md`](https://github.com/github/awesome-copilot/blob/main/agents/rug-orchestrator.agent.md) is a strong coordinator example. It enables the `agent` tool and restricts delegation with `agents: ['SWE', 'QA']`.
|
|
|
|
|
- [`agents/gem-orchestrator.agent.md`](https://github.com/github/awesome-copilot/blob/main/agents/gem-orchestrator.agent.md) shows invocation control with `user-invocable` and `disable-model-invocation`, which is useful when deciding whether an orchestrator should be directly selectable, delegatable, or both.
|
|
|
|
|
- [`agents/custom-agent-foundry.agent.md`](https://github.com/github/awesome-copilot/blob/main/agents/custom-agent-foundry.agent.md) documents the VS Code `handoffs` shape in its guidance section, which is helpful if you want a template before creating your own coordinator workflow.
|
|
|
|
|
|
|
|
|
|
## Important platform nuance: handoffs are not universal
|
|
|
|
|
|
|
|
|
|
VS Code documentation describes both subagents and the `handoffs` frontmatter property. [GitHub's custom agent configuration reference](https://docs.github.com/en/copilot/customizing-copilot/github-copilot-agents/configuration-reference-for-github-copilot-agents), 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.
|
|
|
|
|
|
|
|
|
|
## Common questions
|
|
|
|
|
|
|
|
|
|
**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.
|
|
|
|
|
|
|
|
|
|
## Next steps
|
|
|
|
|
|
|
|
|
|
- Read [Building Custom Agents](../building-custom-agents/) to design coordinator and worker agents.
|
|
|
|
|
- Revisit [What are Agents, Skills, and Instructions](../what-are-agents-skills-instructions/) for the broader customization model.
|
|
|
|
|
- Keep the [GitHub Copilot Terminology Glossary](../github-copilot-terminology-glossary/) nearby when comparing terminology across products.
|
|
|
|
|
|
|
|
|
|
---
|
Aaron Powell
GitHub