docs(copilot): clarify subagent execution model and orchestration patterns #9331
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
ntrogh
requested changes
Feb 6, 2026
Contributor
ntrogh
left a comment
ntrogh
left a comment
There was a problem hiding this comment.
@digitarald Great additions to the doc!! I left some minor comments (a.o. I don't like em-dashes ;) )
| The pattern works like this: | ||
|
|
||
| 1. You (or your custom agent's instructions) describe a complex task. | ||
| 2. The main agent recognizes that part of the task benefits from isolated context. |
Contributor
There was a problem hiding this comment.
Suggested change
| 2. The main agent recognizes that part of the task benefits from isolated context. | |
| 2. The main agent recognizes the part of the task that benefits from isolated context. |
| Subagents in Visual Studio Code provide context isolation and enable you to run tasks in a dedicated context window, separate from the main agent session. This allows you to delegate complex or multi-step tasks to autonomous subagents without affecting the context window of the main chat session and helps it stay focused on the primary task. VS Code can run multiple subagents in parallel to improve overall performance. | ||
|
|
||
| By default, subagents use the same agent and model as the main chat session. By running a custom agent as a subagent, you can apply specialized behavior, tools, and models for specific tasks. For example, use a research custom agent as a subagent to gather information and perform research tasks. | ||
| By default, subagents use the same model and tools as the main chat session but start with a clean context window. Subagents do not inherit the main agent's instructions or conversation history—they receive only the task prompt you provide. By running a custom agent as a subagent, you can apply specialized behavior, tools, and models for specific tasks. For example, use a research custom agent as a subagent to gather information and perform research tasks. |
Contributor
There was a problem hiding this comment.
Suggested change
| By default, subagents use the same model and tools as the main chat session but start with a clean context window. Subagents do not inherit the main agent's instructions or conversation history—they receive only the task prompt you provide. By running a custom agent as a subagent, you can apply specialized behavior, tools, and models for specific tasks. For example, use a research custom agent as a subagent to gather information and perform research tasks. | |
| By default, subagents use the same model and tools as the main chat session but start with a clean context window. Subagents do not inherit the main agent's instructions or conversation history, they receive only the task prompt you provide. By running a custom agent as a subagent, you can apply specialized behavior, tools, and models for specific tasks. For example, use a research custom agent as a subagent to gather information and perform research tasks. |
|
|
||
| ## How subagent execution works | ||
|
|
||
| Subagents are **synchronous**—the main agent waits for subagent results before continuing. This blocking behavior is intentional: subagent findings typically inform the next step of the task. Without the subagent results, the main agent lacks the information it needs to proceed effectively. |
Contributor
There was a problem hiding this comment.
Suggested change
| Subagents are **synchronous**—the main agent waits for subagent results before continuing. This blocking behavior is intentional: subagent findings typically inform the next step of the task. Without the subagent results, the main agent lacks the information it needs to proceed effectively. | |
| Subagents are **synchronous**: the main agent waits for subagent results before continuing. This blocking behavior is intentional: subagent findings typically inform the next step of the task. Without the subagent results, the main agent lacks the information it needs to proceed effectively. |
| However, VS Code can spawn **multiple subagents in parallel**. When you request parallel analysis (for example, "analyze security, performance, and accessibility simultaneously"), VS Code runs those subagents concurrently and waits for all results before the main agent continues. | ||
|
|
||
| > [!NOTE] | ||
| > Subagents are different from starting a new agent session. A new session creates an entirely separate conversation with no connection to your current task. Subagents maintain the relationship—they do focused work and report back to the main agent, which stays in control of the overall task. |
Contributor
There was a problem hiding this comment.
Suggested change
| > Subagents are different from starting a new agent session. A new session creates an entirely separate conversation with no connection to your current task. Subagents maintain the relationship—they do focused work and report back to the main agent, which stays in control of the overall task. | |
| > Subagents are different from starting a new agent session. A new session creates an entirely separate conversation with no connection to your current task. Subagents maintain the relationship: they do focused work and report back to the main agent, which stays in control of the overall task. |
| Hint in your chat prompt that you want to use a subagent to perform a specific task. The main agent will start a subagent, pass the task to it, and receive only the final result. | ||
| ### Agent-initiated vs user-invoked | ||
|
|
||
| Subagents are typically **agent-initiated**, not directly invoked by users in chat. The main agent decides when context isolation helps—you don't manually type "run a subagent" for every task. |
Contributor
There was a problem hiding this comment.
Suggested change
| Subagents are typically **agent-initiated**, not directly invoked by users in chat. The main agent decides when context isolation helps—you don't manually type "run a subagent" for every task. | |
| Subagents are typically **agent-initiated**, not directly invoked by users in chat. The main agent decides when context isolation helps. You don't manually need to type "run a subagent" for every task. |
| ## Run a custom agent as a subagent (Experimental) | ||
|
|
||
| By default, a subagent inherits the agent from the main chat session and uses the same model and tools. To define specific behavior for a subagent, use a [custom agent](/docs/copilot/customization/custom-agents.md). | ||
| By default, a subagent inherits the agent from the main chat session and uses the same model and tools. To define specific behavior for a subagent, use a [custom agent](/docs/copilot/customization/custom-agents.md). Custom agents can specify their own model, tools, and instructions—when used as a subagent, these settings override the defaults inherited from the main session. |
Contributor
There was a problem hiding this comment.
Suggested change
| By default, a subagent inherits the agent from the main chat session and uses the same model and tools. To define specific behavior for a subagent, use a [custom agent](/docs/copilot/customization/custom-agents.md). Custom agents can specify their own model, tools, and instructions—when used as a subagent, these settings override the defaults inherited from the main session. | |
| By default, a subagent inherits the agent from the main chat session and uses the same model and tools. To define specific behavior for a subagent, use a [custom agent](/docs/copilot/customization/custom-agents.md). Custom agents can specify their own model, tools, and instructions. When used as a subagent, these settings override the defaults inherited from the main session. |
|
|
||
| ### Coordinator and worker pattern | ||
|
|
||
| A coordinator agent manages the overall task and delegates subtasks to specialized subagents. Each worker agent can have a tailored set of tools—for example, planning and review agents need only read-only access, while the implementer needs edit capabilities. |
Contributor
There was a problem hiding this comment.
Suggested change
| A coordinator agent manages the overall task and delegates subtasks to specialized subagents. Each worker agent can have a tailored set of tools—for example, planning and review agents need only read-only access, while the implementer needs edit capabilities. | |
| A coordinator agent manages the overall task and delegates subtasks to specialized subagents. Each worker agent can have a tailored set of tools. For example, planning and review agents need only read-only access, while the implementer needs edit capabilities. |
| After all subagents complete, synthesize findings into a prioritized summary. Note which issues are critical versus nice-to-have. Acknowledge what the code does well. | ||
| ``` | ||
|
|
||
| This pattern works because each subagent approaches the code fresh, without being anchored by what other perspectives found. In this example, the orchestrator shapes each subagent's focus area through its prompt—a lightweight approach that requires no additional agent files. |
Contributor
There was a problem hiding this comment.
Suggested change
| This pattern works because each subagent approaches the code fresh, without being anchored by what other perspectives found. In this example, the orchestrator shapes each subagent's focus area through its prompt—a lightweight approach that requires no additional agent files. | |
| This pattern works because each subagent approaches the code fresh, without being anchored by what other perspectives found. In this example, the orchestrator shapes each subagent's focus area through its prompt. This is a lightweight approach that requires no additional agent files. |
| This pattern works because each subagent approaches the code fresh, without being anchored by what other perspectives found. In this example, the orchestrator shapes each subagent's focus area through its prompt—a lightweight approach that requires no additional agent files. | ||
|
|
||
| > [!TIP] | ||
| > For more control, each review perspective can be its own custom agent with specialized tool access. For example, a security reviewer might use a security-focused MCP server, while a code quality reviewer might have access to linting CLI tools. This lets each perspective use the best tools for its specific focus. |
Contributor
There was a problem hiding this comment.
Suggested change
| > For more control, each review perspective can be its own custom agent with specialized tool access. For example, a security reviewer might use a security-focused MCP server, while a code quality reviewer might have access to linting CLI tools. This lets each perspective use the best tools for its specific focus. | |
| > For more control, each review perspective can be its own custom agent with specialized tool access. For example, a security reviewer might use a security-focused MCP server, while a code-quality reviewer might have access to linting CLI tools. This lets each perspective use the best tools for its specific focus. |
|
|
||
| ```mermaid | ||
| flowchart LR | ||
| A["Main Agent"] -->|"Spawns with task prompt"| B["Subagent\n(clean context)"] |
Contributor
There was a problem hiding this comment.
I think the Mermaid renderer needs <br> instead of newline characters.
Also, currently we don't support Mermaid on our website - can you create a PNG and use that instead? You can put the Mermaid in comments to have the source info.
Contributor
There was a problem hiding this comment.
Pull request overview
This PR clarifies the subagent execution model and orchestration patterns in VS Code Copilot documentation. It addresses user confusion about how subagents work by providing detailed explanations of synchronous execution, parallel spawning capabilities, UI visibility, and the relationship between custom agents and subagents. The changes also introduce two orchestration patterns (coordinator/worker and multi-perspective code review) to demonstrate practical applications.
Changes:
- Added detailed explanation of synchronous subagent execution with parallel spawning capabilities, including a mermaid diagram visualizing the flow
- Clarified agent-initiated vs user-invoked patterns and added guidance for defining subagent behavior in custom agent instructions
- Documented how the
agentsarray overridesdisable-model-invocation: truefor explicit allowlisting - Added two orchestration pattern examples: coordinator/worker pattern for feature development and multi-perspective code review pattern
| - Correctness reviewer: logic errors, edge cases, type issues. | ||
| - Code quality reviewer: readability, naming, duplication. | ||
| - Security reviewer: input validation, injection risks, data exposure. | ||
| - Architecture reviewer: does this fit the codebase patterns? |
There was a problem hiding this comment.
The list items have inconsistent structure. The first three items use noun phrases (for example, "logic errors, edge cases, type issues"), while the last item uses a question ("does this fit the codebase patterns?"). For parallel structure, consider reformulating the last item to match the pattern, such as "Architecture reviewer: codebase patterns, design consistency, structural alignment."
Suggested change
| - Architecture reviewer: does this fit the codebase patterns? | |
| - Architecture reviewer: codebase patterns, design consistency, structural alignment. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Addresses user confusion about subagent behavior. Clarifies synchronous execution, parallel spawning, UI visibility, agent-initiated invocation, custom agent model overrides, agents array overriding disable-model-invocation, and adds orchestration patterns (coordinator/worker, multi-perspective code review). Replaces #9330 (was accidentally targeted at vnext).