Text of code.visualstudio.com › docs › agents › run › subagents as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

Use subagents in Visual Studio Code

AI agents: See llms.txt for documentation discovery and navigation. Documentation articles are also available as Markdown by appending .md to the article URL. Join VS Code at Microsoft Ignite or catch the sessions online. A year of VS Code, wrapped. Explore the highlights. Use subagents in Visual Studio Code View as Markdown Ask in VS Code Ask in VS Code Insiders Use subagents to research a topic, compare approaches, or review code without filling your main conversation with intermediate work.

A subagent works in its own context and returns a focused result to the main agent. Learn more about subagent concepts . This article shows how to delegate a task and follow its progress in VS Code. Use the guidance for your harness , then learn how to follow subagent progress with the shared chat controls. When to use subagents Delegate work that has a clear scope and produces a result the main agent can use: Research before implementation : find relevant files, existing patterns, or library options, then return a recommendation.

Compare approaches : investigate independent solutions, or use different models to examine the same problem. Review changes : check separate concerns, such as correctness and performance, then combine the findings. For a quick lookup or a small edit, a direct request is usually enough. Delegation adds model usage and coordination, so consider the cost as well as the benefit of keeping intermediate work out of the main context.

Subagents by harness Your agent harness determines how subagents run and which configuration options they support. Select a harness before you submit the first prompt. Note Claude and Codex harnesses are disabled when Copilot enterprise-managed settings apply , unless your administrator explicitly permits them. Contact the IT team that deployed the settings to discuss access. Provider documentation also covers CLI workflows.

Commands and configuration options can differ in VS Code. Use the harness guide for integration-specific setup and limitations. The Copilot harness manages 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 . Copilot uses the native task tool for delegation, rather than Local's runSubagent .

When migrating a coordinator agent, review both instructions that name the tool and the agent's tool list. Do not assume the tools accept identical arguments. See the subagent migration FAQ . 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 integration-specific setup, see Use the Codex harness . Subagents in Local harness sessions The Local harness The Local harness is deprecated and will be removed in February 2027. Move your workflows to the Copilot harness before then.

Learn more about Local harness deprecation . 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 harness The Local harness is deprecated and will be removed in February 2027. Move your workflows to the Copilot harness before then. Learn more about Local harness deprecation . session: Open your project, then select the Local harness The Local harness is deprecated and will be removed in February 2027.

Move your workflows to the Copilot harness before then. Learn more about Local harness deprecation . and Agent role for a new session in the Chat view. Select Configure Tools and make sure Run Subagent ( agent/runSubagent ) is selected. Learn more about selecting tools . 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.

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 harness 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.

Note Explicitly listing an agent in agents overrides that agent's disable-model-invocation: true . Picker visibility and subagent availability are separate controls. 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: An explicit model parameter supplied by the main agent to the runSubagent tool.

The selected custom agent's model property, which accepts a model name or a prioritized list of models. Auto, when chat.subagents.defaultToAuto Open in VS Code Open in VS Code Insiders is enabled and the condit

The rest of this page is on the live site.