|
| 1 | +--- |
| 2 | +title: 'Agents and Subagents' |
| 3 | +description: 'Learn how delegated subagents differ from primary agents, when to use them, and how to launch them in VS Code and Copilot CLI.' |
| 4 | +authors: |
| 5 | + - GitHub Copilot Learning Hub Team |
| 6 | +lastUpdated: 2026-04-02 |
| 7 | +estimatedReadingTime: '9 minutes' |
| 8 | +tags: |
| 9 | + - agents |
| 10 | + - subagents |
| 11 | + - orchestration |
| 12 | + - fundamentals |
| 13 | +relatedArticles: |
| 14 | + - ./building-custom-agents.md |
| 15 | + - ./what-are-agents-skills-instructions.md |
| 16 | + - ./github-copilot-terminology-glossary.md |
| 17 | +prerequisites: |
| 18 | + - Basic understanding of GitHub Copilot agents |
| 19 | +--- |
| 20 | + |
| 21 | +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. |
| 22 | + |
| 23 | +This distinction matters more as you move from simple chat prompts to orchestrated agentic workflows. |
| 24 | + |
| 25 | +## Start with the mental model |
| 26 | + |
| 27 | +Think of the main agent as a project lead and subagents as focused contributors: |
| 28 | + |
| 29 | +| Topic | Agent | Subagent | |
| 30 | +|------|------|------| |
| 31 | +| How it starts | Selected by the user or configured for the workflow | Launched by another agent or orchestrator | |
| 32 | +| Lifetime | Persists across the main conversation or session | Temporary; exists only for the delegated task | |
| 33 | +| Context | Carries the broader conversation and goals | Gets a narrower prompt and its own isolated context | |
| 34 | +| Scope | Coordinates the whole task | Performs one focused piece of work | |
| 35 | +| Output | Talks directly with the user | Reports back to the main agent, which synthesizes the result | |
| 36 | + |
| 37 | +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. |
| 38 | + |
| 39 | +## What changes when work moves to a subagent |
| 40 | + |
| 41 | +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: |
| 42 | + |
| 43 | +- **Context isolation**: the subagent gets only the task-relevant prompt, which reduces distraction from earlier conversation history. |
| 44 | +- **Focused instructions**: the subagent can use a tighter role, such as planner, implementer, reviewer, or researcher. |
| 45 | +- **Parallelism**: multiple subagents can work at the same time when tasks do not conflict. |
| 46 | +- **Controlled synthesis**: the parent agent decides what gets brought back into the main conversation. |
| 47 | +- **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. |
| 48 | + |
| 49 | +That isolation is one of the main reasons subagents can outperform a single monolithic agent on larger tasks. |
| 50 | + |
| 51 | +## When to use subagents |
| 52 | + |
| 53 | +Subagents work especially well when you need to: |
| 54 | + |
| 55 | +- research before implementation |
| 56 | +- compare multiple approaches without polluting the main thread |
| 57 | +- run parallel review perspectives, such as correctness, security, and architecture |
| 58 | +- split large work into independent tracks with explicit dependencies |
| 59 | +- keep an orchestrator agent focused on coordination rather than direct execution |
| 60 | +- compare multiple approaches across different models |
| 61 | + |
| 62 | +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. |
| 63 | + |
| 64 | +## Launch subagents in VS Code |
| 65 | + |
| 66 | +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. |
| 67 | + |
| 68 | +### 1. Enable the agent tool |
| 69 | + |
| 70 | +Use the `agent` tool in frontmatter so the main agent can launch other agents: |
| 71 | + |
| 72 | +```yaml |
| 73 | +--- |
| 74 | +name: Feature Builder |
| 75 | +tools: ['agent', 'read', 'search', 'edit'] |
| 76 | +agents: ['Planner', 'Implementer', 'Reviewer'] |
| 77 | +--- |
| 78 | +``` |
| 79 | + |
| 80 | +The `agents` property acts as an allowlist for which worker agents this coordinator can call. |
| 81 | + |
| 82 | +### 2. Define worker agents with clear boundaries |
| 83 | + |
| 84 | +Worker agents are often hidden from the picker and reserved for delegation: |
| 85 | + |
| 86 | +```yaml |
| 87 | +--- |
| 88 | +name: Planner |
| 89 | +user-invocable: false |
| 90 | +tools: ['read', 'search'] |
| 91 | +--- |
| 92 | +``` |
| 93 | + |
| 94 | +You can also use `disable-model-invocation: true` to prevent an agent from being used as a subagent unless another coordinator explicitly allows it. |
| 95 | + |
| 96 | +### 3. Prompt for isolated or parallel work |
| 97 | + |
| 98 | +You do not always need to say "run a subagent," but prompts that describe isolated research or parallel tracks make delegation easier. For example: |
| 99 | + |
| 100 | +```text |
| 101 | +Analyze this feature in parallel: |
| 102 | +1. Research existing code patterns |
| 103 | +2. Propose an implementation plan |
| 104 | +3. Review likely security risks |
| 105 | +Then summarize the findings into one recommendation. |
| 106 | +``` |
| 107 | + |
| 108 | +### 4. Know the nesting rule |
| 109 | + |
| 110 | +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. |
| 111 | + |
| 112 | +## Launch subagents in Copilot CLI |
| 113 | + |
| 114 | +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. |
| 115 | + |
| 116 | +```text |
| 117 | +/fleet Update the auth docs, refactor the auth service, and add related tests. |
| 118 | +``` |
| 119 | + |
| 120 | +For non-interactive execution: |
| 121 | + |
| 122 | +```bash |
| 123 | +copilot -p "/fleet Update the auth docs, refactor the auth service, and add related tests." --no-ask-user |
| 124 | +``` |
| 125 | + |
| 126 | +The important behavior is different from a single chat turn: |
| 127 | + |
| 128 | +- the orchestrator plans work items first |
| 129 | +- independent tasks can run in parallel |
| 130 | +- each subagent gets its own context window |
| 131 | +- subagents share the same filesystem, so overlapping writes should be avoided |
| 132 | + |
| 133 | +That makes `/fleet` a practical way to launch subagents even if you are not authoring custom agent files yourself. |
| 134 | + |
| 135 | +## Orchestration patterns that work well |
| 136 | + |
| 137 | +### Coordinator and worker |
| 138 | + |
| 139 | +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. |
| 140 | + |
| 141 | +### Multi-perspective review |
| 142 | + |
| 143 | +Run parallel subagents for different lenses - correctness, security, code quality, architecture - and combine the results after they finish. |
| 144 | + |
| 145 | +### Research, then act |
| 146 | + |
| 147 | +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. |
| 148 | + |
| 149 | +## Repository examples you can inspect |
| 150 | + |
| 151 | +This repository already includes a few useful examples of delegation-related syntax: |
| 152 | + |
| 153 | +- [`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. |
| 154 | +- [`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']`. |
| 155 | +- [`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. |
| 156 | +- [`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. |
| 157 | + |
| 158 | +## Important platform nuance: handoffs are not universal |
| 159 | + |
| 160 | +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. |
| 161 | + |
| 162 | +That means you should think about delegation features in product-specific terms: |
| 163 | + |
| 164 | +- **VS Code**: supports subagent concepts, allowlists, and handoff-oriented agent composition |
| 165 | +- **Copilot CLI**: exposes practical orchestration through commands like `/fleet` |
| 166 | +- **GitHub.com coding agent / cloud agent**: supports custom agents, but some VS Code-specific frontmatter is intentionally ignored |
| 167 | + |
| 168 | +If you share agent files across surfaces, document those differences so users know which behaviors are portable and which are editor-specific. |
| 169 | + |
| 170 | +## Common questions |
| 171 | + |
| 172 | +**Do users always invoke subagents directly?** |
| 173 | + |
| 174 | +No. Most of the time the main agent launches them when it decides the task benefits from context isolation or parallelism. |
| 175 | + |
| 176 | +**Can a subagent use a different model or tool set?** |
| 177 | + |
| 178 | +Yes, when the delegated worker is a custom agent with its own frontmatter. |
| 179 | + |
| 180 | +**Are subagents always parallel?** |
| 181 | + |
| 182 | +No. They can run sequentially when one step depends on another, or in parallel when work items are independent. |
| 183 | + |
| 184 | +## Next steps |
| 185 | + |
| 186 | +- Read [Building Custom Agents](../building-custom-agents/) to design coordinator and worker agents. |
| 187 | +- Revisit [What are Agents, Skills, and Instructions](../what-are-agents-skills-instructions/) for the broader customization model. |
| 188 | +- Keep the [GitHub Copilot Terminology Glossary](../github-copilot-terminology-glossary/) nearby when comparing terminology across products. |
| 189 | + |
| 190 | +--- |
0 commit comments