Custom agents in Visual Studio and VS Code: full guide

Home » Python » Custom agents in Visual Studio and VS Code: full guide

AI-powered agents are reshaping how developers work inside Visual Studio and VS Code, moving far beyond a single generic assistant to a rich ecosystem of specialized, customizable helpers. Instead of just answering questions in a chat window, these agents can plan work, edit code across your solution, run tools, and even coordinate with cloud services or external knowledge bases to ship real features end to end.

When you combine built-in agents, local and cloud execution modes, and fully custom agent profiles defined in your repositories, you get a flexible framework that adapts to your team’s workflows rather than forcing you into a single way of working. From debugging and profiling to automated testing, modernization, documentation, and code review linked to your internal standards, custom agents in Visual Studio and VS Code give you a way to encode and scale your best practices directly into the IDE.

Preset agents in Visual Studio: specialized helpers for common workflows

Visual Studio ships with a curated set of preset agents that are deeply wired into the IDE, each focused on a specific part of the development lifecycle. These agents go far beyond a general chat model because they can tap into call stacks, diagnostics, profiler traces, project graphs and test infrastructure directly from your solution.

The Debugger agent is geared towards systematic error analysis, leveraging your runtime context instead of just parroting the error message back to you. It can inspect call stacks, local variables and diagnostic output to walk through failures step by step, often following the bug across multiple files or layers until it finds the true root cause rather than the visible symptom.

The Profiler agent is tightly connected to Visual Studio’s profiling stack so that performance advice is grounded in your actual code paths and hot spots. Instead of offering generic tuning tips, it examines profiler sessions, highlights real bottlenecks, and proposes targeted optimizations that align with your project architecture and technology stack.

The Test agent (available when a solution is loaded) focuses on generating and improving unit tests that fit your project’s frameworks and conventions. Rather than dumping boilerplate tests that your CI will immediately flag, it learns from your existing patterns and uses that context to craft realistic, maintainable tests that plug into your pipelines.

The Modernize agent (for .NET and C++ projects) is designed to guide framework and dependency upgrades across your actual solution graph. It can surface breaking changes, propose migration code, and adjust to your coding patterns so that modernization feels like an assisted refactor instead of a risky, manual rewrite.

You can access these preset agents through the agent picker in the chat panel or by using the ‘@’ syntax directly inside chat. Switching between them lets you apply a different “persona” to the same codebase – for example, moving from a debugging-focused conversation to a testing or performance-oriented one without losing context.

From preset to custom: building your own agents on top of the platform

Preset agents cover the most common workflows, but the real power comes when you define custom agents that match how your team actually works. Visual Studio and GitHub Copilot share a common foundation for agents: workspace-aware models that understand your code, can call IDE tools through prompts, and can be given a dedicated role, model and toolset.

Custom agents are defined as Markdown profiles (typically with a .agent.md suffix) stored under an agents folder in your repo or profile. In GitHub-hosted projects this usually means .github/agents/your-agent.agent.md, but at organization or enterprise level you may use a top-level agents directory without the .github/ prefix so that the same agent can be reused across many repositories.

Inside each agent profile you declare a YAML frontmatter block that specifies its identity, capabilities, tools and optional MCP configuration. Typical properties include a human-friendly name, a short description summarizing what the agent does, the list of tools it can call, optional mcp-servers entries, a preferred model, an optional target (for example vscode or github-copilot), and then the main instruction message that defines how the agent should behave.

The message section in the Markdown area under the YAML behaves like a long-form system prompt for that agent. You use it to describe tone, priorities, coding standards, review checklists, testing expectations, or any other rules you want that agent to consistently follow, up to a generous character limit (around 30,000 characters) that lets you encode fairly complex behaviors.

File naming rules are strict to keep things robust and portable. The filename (before .agent.md) must be unique and descriptive and can only contain characters such as letters (a-z, A-Z), digits (0-9), dots, hyphens and underscores, which helps avoid issues across tools and platforms.

