OpenWikimicrosoft/vscode

Subagents

Purpose and Scope

Subagents are the VS Code agent primitive for delegating focused work from a main agent conversation to a narrower agent. The user-facing concept is an independent AI agent that researches a topic, analyzes code, reviews changes, explores alternatives, or performs another bounded task, then returns a result. In the Copilot extension implementation, that idea is represented as generated custom-agent resources with declared tools, model preferences, invocation controls, optional handoffs, and explicit delegation permissions. A subagent is therefore not just a prompt convention; it becomes a resource with behavior that the chat runtime can inspect and enforce. Sources: extensions/copilot/src/extension/agents/vscode-node/agentTypes.ts, extensions/copilot/src/extension/agents/vscode-node/exploreAgentProvider.ts

Use subagents when the main conversation benefits from isolation. Complex work often needs searches, file reads, comparisons, and parallel investigation before implementation can proceed. If every intermediate lookup is added to the main thread, the primary agent has more context to manage and the user has more noise to review. A focused helper can gather that detail, summarize it, and let the primary agent continue with a cleaner plan. The supplied sources show this pattern in both built-in local agents and organization-provided custom agents that are exposed through the same VS Code custom-agent provider shape. Sources: extensions/copilot/src/extension/agents/vscode-node/askAgentProvider.ts, extensions/copilot/src/extension/agents/vscode-node/githubOrgCustomAgentProvider.ts

Relevant Source Files

  • extensions/copilot/src/extension/agents/node/adapters/types.ts - Defines protocol adapter interfaces for request parsing, streaming text and tool-call blocks, final events, content type, and authentication header extraction.
  • extensions/copilot/src/extension/agents/vscode-node/agentTypes.ts - Defines AgentConfig, AgentHandoff, DEFAULT_READ_TOOLS, and buildAgentMarkdown, the shared contract for generating agent resources.
  • extensions/copilot/src/extension/agents/vscode-node/askAgentProvider.ts - Implements the built-in Ask custom-agent provider, including read-only behavior, settings-driven customization, cache-file generation, and local chat resources.
  • extensions/copilot/src/extension/agents/vscode-node/exploreAgentProvider.ts - Implements the built-in Explore provider, a read-only code research subagent with fallback models, non-user-invocable behavior, and cache-file generation.
  • extensions/copilot/src/extension/agents/vscode-node/githubOrgChatResourcesService.ts - Provides organization-aware cache operations for agent and instruction resources, including polling, validation, cache writes, cache clearing, and resource listing.
  • extensions/copilot/src/extension/agents/vscode-node/githubOrgCustomAgentProvider.ts - Polls GitHub organization and enterprise custom agents, stores generated agent resources, and exposes cached agents to VS Code chat.

Core Primitives

The central source-level primitive is AgentConfig. It names the agent, describes its purpose, supplies an argument hint, declares allowed tools, and can select a model or ordered model list. It also contains the fields that make subagent behavior explicit: target environment, model invocation control, user invocation visibility, permitted nested agents, handoffs, and instruction body. buildAgentMarkdown serializes those fields into frontmatter plus body text, so the runtime-facing representation is declarative rather than hidden inside provider code. This makes generated local agents and cached organization agents fit one resource model. Sources: extensions/copilot/src/extension/agents/vscode-node/agentTypes.ts

The agents field is the main boundary for delegation. When it is present, buildAgentMarkdown writes an array to the generated agent resource; when it is an empty array, the resource explicitly allows no subagents. That detail matters for safety and predictability because a provider can say whether an agent may call helpers at all. A planning agent might allow a research helper, while a read-only helper can stop further delegation. AgentHandoff models a related but different transition: a labeled move to another agent with a prompt and optional send, continuation, and model controls. Sources: extensions/copilot/src/extension/agents/vscode-node/agentTypes.ts

The shared DEFAULT_READ_TOOLS list is the clearest safety signal in the common contract. Its comment says these tools can inspect the workspace and never modify it, and the list includes search, read, web, memory, GitHub issue and pull-request readers, terminal output inspection, and test failure inspection. Built-in read-only agents rely on this list so they can answer questions and diagnose problems without editing files. For subagents, that creates a useful separation: background research can be powerful and context-aware while still remaining outside the implementation boundary. Sources: extensions/copilot/src/extension/agents/vscode-node/agentTypes.ts

Built-in Providers

Explore is the most direct built-in subagent in the supplied code. Its base configuration describes it as a fast, read-only codebase exploration and question-answering helper, recommends it over manually chaining many search and file-reading operations, and says it is safe to call in parallel. It sets userInvocable to false, which makes it primarily a helper for other agents instead of a mode users normally select directly. It also provides a fallback model priority list so the runtime can choose an available small or automatic Copilot model for search-heavy work. Sources: extensions/copilot/src/extension/agents/vscode-node/exploreAgentProvider.ts

