Learning Hub: Agents and subagents

website/astro.config.mjs

@@ -66,6 +66,7 @@ export default defineConfig({
           label: "Fundamentals",
           items: [
             "learning-hub/what-are-agents-skills-instructions",
+            "learning-hub/agents-and-subagents",
             "learning-hub/understanding-copilot-context",
             "learning-hub/copilot-configuration-basics",
             "learning-hub/defining-custom-instructions",

website/src/content/docs/learning-hub/agents-and-subagents.md

@@ -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, 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.
+
+---

website/src/content/docs/learning-hub/building-custom-agents.md

@@ -11,6 +11,7 @@ tags:
   - fundamentals
 relatedArticles:
   - ./what-are-agents-skills-instructions.md
+  - ./agents-and-subagents.md
   - ./creating-effective-skills.md
   - ./understanding-mcp-servers.md
 prerequisites:

website/src/content/docs/learning-hub/github-copilot-terminology-glossary.md

@@ -3,7 +3,7 @@ title: 'GitHub Copilot Terminology Glossary'
 description: 'A quick reference guide defining common GitHub Copilot and platform-specific terms.'
 authors:
   - GitHub Copilot Learning Hub Team
-lastUpdated: 2025-12-15
+lastUpdated: 2026-04-02
 estimatedReadingTime: '8 minutes'
 tags:
   - glossary
@@ -24,14 +24,24 @@ Use this page as a quick reference when reading articles in the Learning Hub or
 
 ### Agent
 
-A specialized configuration file (`*.agent.md`) that defines a GitHub Copilot persona or assistant with specific expertise, tools, and behavior patterns. Agents integrate with MCP servers to provide enhanced capabilities for particular workflows (e.g., "Terraform Expert" or "Security Auditor").
+A specialized configuration file (`*.agent.md`) that defines a GitHub Copilot persona or assistant with specific expertise, tools, and behavior patterns. In products that support delegation, the agent is usually the primary coordinator or main session persona, while subagents handle narrower delegated tasks.
 
 **When to use**: For recurring workflows that benefit from deep tooling integrations and persistent conversational context.
 
 **Learn more**: [What are Agents, Skills, and Instructions](../what-are-agents-skills-instructions/)
 
 ---
 
+### Subagent
+
+A temporary, task-focused agent launched by another agent or orchestrator. A subagent usually gets a narrower prompt, its own isolated context window, and returns a summary back to the main agent instead of staying in the primary conversation.
+
+**When to use**: For isolated research, parallel analysis, specialized review passes, or delegated implementation steps.
+
+**Learn more**: [Agents and Subagents](../agents-and-subagents/)
+
+---
+
 ### Built-in Tool
 
 A native capability provided by GitHub Copilot without requiring additional configuration or MCP servers. Examples include code search, file editing, terminal command execution, and web search. Built-in tools are always available and don't require installation.
@@ -101,6 +111,16 @@ tools: ['codebase']
 
 ---
 
+### Handoff
+
+A VS Code custom-agent frontmatter property (`handoffs`) that defines suggested transitions from one agent to another, often with a pre-filled follow-up prompt. Handoffs are useful for guided workflows such as research -> implementation or planning -> review.
+
+**Important**: GitHub's custom agent configuration reference says `handoffs` are currently ignored for Copilot cloud agent on GitHub.com, so this concept is not portable across every Copilot surface.
+
+**Learn more**: [Agents and Subagents](../agents-and-subagents/), [Building Custom Agents](../building-custom-agents/)
+
+---
+
 ### AGENTS.md
 
 An emerging industry standard file format for defining portable AI coding instructions that work across different AI coding tools (GitHub Copilot, Claude, Codex, and others). The `AGENTS.md` file, typically placed in a repository root or `.github/` directory, contains instructions for how AI assistants should interact with your codebase.

website/src/content/docs/learning-hub/index.md

@@ -8,7 +8,8 @@ tableOfContents: false
 
 Essential concepts to tailor GitHub Copilot beyond its default experience. Start with
 [What are Agents, Skills, and Instructions](what-are-agents-skills-instructions/)
-and work through the full track to master every customization primitive.
+and work through the full track to master every customization primitive. For delegation
+and orchestration patterns, continue with [Agents and Subagents](agents-and-subagents/).
 
 ## Reference
 

website/src/content/docs/learning-hub/what-are-agents-skills-instructions.md

@@ -20,11 +20,14 @@ Agents are configuration files (`*.agent.md`) that describe:
 
 When you assign an issue to Copilot or open the **Agents** panel in VS Code, these configurations let you swap in a specialized assistant. Each agent in this repo lives under `agents/` and includes metadata about the tools it depends on.
 
+In products that support delegation, a primary agent can also launch temporary subagents for focused work such as planning, research, or review. See [Agents and Subagents](../agents-and-subagents/) for the coordination model.
+
 ### When to reach for an agent
 
 - You have a recurring workflow that benefits from deep tooling integrations.
 - You want Copilot to proactively execute commands or fetch context via MCP.
 - You need persona-level guardrails that persist throughout a coding session.
+- You want a coordinator that can delegate narrower work to subagents.
 
 ## Skills