MCP and external knowledge: connecting agents to your company’s brain

Where custom agents really start to shine is when you connect them to external knowledge sources through the Model Context Protocol (MCP). Instead of limiting an agent to what’s inside your repo, MCP lets it talk to internal documentation systems, design libraries, APIs or databases as first-class tools.

Within the agent profile you can configure mcp-servers entries so that only that agent can call specific MCP tools. For example, a design-enforcement agent might have a connection to a Figma-backed MCP server while a compliance agent might talk to a policy database; those tools won’t bleed into other agents unless you explicitly enable them.

Teams are already using these capabilities to build specialized workflows tailored to their organizations. One common pattern is a code-review agent that evaluates pull requests not only against generic best practices but also against your internal style guide or Architecture Decision Records, made available via MCP.

Another popular scenario is design system enforcement, where an agent is wired to your design assets and component libraries. That agent can call tools backed by Figma files or UI component registries to flag visual or structural drift before it ever reaches production, nudging developers back toward approved patterns.

Planning agents are also gaining traction, focusing purely on discovery and scoping work before any code is written. These agents gather requirements, ask clarifying questions, explore edge cases, and then produce structured implementation plans that you can hand off either to a human or to a more action-oriented coding agent to execute.

If you’re looking for ready-made examples, the community-maintained “awesome-copilot” repository offers a growing collection of agent configurations. You can clone them as starting points, but you still need to check that the tool names actually exist in your Visual Studio or VS Code environment, because tool identifiers differ between GitHub.com, VS Code, JetBrains IDEs and other platforms.

How autonomous agents behave across tools and environments

At a conceptual level, an “agent” is an AI assistant that can autonomously execute a coding task rather than just suggesting snippets in-line. You provide a high-level goal (“fix the failing tests”, “implement this feature”), and the agent breaks it into steps, edits files, runs commands, and iterates when something fails, often finishing with a commit or pull request.

VS Code exposes this agentic behavior in multiple ways, from interactive chat in the editor to background automation via the Copilot CLI. You can let agents run locally on your machine, in remote cloud environments, or through third-party providers like Anthropic or OpenAI, deciding in each case how much autonomy they have and which tools they may call.

All of your ongoing sessions appear in a unified sessions list inside the Chat view, regardless of where the agent is actually running. This makes it easier to keep track of multiple long-running tasks, jump between them, and maintain a coherent activity history.

Agents operate along two main dimensions: where they run (local vs cloud) and how you interact with them (fully interactive vs largely autonomous). Local agents use the VS Code agent loop to work directly in your editor with rich access to your workspace; Copilot CLI agents run in the background on your machine and can use Git worktrees; cloud agents run on GitHub’s infrastructure and integrate tightly with pull requests for collaboration.

There’s also support for “third-party” agents that rely on SDKs from providers such as Anthropic or OpenAI, and on API evolution and agentic AI. These can run locally or in your own cloud, giving you additional control over data boundaries while still benefitting from the same chat and session management patterns in VS Code.

Agents operate along two main dimensions: where they run (local vs cloud) and how you interact with them (fully interactive vs largely autonomous). Local agents use the VS Code agent loop to work directly in your editor with rich access to your workspace; Copilot CLI agents run in the background on your machine and can use Git worktrees; cloud agents run on GitHub’s infrastructure and integrate tightly with pull requests for collaboration.

Choosing the right agent role and permission level

If the agent type defines where the work runs, the agent persona defines how that work is carried out. A code-review agent is configured to comment on quality and style but not to change files, while an implementation agent is authorized to edit code, run commands, and call many tools as it sees fit.

VS Code provides three built-in agent personas as a baseline: Agent, Plan and Ask. The main Agent persona focuses on end-to-end implementation, orchestrating tools and multi-file changes; Plan creates structured, step-by-step plans without editing code; Ask answers questions about your codebase or technology topics and can suggest code blocks for you to apply manually.