Ask shows a related read-only conversational mode. Its configuration says it answers questions without making changes, targets VS Code, disables direct model invocation, and sets an empty agents list so it cannot delegate further. It starts from the shared read-only tool list and adds Mermaid diagram rendering. The provider also watches configuration changes for additional Ask tools and model override settings, then fires onDidChangeCustomAgents so VS Code can refresh the generated resource. That makes Ask configurable while preserving the same generated-agent contract used by Explore. Sources: extensions/copilot/src/extension/agents/vscode-node/askAgentProvider.ts

Both built-in providers follow the same execution pattern. When VS Code asks for custom agents, the provider builds a customized configuration, converts it to agent markdown, ensures a provider-specific directory exists under extension global storage, writes the generated agent file, logs the write, and returns a vscode.ChatResource scoped to local sessions. This design means built-in agents do not need static markdown files checked into the repository. It also means settings can change the agent definition while the rest of VS Code continues consuming a stable resource URI and frontmatter schema. Sources: extensions/copilot/src/extension/agents/vscode-node/askAgentProvider.ts, extensions/copilot/src/extension/agents/vscode-node/exploreAgentProvider.ts

Organization and Third-Party Agent Resources

Subagents are not limited to the built-in providers. GitHubOrgCustomAgentProvider exposes organization and enterprise custom agents through vscode.ChatCustomAgentProvider. It registers a polling callback through the organization resource service, reads the preferred organization, respects cancellation when providing agents, and returns cached agent files for that organization. During polling, it requests organization and enterprise sources, fetches an accessible repository for the organization, reads the custom-agent list, retrieves full details for each agent, and compares the result with existing cached resources. This gives teams a path for shared agent behavior without changing local provider code. Sources: extensions/copilot/src/extension/agents/vscode-node/githubOrgCustomAgentProvider.ts

GitHubOrgChatResourcesService is the storage boundary for organization-backed chat resources. Its interface covers preferred organization discovery, polling subscriptions, individual cache reads, cache writes with change detection, cache clearing, and listing cached resources as chat resources. It maps prompt resource types into separate cache subdirectories for instructions and agents, and it validates filenames by the expected extension before treating them as resources. That separation matters because organization instructions and custom agents are both file-backed, but they have different formats and runtime meanings. The service keeps those resources organized for the provider layer. Sources: extensions/copilot/src/extension/agents/vscode-node/githubOrgChatResourcesService.ts

Adapter and Streaming Boundary

The adapter types define how external agent runtimes can connect to VS Code sessions. IProtocolAdapter parses an incoming request body into VS Code-shaped messages and options, formats streamed blocks into protocol-specific events, emits initial and final stream events, reports the response content type, and extracts an authentication key or nonce from request headers. The stream block union separates text from tool calls, which is important for subagents because delegated work often mixes explanation with searches, reads, or other tool requests. This boundary lets provider SDKs and harnesses preserve their protocol details while presenting a common streaming shape to VS Code. Sources: extensions/copilot/src/extension/agents/node/adapters/types.ts

Compact Reference

  • AgentConfig: Declares generated agent metadata, tools, model selection, target, invocation controls, nested agents, handoffs, and instruction body.
  • AgentHandoff: Declares a labeled transition to another agent with prompt text and optional send, continuation, and model settings.
  • buildAgentMarkdown(config): Serializes an agent configuration into frontmatter and body content for an agent resource.
  • DEFAULT_READ_TOOLS: Shared read-only inspection tool set used by Ask, Explore, and other agents.
  • AskAgentProvider: Provides a read-only local Ask agent with settings-aware tool and model customization.
  • ExploreAgentProvider: Provides a hidden, read-only research subagent optimized for codebase exploration and parallel investigation.
  • IGitHubOrgChatResourcesService: Owns organization lookup, polling, validation, cache operations, and cached resource listing.
  • GitHubOrgCustomAgentProvider: Exposes GitHub organization and enterprise custom agents as cached VS Code chat resources.
  • IProtocolAdapter: Bridges request parsing and streamed response formatting for agent runtime protocols.

Execution Flow and Next Steps

A typical subagent flow starts when VS Code asks a registered provider for custom agents. The provider computes or retrieves an agent definition, stores or lists it as a chat resource, and the chat runtime reads the same declarative fields regardless of whether the resource came from Ask, Explore, or an organization cache. For research-heavy work, prefer Explore-style isolation: give the helper a bounded question and desired thoroughness, then let the main agent act on the returned summary. Next, read the custom agents, skills, and prompts page for authoring conventions, the Agents window page for session orchestration, and the chat tools and approvals page for permission boundaries.

Ask a question...