Agents Window
Purpose and Scope
The Agents window is the agent-first counterpart to the normal VS Code editor window. Official product documentation describes it as a preview surface for orchestrating higher-level tasks across projects, where chat and the sessions list become the primary interface rather than side panels around a code editor. In repository terms, this page covers the source contracts that make that kind of surface configurable, session-aware, and connected to Copilot agent implementations. It does not replace the Chat view: both surfaces share agent sessions, settings, and keybindings, so users can move between a code-first workflow and an agent-first workflow without restarting their work.
Sources: src/vscode-dts/vscode.proposed.agentsWindowConfiguration.d.ts, src/vs/workbench/contrib/agentsVoice/browser/agentsVoiceWindowService.ts
An agent-first window needs more than a second shell around chat. It needs extension-facing configuration, window lifecycle ownership, session discovery, input and output services, and agent definitions that can be invoked safely. The repository evidence shows those layers split between VS Code workbench code and the bundled Copilot extension. The workbench side owns the auxiliary window and browser services. The Copilot side describes agent metadata, read-only tool boundaries, generated agent resources, and protocol adaptation for model traffic. Read together, these files explain how the window experience can host agents while still depending on shared VS Code platform services.
Sources: src/vs/workbench/contrib/agentsVoice/browser/agentsVoiceWindowService.ts, extensions/copilot/src/extension/agents/vscode-node/agentTypes.ts, extensions/copilot/src/extension/agents/node/adapters/types.ts
Relevant Source Files
- src/vscode-dts/vscode.proposed.agentsWindowConfiguration.d.ts — declares the proposed API marker that enables an agentsWindow property in extension configuration contribution schemas, without adding a new TypeScript runtime API surface.
- src/vs/workbench/contrib/agentsVoice/browser/agentsVoiceWindowService.ts — implements an auxiliary agent voice window service with open-state events, window references, persisted sizing behavior, and dependencies on agent sessions, voice input and playback, chat, commands, keybindings, workspace context, and theming.
- extensions/copilot/src/extension/agents/node/adapters/types.ts — defines protocol adapter interfaces for parsing incoming agent requests, formatting streaming text and tool-call responses, closing streams with usage data, choosing content types, and extracting authentication keys from request headers.
- extensions/copilot/src/extension/agents/vscode-node/agentTypes.ts — defines agent configuration, handoff metadata, default read-only tools, and the markdown generation helper used by built-in Copilot agent providers.
- extensions/copilot/src/extension/agents/vscode-node/askAgentProvider.ts — provides the built-in Ask agent as a read-only conversational mode that writes generated agent markdown into extension global storage and reacts to Ask-agent settings changes.
- extensions/copilot/src/extension/agents/vscode-node/exploreAgentProvider.ts — provides the built-in Explore agent as a read-only code research subagent with model fallback behavior and settings-driven regeneration.
Core Primitives
The first primitive is configuration visibility. The proposed declaration file is intentionally empty as a module, but its comment is important: the proposal enables an agentsWindow property in contributes.configuration schemas. That means the public-facing extension contract is not a new callable API. Instead, it is a schema capability that lets extension manifests describe configuration in a way the agents window can understand. This is a lightweight design choice: extension authors do not get a separate object model here, but they can participate in the preview surface through contribution metadata that VS Code already reads.
Sources: src/vscode-dts/vscode.proposed.agentsWindowConfiguration.d.ts
The second primitive is the auxiliary window service. The workbench implementation keeps an open-state event, an auxiliary window reference, a disposable store for window-scoped resources, an ownership broadcast channel, and a resize timeout. Those fields show the implementation concerns behind a dedicated window: the service must know whether the window is open, clean up resources when it closes, coordinate ownership across contexts, and avoid losing user sizing state. The constructor dependencies also show that the window is not isolated from the workbench; it is wired into storage, host behavior, configuration, commands, keybindings, workspace context, theme colors, chat services, agent sessions, and voice services.
Sources: src/vs/workbench/contrib/agentsVoice/browser/agentsVoiceWindowService.ts
The third primitive is the agent resource model. Copilot agents are represented by generated agent markdown, not hard-coded UI entries alone. The shared AgentConfig type contains the name, description, argument hint, tools, optional model selection, target, invocation flags, allowed subagents, handoffs, and body. The build helper emits front matter followed by the instruction body, including arrays for tools and agents and block-style entries for handoffs. This gives the Agents window and Chat surfaces a common representation for modes such as Ask and Explore while keeping the actual provider logic small and settings-driven.
Sources: extensions/copilot/src/extension/agents/vscode-node/agentTypes.ts, extensions/copilot/src/extension/agents/vscode-node/askAgentProvider.ts, extensions/copilot/src/extension/agents/vscode-node/exploreAgentProvider.ts
System-to-Code Mapping
| User-facing concept | Repository implementation | Why it matters |
|---|---|---|
| Preview agents-window configuration | src/vscode-dts/vscode.proposed.agentsWindowConfiguration.d.ts | Allows configuration contribution schemas to include agents-window metadata without introducing a TypeScript API method. |
| Dedicated auxiliary surface | src/vs/workbench/contrib/agentsVoice/browser/agentsVoiceWindowService.ts | Manages an auxiliary window, open-state notifications, storage, ownership coordination, and service wiring. |
| Shared agent sessions and chat services | src/vs/workbench/contrib/agentsVoice/browser/agentsVoiceWindowService.ts | Connects the window to agent session state, chat service behavior, title-bar status, and workspace context. |
| Agent definitions | extensions/copilot/src/extension/agents/vscode-node/agentTypes.ts | Provides the common schema for generated agent markdown, including tools, models, subagents, and handoffs. |
| Ask mode | extensions/copilot/src/extension/agents/vscode-node/askAgentProvider.ts | Supplies a read-only conversational agent for explanations and project questions. |
| Explore mode | extensions/copilot/src/extension/agents/vscode-node/exploreAgentProvider.ts | Supplies a read-only research subagent optimized for search-heavy codebase exploration. |
| Streaming protocol boundary | extensions/copilot/src/extension/agents/node/adapters/types.ts | Normalizes request parsing, streaming text, tool calls, final events, response content types, and header-based auth extraction. |
Execution Flow
A typical agent-first flow starts when the user opens the dedicated surface from VS Code, for example through the product command described in the official documentation. The workbench side is responsible for creating and owning the auxiliary window, then binding that window to the relevant services. The service imports the widget, widget binding, and sessions picker used by the agent voice surface, and its dependencies include agent sessions and chat services. That structure matches the product promise that the agent-first window is not a separate account or session universe; it is another window over shared VS Code agent state.
Sources: src/vs/workbench/contrib/agentsVoice/browser/agentsVoiceWindowService.ts
Once the surface is available, the Copilot extension can contribute agent resources. AskAgentProvider builds a customized configuration, serializes it to agent markdown, writes it under extension global storage in an ask-agent cache directory, and returns the resulting resource for local session types. It also listens for configuration changes affecting additional Ask tools and the Ask model, then fires its custom-agent change event. That change signal is important in a live agents window because settings should alter the available agent definition without requiring users to manually recreate the surface or restart the extension host.
Sources: extensions/copilot/src/extension/agents/vscode-node/askAgentProvider.ts, extensions/copilot/src/extension/agents/vscode-node/agentTypes.ts
ExploreAgentProvider follows the same provider pattern but serves a different workflow. Its base configuration identifies Explore as a read-only code research subagent, not a general editing mode. It is marked non-user-invocable, has no child agents, and uses the default read-only tools. The provider watches Explore-related model configuration and writes an Explore agent markdown file into extension global storage. The fallback model list includes smaller or automatic Copilot choices, which is consistent with a subagent intended to perform focused exploration quickly and, in some scenarios, safely in parallel with the main conversation.
Sources: extensions/copilot/src/extension/agents/vscode-node/exploreAgentProvider.ts, extensions/copilot/src/extension/agents/vscode-node/agentTypes.ts
API Components and Configuration Reference
The proposed agents-window API surface is deliberately narrow. The declaration file adds no exported functions, classes, commands, or events. Its purpose is to turn on schema support for an agentsWindow property under contributes.configuration. Developers reading this should avoid looking for a runtime method to open or control the Agents window from this file. The useful contract is manifest-level: a proposed API gate lets configuration contributions carry agents-window information while the rest of the implementation remains in workbench services and extension providers.
Sources: src/vscode-dts/vscode.proposed.agentsWindowConfiguration.d.ts
The shared agent configuration contract is more concrete. AgentConfig requires name, description, argumentHint, tools, and body, and it accepts optional model, target, disableModelInvocation, userInvocable, agents, and handoffs fields. AgentHandoff contains label, target agent, prompt, optional send behavior, optional continue-display behavior, and optional model override. DEFAULT_READ_TOOLS includes workspace and external read operations such as search, read, web, memory, GitHub issue and pull request reads, terminal-output retrieval, and test-failure inspection. That default list is the main safety boundary for read-only agents such as Ask and Explore.
Sources: extensions/copilot/src/extension/agents/vscode-node/agentTypes.ts
The protocol adapter contract describes the lower-level request and streaming boundary used by Copilot agent integrations. An adapter parses a request body into VS Code chat messages, model data, request options, and an optional type. It formats streaming responses from text blocks and tool-call blocks, can emit initial events, must generate final events, chooses a response content type, and extracts an authentication key or nonce from incoming headers. This keeps endpoint-specific protocol details outside the agent window itself, while still allowing the agent experience to consume streamed text and tool-call information consistently.
Sources: extensions/copilot/src/extension/agents/node/adapters/types.ts
Implementation Details and Edge Cases
The auxiliary window service shows several edge cases that matter for an agent-first window. It tracks open state rather than assuming a singleton is always present. It uses disposables so widget bindings, timers, and other window-scoped resources can be cleaned up when the auxiliary window closes. It imports storage keys and default dimensions, which indicates persisted size and placement are part of the experience. It also references theme colors for editor and input backgrounds and borders, so the window can visually align with the user’s selected VS Code theme rather than behaving like an unrelated browser popup.
Sources: src/vs/workbench/contrib/agentsVoice/browser/agentsVoiceWindowService.ts
The service also contains an explicit Electron boundary. A comment notes that it calls setWindowAlwaysOnTop through a registered command and avoids importing the native host service in the browser layer. That is a small but important architectural constraint: browser-layer code should remain portable across desktop and web-oriented workbench contexts, while Electron-only behavior is delegated through the command system. For an agents window, that pattern prevents convenience features from leaking native dependencies into code that is otherwise responsible for browser workbench composition, session binding, and UI lifecycle management.
Sources: src/vs/workbench/contrib/agentsVoice/browser/agentsVoiceWindowService.ts
Testing and Validation Signals
The supplied page sources do not include a dedicated agents-window smoke test, so the strongest source-backed validation signals here are structural. Proposed API support should be covered by the VS Code declaration build pipeline, while the Copilot providers should be compiled with the extension and exercised wherever custom agent resources are loaded. For manual validation, open the Agents window, confirm that shared sessions are visible, change Ask or Explore model-related settings, and verify that the provider change event causes regenerated local agent resources to be reflected in the agent picker or session flow.
Sources: src/vscode-dts/vscode.proposed.agentsWindowConfiguration.d.ts, extensions/copilot/src/extension/agents/vscode-node/askAgentProvider.ts, extensions/copilot/src/extension/agents/vscode-node/exploreAgentProvider.ts
When debugging provider behavior, start from the generated resource path rather than the UI alone. AskAgentProvider and ExploreAgentProvider both create a cache directory under the extension global storage URI, write a markdown agent file, and log a trace message after writing. If an agent does not appear, verify that the provider is being asked for local session resources, the cache directory can be created, and configuration-change listeners are firing for the relevant keys. If request streaming looks wrong, the adapter contract is the place to inspect parsing, event formatting, final usage emission, content type selection, and header authentication extraction.
Sources: extensions/copilot/src/extension/agents/vscode-node/askAgentProvider.ts, extensions/copilot/src/extension/agents/vscode-node/exploreAgentProvider.ts, extensions/copilot/src/extension/agents/node/adapters/types.ts
Related Pages and Next Steps
Read the Chat View page when you need the code-first surface that shares sessions and settings with the Agents window. Read Chat Sessions for persistence and synchronization behavior, and Chat Tools and Approvals for the tool-permission model behind autonomous work. For customization, continue to Custom Agents, Skills, and Prompts, because the same generated agent-resource model used by Ask and Explore is part of the larger agent customization story. Contributors changing this area should keep the workbench window lifecycle, proposed configuration schema, Copilot provider regeneration, and streaming protocol contracts aligned.
Sources: src/vs/workbench/contrib/agentsVoice/browser/agentsVoiceWindowService.ts, extensions/copilot/src/extension/agents/vscode-node/agentTypes.ts, extensions/copilot/src/extension/agents/node/adapters/types.ts