You can switch between these personas at any time via the agents dropdown in the Chat view, and for more specialized flows you define custom agents with their own roles and tool sets. This makes it easy to keep, say, a conservative review agent separated from an aggressive refactoring agent, each tuned for its own purpose.

Because agents can call tools and run shell commands autonomously, VS Code adds a permission layer to control how much freedom they get in each session. Using the permissions picker, you can decide whether every tool invocation requires your explicit approval, whether only risky calls need confirmation, or whether the agent is allowed to run in an almost fully automated “autopilot” mode.

The default approvals mode usually treats read-only and obviously safe tools as pre-approved while prompting you for actions that might modify files or run commands. Bypass Approvals maximizes speed by auto-approving everything; Autopilot (currently in preview) goes further by both approving tools and auto-answering clarification prompts so the agent can work until it considers the task done.

Handing off work between agents and assigning tasks

One of the more powerful patterns with agents in VS Code is the ability to hand a session off from one agent to another. This enables workflows like using a local Plan agent to define a complex feature, then handing that plan to a Copilot CLI agent to prototype locally, and finally sending the result to a cloud agent that opens a pull request on GitHub.

When you change the agent type from the session dropdown, VS Code creates a new session that inherits the full chat history and context. The original agent’s conversation is archived for reference, while the new agent continues from the same starting point but with a different role or execution environment.

From the Copilot CLI, you can explicitly delegate work to a cloud-based agent using the /delegate command in chat. You can append further instructions to fine-tune what the recipient agent should focus on, which is useful when switching from exploratory work to production-ready changes.

Deep integration with GitHub issues and pull requests means you can assign coding tasks to agents without leaving your normal workflow. By assigning an issue to copilot or mentioning the Copilot coding agent in a comment, you can request code changes or reviews that respect the agent’s configured profile.

In IDEs that support the GitHub Pull Requests extension, you can even ask agents to implement TODO comments directly from the editor. That effectively turns scattered TODO markers into a queue of structured tasks that a coding agent can pick up, implement and push back as commits or PRs.

Creating and configuring custom agents in GitHub and IDEs

Setting up a custom agent usually starts on GitHub.com or in your IDE, where you create a new agent profile in the appropriate agents directory. On GitHub.com there’s a dedicated “agents” tab under the Copilot area that lets you spin up a template profile in a chosen repository and branch.

When you create a new agent from the GitHub agents tab, the platform generates a template file, typically named my-agent.agent.md, in the repo’s .github/agents folder. For organization- or enterprise-level agents you remove the .github/ part of the path and place the file under a top-level agents directory instead so it can be used across multiple projects.

The next step is to rename the file to something meaningful and unique, following the allowed character set. A clear filename makes it much easier for teammates to understand an agent’s purpose and select it correctly from dropdown lists later in GitHub.com or the IDE’s chat interfaces.

Once the file is in place, you edit the YAML frontmatter to configure the agent’s name, description, tools and optional model and MCP-server configuration. The description is required and should briefly state what the agent is optimized for – performance reviews, API hardening, test generation, domain-specific validation, and so on.

After committing and merging the agent profile into the default branch, the new agent appears in the agents dropdown wherever Copilot’s coding agent experience is available. That includes GitHub.com, the Copilot CLI and supported IDEs, so a single agent definition can drive consistent behavior across all those surfaces.

Working with custom agents in VS Code

VS Code makes it especially straightforward to create and tweak custom agents directly from the Chat view. At the bottom of the chat panel there’s an agents dropdown that includes an option to configure custom agents, as well as a shortcut to create a new one.

When you choose to create a new custom agent in VS Code, you decide where its profile should live: in the current workspace or in your user profile. A workspace-level agent is scoped to that project’s .github/agents folder, while a user-profile agent lives under your personal configuration and is available in all workspaces you open.

You then specify a filename for the new agent profile; this is also the default label that will appear in the agents dropdown. VS Code opens the newly created .agent.md file so you can fill in the YAML and the Markdown instructions with descriptions, tools, and any behavior prompts you need.

