You've probably settled into a rhythm with GitHub Copilot by now — tab-completing suggestions, asking the chat panel questions about unfamiliar code, maybe even using agent mode for larger refactors. But every team has that thing: the naming convention nobody remembers, the architecture decision buried in a Confluence page, the review checklist that lives in someone's head. Generic AI assistance doesn't know about any of it. With Visual Studio 2026 v18.4, shipped on 24 March 2026, that changes. Custom agents let you encode your team's specific workflows, conventions, and knowledge sources into reusable AI personas that sit right inside the IDE.

This isn't a minor quality-of-life tweak. It's the difference between "an AI that writes C#" and "an AI that writes C# the way your team writes C#."

What shipped in v18.4

The headline feature is custom agents, but v18.4 also expanded the set of built-in agents and introduced several supporting capabilities worth understanding first.

Built-in agents

Visual Studio 2026 now ships four curated agents, each wired into specific IDE subsystems:

Agent What it does
@debugger Analyses call stacks, variable state, and diagnostic tools to walk through error diagnosis across your solution
@profiler Connects to Visual Studio's profiling infrastructure to identify bottlenecks and suggest targeted optimisations
@test Generates unit tests tuned to your project's framework and patterns
@modernize Handles framework and dependency upgrades for .NET and C++ with awareness of your project graph

You invoke them with the @ syntax in the Copilot Chat panel — @profiler Find the performance bottlenecks in my application — or via the agent picker dropdown.

The @modernize agent deserves special mention for .NET developers. It follows a three-stage workflow: assessment (reviewing package versions, target frameworks, and API compatibility risks), plan (generating a migration plan), and task execution (working through the migration with a dynamic task file you can edit as work progresses). If you've ever migrated a large solution from .NET 6 to .NET 10, you'll appreciate how much manual inventory work this eliminates.

The find_symbol tool

Agent mode also gained find_symbol, a language-aware symbol navigation tool. Rather than relying on text-based search, Copilot can now find all references to symbols across your projects and access metadata like type information, declarations, and scope. It supports C#, Razor, TypeScript, C++, and any LSP-enabled language.

This matters because agents can now reason about your codebase structurally. When a custom agent says "find all implementations of IOrderProcessor", it's using the same symbol resolution the IDE uses — not a regex search that matches comments and string literals.

Custom agents: the .agent.md format

Custom agents are Markdown files with YAML frontmatter, stored in your repository at .github/agents/:

your-repo/
└── .github/
    └── agents/
        └── code-reviewer.agent.md
        └── architecture-guard.agent.md

Because they live in the repo, they're versioned, reviewed in pull requests, and available to everyone who clones the project. No per-machine configuration, no extension marketplace installs.

File structure

Each agent file has two parts: frontmatter for configuration and Markdown body for instructions.

markdown 
---
name: Code Reviewer
description: Reviews PRs against our team's coding standards
model: claude-opus-4-6
tools: ["code_search", "readfile", "find_references"]
---

You are a code reviewer for our team. When reviewing changes, check for:

- Naming conventions: PascalCase for public methods, camelCase for private fields
- Error handling: all async calls must have try/catch with structured logging
- Test coverage: every public method needs at least one unit test

Flag violations clearly and suggest fixes inline.

The frontmatter properties:

Property Required Description
name No Display name in the agent picker. Falls back to the filename without extension
description Yes Brief description shown on hover
model No AI model to use. Omit to inherit from the model picker
tools No Array of tool names the agent can access. Omit to enable all available tools

// TIP

Select the Tools icon in the Copilot Chat window to see all available tool names in your version of Visual Studio. Tool names differ across GitHub Copilot platforms, so verify they work in VS specifically before committing your agent files.

What makes this different from custom instructions

You might be thinking, "I could already set custom instructions in Copilot." True — but custom instructions apply globally. Agents are scoped: you choose which agent to engage based on the task. A code review agent enforces different rules than a planning agent, and neither interferes with default Copilot behaviour when you don't invoke them.

Agents also get tool restrictions. You can limit a planning agent to code_search and readfile (it can explore but not edit), while a refactoring agent gets editfiles and runcommandinterminal too.

Building practical agents for .NET teams

Let's move beyond the template examples and build agents that address real workflow problems.

An architecture enforcement agent

Most .NET teams have layering rules — controllers shouldn't reference repositories directly, domain entities shouldn't depend on infrastructure concerns. These rules are easy to state and surprisingly hard to enforce in code review.

markdown 
---
name: Architecture Guard
description: Enforces layering and dependency rules for our Clean Architecture solution
tools: ["code_search", "readfile", "find_references"]
---

You are an architecture reviewer for a .NET solution following Clean Architecture.

## Dependency rules

- **Domain** layer: No dependencies on Application, Infrastructure, or Presentation
- **Application** layer: May depend on Domain only
- **Infrastructure** layer: May depend on Domain and Application
- **Presentation** (API/Web) layer: May depend on Application only, never Infrastructure directly

## What to check

1. Using find_references, verify that new or modified classes don't introduce prohibited dependencies
2. Check that interfaces are defined in the correct layer (abstractions in Domain or Application, implementations in Infrastructure)
3. Flag any direct `DbContext` usage outside the Infrastructure layer
4. Ensure MediatR handlers live in the Application layer, not in controllers

When you find a violation, explain which dependency rule it breaks and suggest where the code should live instead.

This agent can't run your build or execute Roslyn analysers, but it can structurally navigate the codebase using find_references and flag violations that a human reviewer might miss after staring at the twentieth file in a PR.

A performance review agent

Performance problems often hide in patterns that look correct in isolation. An agent with profiling context can catch them:

markdown 
---
name: Performance Reviewer
description: Reviews code for common .NET performance pitfalls
tools: ["code_search", "readfile", "find_references"]
---

