Use subagents in Visual Studio Code

The Local harness uses the VS Code runSubagent tool. The following instructions cover tool selection, custom-agent configuration, model selection, and nested subagents for this harness.

Invoke a subagent

Try a read-only research task in a Local session:

1. Open your project, then start a session in the Chat view with the Local harness and Agent role.

2. Select Configure Tools and make sure Run Subagent (agent/runSubagent) is selected. Learn more about selecting tools.

3. Enter a prompt that explicitly requests a subagent:

   Use a subagent to find how authentication works in this codebase.
   Do not change files. Return the relevant files, the authentication flow,
   and any unanswered questions.
   

4. Follow the subagent's progress, then review the main agent's summary of its findings.

How subagents are invoked

You request delegation in natural language, and the main agent invokes the subagent tool. The main agent can also decide to delegate without an explicit request. It passes a task to the subagent, receives the result, and uses that result to continue your work.

A Local subagent doesn't inherit the main conversation history. Make the delegated task self-contained by specifying:

• Goal: the question to answer or work to complete.
• Context: relevant files, constraints, and decisions already made.
• Allowed actions: whether to research only or make changes.
• Expected result: the findings, recommendation, or changes to return.

Each Local invocation is stateless: the main agent can't send follow-up messages to the same subagent. Further work requires a new invocation with the relevant context. The built-in tools for asking clarifying questions and managing todo items are unavailable to Local subagents.

Invoke a subagent in a prompt file

For a reusable Local workflow, add the agent tool set to a prompt file's tools frontmatter. Describe the delegated task and expected result in the prompt body, using the same approach as an interactive request.

Run a custom agent as a subagent

In Local sessions, a subagent inherits the main agent's instructions and selected tools unless you specify a custom agent. A custom agent provides task-specific instructions and can override the tools and model.

For example, create .github/agents/codebase-researcher.agent.md in your workspace with this content. See Create a custom agent for other ways to create the file.

---
name: Codebase Researcher
description: Find relevant code and explain existing patterns
user-invocable: false
tools: ['read', 'search']
---
Research the requested topic without changing files.
Return relevant file paths, existing patterns, and unanswered questions.

Save the file, then request it from your main chat:

Use the Codebase Researcher subagent to explain how authentication works
in this project.

Agent names are case-sensitive. Use the exact name from the custom agent definition.

Control how a custom agent is invoked

Two frontmatter properties control how an agent is available:

• user-invocable controls visibility in the agents dropdown. Set it to false to hide a subagent-only helper such as Codebase Researcher. The default is true.
• disable-model-invocation controls whether other agents can invoke it as a subagent. The default is false.

The deprecated infer property is replaced by these two properties.

Restrict which subagents an agent can use

By default, custom agents without disable-model-invocation: true are available as subagents. To keep a coordinator focused on specific workers, set its agents frontmatter:

• agents: ['Codebase Researcher', 'Reviewer'] permits only the named agents.
• agents: ['*'], or omitting the property, permits all available agents.
• agents: [] prevents subagent use.

Include the agent tool set in the coordinator's tools property. The coordinator and worker example shows a complete workflow.

Select the model for a subagent

Local subagents select a model in this order:

1. An explicit model parameter supplied by the main agent to the runSubagent tool.
2. The selected custom agent's model property, which accepts a model name or a prioritized list of models.
3. Auto, when chat.subagents.defaultToAuto Open in VS Code Open in VS Code Insiders is enabled and the conditions for using Auto apply.
4. The model running the main conversation.

To request a model, include it in your prompt. Replace <model name> with a model available in your session:

Use a subagent with <model name> to review the error handling in this module.

Explicit and agent-configured model selections are checked against the main model's cost tier. If a selection exceeds that tier, the subagent doesn't run and reports which models are available.

Use Auto for subagents

Enable chat.subagents.defaultToAuto Open in VS Code Open in VS Code Insiders to use Auto instead of the main model when neither the tool call nor the agent specifies a model. The setting defaults to false and doesn't override an inherited custom agent's model configuration.

If Auto is unavailable, the subagent uses the main conversation's model.

Subagents of a bring your own key model continue to use that model unless you specify a different one. Auto routing through this setting is not constrained by the main model's fixed cost tier.

Nested subagents

Local subagents cannot invoke further subagents by default. For a workflow that delegates work recursively, enable chat.subagents.allowInvocationsFromSubagents Open in VS Code Open in VS Code Insiders (false by default). Nesting is limited to a maximum depth of five.

Keep recursive tasks bounded, and include a stopping condition so agents don't repeatedly delegate the same work.

Example: recursive agent

A recursive agent lists itself in its agents property. With nested subagents enabled, save this example as .github/agents/recursive-processor.agent.md to split a list of files into smaller research tasks:

---
name: Recursive Processor
description: Research independent files in small groups
tools: ['agent', 'read', 'search']
agents: ['Recursive Processor']
argument-hint: A list of files to summarize
---
Summarize the purpose of each file without changing it.
* For more than four files, split the list in half and delegate each half
  to a Recursive Processor subagent.
* For four or fewer files, or if further delegation is unavailable,
  summarize the files directly.
* Combine the results into a single summary.

Orchestration patterns

For repeatable multi-step work in a Local session, use a coordinator agent to assign focused tasks to workers and combine their results.

Coordinator and worker pattern

A feature-building coordinator can delegate research and review while making the code changes itself. This example uses three agent files: the Codebase Researcher defined earlier, a reviewer, and a coordinator.

Create .github/agents/reviewer.agent.md:

---
name: Reviewer
description: Review changes for correctness and missing tests
user-invocable: false
tools: ['read', 'search']
---
Review the supplied files and change summary without editing files.
Report correctness issues and missing test coverage with file references.

Create .github/agents/feature-builder.agent.md:

---
name: Feature Builder
description: Implement features with delegated research and review
tools: ['agent', 'edit', 'read', 'search']
agents: ['Codebase Researcher', 'Reviewer']
---
For each feature request:
1. Ask Codebase Researcher to find relevant files and existing patterns.
2. Use its findings to implement the requested change.
3. Ask Reviewer to check the changed files, passing the requirements
   and a summary of your changes.
4. Address the findings, then summarize the changes and remaining risks.

Save all three files. In a Local session, select Feature Builder from the agents dropdown and describe the feature to implement. The workers have read-only tools, while the coordinator has edit tools.

If another review is needed, the coordinator starts a new invocation and supplies the updated context. The earlier reviewer invocation doesn't retain a conversation for follow-up messages.

Multi-perspective code review

For a one-off review, assign perspectives in your prompt instead of creating more agent files:

Use two subagents to review the current changes without editing files.
Ask one to check correctness and the other to check test coverage.
Combine their findings, remove duplicates, and prioritize actionable issues.

Separate contexts can surface different issues, but don't guarantee unbiased or correct conclusions. Review the combined findings before acting on them.

Troubleshooting

For Local sessions, check these common causes:

The Copilot harness uses the Copilot SDK to manage delegation to built-in or custom subagents. Request a subagent in your prompt, or let the main agent decide when to delegate. For native agent behavior and configuration, see built-in and custom agents in Copilot.

The Claude harness manages its own subagents, with separate context and configurable instructions and tools. Request delegation in your prompt, or let the agent choose an appropriate subagent. See Claude subagents for native configuration and behavior.

The Codex harness uses provider-native subagents to run independent tasks and collect their results. Ask Codex to delegate in your prompt, and see Codex subagents for native configuration and behavior. For availability and setup, including the Experimental Agent Host integration, see Use the Codex harness.