The editor offers a “Configure tools…” button that opens a specialized dialog listing all the tools available to agents in your environment. This includes built-in tools, MCP-provided tools, and tools coming from installed extensions; you select the ones you want and VS Code writes the corresponding entries into the agent profile for you.

To control which AI model the agent relies on, you can add a model: property in the YAML and then use autocomplete to pick from the set of supported models. That makes it easy, for example, to give a heavy-duty refactoring agent access to a more capable model while keeping a lightweight Q&A agent on a smaller, cheaper model.

Updating an existing agent is just as simple: from the agents dropdown you select “Configure custom agents…” and then pick the profile you want to modify. VS Code opens the underlying .agent.md file, and after you edit and save, the changes take effect wherever that profile is used.

Custom agents in JetBrains IDEs, Eclipse and Xcode

The same agent profile format works across several major IDEs, not just VS Code. JetBrains IDEs (like IntelliJ IDEA, WebStorm or Rider), Eclipse and Xcode all integrate with GitHub Copilot’s agents and can create and edit .agent.md files in a familiar way.

In JetBrains IDEs, you start by opening the GitHub Copilot Chat window and using the agents dropdown at the bottom to configure agents. Choosing the workspace scope creates a new profile file inside .github/agents in your project, and the IDE opens it so you can set description, tools and instructions.

A “Configure tools…” button in the JetBrains editor lets you browse available tools, including MCP-based tools, and add them to the agent with a single click. You can also specify the model property here, again driven by an autocomplete list of supported AI models.

In Eclipse the workflow is similar: you open the Copilot Chat view, use the agents dropdown to select “Configure agents…” and then create a new profile via an “Add…” action. The editor opens a fresh .agent.md file under .github/agents, where you can define description, tools, MCP servers and behavior prompts, plus adjust models and other properties as needed.

Xcode’s integration also relies on the Chat view’s agents dropdown, with a dedicated “Create an agent” option. After naming the profile, Xcode generates the .agent.md file under .github/agents and provides a “Customize agent” button in the editor that lets you pick the AI model, select tools (including MCP tools), and configure handoffs between custom agents.

Across JetBrains, Eclipse and Xcode, updating an existing profile always goes through the same pattern: open the agents configuration, select the agent, and edit the underlying Markdown file. Those edits then flow back into GitHub’s Copilot ecosystem, so the same custom agent remains consistent regardless of which IDE is being used.

Designing powerful agent profiles: identity, tools and behavior

Getting real value from custom agents depends on how well you design their profiles, starting with a clear identity and focused capabilities. A well-crafted name and description make the agent’s intent obvious and help the underlying model prioritize the right behavior.

The tools list is your main lever for controlling what an agent can actually do. You can give an agent access to every tool in your environment simply by omitting the property, or you can be very precise and only enable a subset of capabilities – for example "read", "edit", "search" and a handful of domain-specific MCP tools.

Optional mcp-servers entries let you configure extra servers that are visible only to that particular agent profile. This is handy when an agent needs privileged access to internal systems (like confidential design docs or compliance databases) but you don’t want every agent to be able to query the same resources.

When you’re using the agent in VS Code, JetBrains IDEs, Eclipse or Xcode, you can also specify a dedicated model property so that each agent can use the model that best fits its job. Some teams run heavy reasoning models for planning and architecture review agents while giving lightweight Q&A agents cheaper models to control cost.

The optional target property is useful when you want an agent to appear only in certain environments. By setting target: vscode or target: github-copilot, you can build profiles that are dedicated to IDE-based workflows or GitHub.com-based flows, while omitting the property keeps the agent available everywhere.

Finally, the body of the Markdown file holds the actual instructions or “voice” of the agent, and this is where you encode your standards and expectations. You might spell out unit-test coverage rules, technology constraints, tone guidelines for documentation, or detailed review checklists; the richer and clearer this content is, the more consistent the agent will behave across sessions.