You are a .NET performance specialist reviewing code changes. Check for:

## Allocation patterns
- LINQ chains that materialise collections unnecessarily (ToList/ToArray in intermediate steps)
- String concatenation in loops — suggest StringBuilder or string.Create
- Boxing of value types through interface dispatch
- Closure allocations in hot paths (lambdas capturing local variables)

## Async pitfalls
- Sync-over-async patterns (calling .Result or .Wait() on tasks)
- Missing ConfigureAwait(false) in library code
- Async methods that never actually await — should return Task directly
- Task.Run wrapping already-async methods

## EF Core
- N+1 query patterns (accessing navigation properties in loops without Include)
- Tracking queries used for read-only scenarios — suggest AsNoTracking
- Missing indexes suggested by query patterns

Be specific. Reference the file and method where you found each issue. Suggest the concrete fix, not just "consider optimising this."

A migration companion agent

If your team is mid-migration (say, moving from Newtonsoft.Json to System.Text.Json, or from MediatR to Wolverine), a custom agent can carry the institutional knowledge of what's been decided:

markdown 
---
name: JSON Migration
description: Assists with Newtonsoft.Json to System.Text.Json migration
tools: ["code_search", "readfile", "editfiles", "find_references"]
---

You are helping migrate this solution from Newtonsoft.Json to System.Text.Json.

## Migration rules

1. Replace JsonConvert.SerializeObject/DeserializeObject with JsonSerializer.Serialize/Deserialize
2. Replace [JsonProperty("name")] with [JsonPropertyName("name")]
3. Replace [JsonIgnore] (Newtonsoft) with [JsonIgnore] (System.Text.Json) — same attribute name, different namespace
4. Custom JsonConverters must be rewritten for System.Text.Json's Utf8JsonReader/Utf8JsonWriter API
5. Newtonsoft's default of case-insensitive deserialisation must be explicitly configured:
   `JsonSerializerOptions { PropertyNameCaseInsensitive = true }`

## What NOT to migrate yet

- Files in the ExternalIntegrations/ folder use Newtonsoft features (JObject dynamic parsing) that have no direct STJ equivalent. Skip these and flag them for manual review.
- Any converter using Newtonsoft's ReadJson with JToken.Load should be flagged, not auto-converted.

When editing files, remove the Newtonsoft using directive only after confirming no other Newtonsoft types are used in the file.

This is where custom agents shine compared to generic Copilot. The "what NOT to migrate" section encodes a team decision that no amount of AI training data would produce.

Connecting agents to external knowledge with MCP

Custom agents become significantly more powerful when paired with MCP (Model Context Protocol) servers. MCP lets an agent reach beyond the repository into external systems — internal documentation, design systems, databases, APIs.

Consider a code review agent connected to your team's ADR (Architecture Decision Record) repository:

markdown 
---
name: ADR-Aware Reviewer
description: Reviews code against our Architecture Decision Records
tools: ["code_search", "readfile", "find_references"]
---

You are a code reviewer with access to our Architecture Decision Records via MCP.

Before reviewing any change, search our ADRs for decisions relevant to the affected area
of the codebase. If a change contradicts an existing ADR, flag it and reference
the specific decision by number and title.

If no relevant ADR exists and the change introduces a new architectural pattern,
suggest that the author create an ADR before merging.

The MCP connection is configured separately in Visual Studio's settings — the agent file itself just needs to reference the tools that the MCP server exposes. This separation keeps the agent definition portable across team members who might have different MCP authentication configurations.

// NOTE

Enterprise organisations can now govern MCP server usage through GitHub allowlist policies, controlling which servers are approved per organisation. This is particularly relevant when agents connect to servers that process sensitive codebases.

Curated .NET agents from Microsoft

Before building everything from scratch, check the awesome-copilot repository maintained by GitHub. It includes two agents specifically for .NET developers:

CSharpExpert.agent.md applies modern C# conventions to Copilot's code generation. It follows current best practices whilst matching your repository's existing conventions, generates only the code needed, uses async/await with proper cancellation and exception handling, and avoids unused interfaces, methods, or parameters.

WinFormsExpert.agent.md targets Windows Forms development on .NET 8 through .NET 10. It prevents .Designer.cs corruption (a real concern when AI edits WinForms code), applies MVVM and MVP patterns with Community Toolkit data binding, handles InvokeAsync overloads correctly, and respects dark mode and high-DPI awareness.

To use them, drop the files into your .github/agents/ folder and select them from the agent picker.

// TIP

Enable Tools > Options > GitHub > Copilot > "Enable project specific .NET instructions" to have Visual Studio automatically add the appropriate agent based on your project type.

Common pitfalls

Overly broad instructions. An agent that tries to be a code reviewer, architect, performance analyst, and migration guide will be mediocre at all of them. Keep agents focused on a single workflow.

Not specifying tools. Omitting the tools array enables everything, including editfiles and runcommandinterminal. A review-only agent should be explicitly limited to read-only tools. This isn't just about safety — it helps the model stay focused.

Ignoring tool name portability. Tool names differ between VS Code, Visual Studio, and GitHub.com. An agent written with VS Code tool names (insert_edit_into_file) won't work in Visual Studio (editfiles). Always verify tool names in the target IDE.

Treating agents as documentation. An agent's instructions should be actionable directives, not reference material. "Our API uses REST conventions" is too vague. "All controller actions must return IActionResult and use [ProducesResponseType] attributes for 200, 400, and 404 status codes" gives the agent something to actually check.

Forgetting the model property. If your agent is designed for complex architectural reasoning, explicitly set a capable model. Relying on whatever the user has selected in the picker can produce inconsistent results if someone switches to a faster, less capable model.

Summary