Using custom agents across GitHub.com, CLI and IDEs

Once a custom agent is defined, you’re not limited to using it in a single place – it travels with your code wherever Copilot’s coding agent runs. On GitHub.com you can pick your custom agent from the panel or agents tab when asking Copilot to perform a task on an issue or pull request.

When assigning GitHub issues, you can choose a specific custom agent instead of the generic coding agent if the task benefits from that agent’s specialized configuration. For example, a security-focused agent profile could be assigned to review changes in an authentication module while a performance-tuning agent looks after hot paths in a backend service.

From the GitHub Copilot CLI, you can opt into a particular custom agent using a slash command like /agent or by referencing the agent in a prompt or command-line parameter. That way your terminal workflows stay aligned with the same personas you use in the browser or the IDE.

Whenever a Copilot coding agent opens a pull request on your behalf, GitHub notes which custom agent was used to complete the work. This is helpful for auditing and for understanding whether a specific agent configuration tends to produce certain styles of changes or patterns of behavior.

The same agent profiles can then be used directly inside supported IDEs via their Chat panes, so you can switch among planning, editing, research, or compliance-focused agents depending on the task at hand. Even though some YAML properties may behave slightly differently between GitHub.com and IDE contexts, the overall profile remains portable and consistent.

Local agents in VS Code: interactive sessions with full workspace context

Local agents in VS Code run on your own machine against your current workspace and give you highly interactive, low-latency conversations. They have first-class access to your files, extensions, MCP tools and the full set of models you’ve configured, including bring-your-own-key (BYOK) models.

These local sessions are perfect for tasks that require immediate back-and-forth or deep integration with your current development state. That includes brainstorming and planning, debugging stack traces, responding to linter errors, inspecting unit test results, and any workflow that involves extension-contributed tools.

Each local agent chat uses one of the built-in agents (Agent, Plan or Ask) unless you pick a custom persona, and you can pivot between them as your needs change. For instance, you might start with Ask to understand part of the codebase, then switch to Plan to design a feature, and finally move to Agent to implement it.

Starting a local Agent session is as simple as picking “Agent” from the Chat agent picker and describing a high-level goal. You can say things like “Implement a user authentication system with OAuth2 and JWT” or “Set up CI/CD for this project,” and the agent will plan work, run tools and propose edits across the solution.

As the agent works, VS Code uses editor overlays to show suggested edits and makes it easy to navigate, review and accept or reject them. You can also adjust the set of tools the agent may call via the tools picker, expanding or restricting its capabilities as you go.

The Ask persona is particularly suitable when you want knowledge and guidance without automatic file changes. Ask can deep-dive into your codebase, answer technology questions, and return code blocks that you manually apply through an “Apply in Editor” action, keeping you in full control.

Meanwhile, the Plan persona specializes in producing structured implementation plans before any code is touched. These plans can be handed off to another agent or just used as a checklist for your own work, ensuring that you’ve considered dependencies, data models and edge cases before diving into implementation.

Although an earlier “Edit mode” existed for multi-file changes, that mode has been deprecated in favor of the more capable Agent persona. You can still re-enable Edit mode via specific VS Code settings, but for most scenarios the Agent persona is the recommended path for multi-file refactors and feature work.

Throughout a session, you’re free to send follow-up prompts even while a request is running. You can queue adjustments for later, change direction mid-flight, or interrupt and steer the agent as you see fit, which makes the whole process feel less like a batch job and more like a collaborative pair-programming session.

All of these capabilities tie back into the broader agents ecosystem – you can view overviews, manage sessions, add tools, wire up MCP servers and define custom agents or hooks to enforce policies and automate lifecycle events. When you invest in good agent profiles and workflows, the same building blocks pay off across chat, CLI, IDEs and GitHub itself.

Bringing all these pieces together, custom agents in Visual Studio and VS Code turn your coding environment into a set of reusable, role-focused collaborators that understand your stack, your tools and your standards, helping teams move faster while keeping quality and consistency under control.