Getting Started: Agents¶

What is a custom agent?¶

When you open Copilot in VS Code, the default mode is the built-in Agent - a general-purpose AI that can use all tools and handle any task. That works well for most things.

A custom agent is a specialised version of that. It has a name, a persona defined in plain text, a specific set of allowed tools, and optionally a preferred model. You switch to it from the agents dropdown in the Chat panel, and from that point Copilot behaves according to its instructions.

Think of it as giving Copilot a specific job title for the session: instead of a generalist, it becomes a security reviewer, a deep-research analyst, or an AFRY PowerPoint builder. In a kitchen analogy, the agent is the Chef.

Custom agents vs. Agent mode¶

The three built-in agents¶

VS Code ships three agents out of the box, and the differences between them illustrate exactly how tool and prompt choices shape behaviour.

The prompting is different too. Agent is instructed to act and iterate until the task is done. Ask is instructed to explain and answer. Plan is instructed to decompose and reason before committing to any action. The same underlying model, three very different behaviours - just from tool restrictions and system instructions.

Custom agents follow the same principle: you define the tools and the instructions, and you get a repeatable, predictable persona.

Use plain Agent mode for general coding and exploratory tasks. Use a custom agent when you want Copilot to consistently behave in a specific way - for example, only using read-only tools, always applying a certain review checklist, or always working within a defined set of MCP servers.

The .agent.md file¶

A custom agent is defined in a single markdown file with the .agent.md extension. The YAML frontmatter defines its configuration; the file body is the instruction text Copilot prepends to every prompt when that agent is active.

---
name: Security Reviewer
description: Reviews code for security vulnerabilities. Read-only - no edits.
tools: [read, search, codebase]
---

You are a security-focused code reviewer. Your job is to identify
vulnerabilities, not to fix them. For each issue found, state the
location, the risk, and a recommended remediation approach.

Focus on: injection flaws, insecure dependencies, secrets in code,
broken access control, and cryptographic weaknesses.

Key frontmatter fields¶

The instruction body can be up to 30,000 characters.

Where to put agent files¶

Invoking an agent¶

Direct invocation - you pick the agent yourself:

1. Open the Chat panel
2. Click the agents dropdown (shows all available agents)
3. Select the agent you want
4. Chat as normal - the agent's instructions are now active

Automatic invocation - Copilot picks the agent:

If the runSubagent tool is active, Copilot can automatically select and invoke a custom agent as a subagent when it decides the task is a good fit. You can disable this for a specific agent by setting user-invocable: false and disable-model-invocation: true in its frontmatter.

Subagents¶

A subagent is an agent invoked from inside another agent - used to delegate an isolated piece of work without interrupting the main conversation.

When the main agent encounters a subtask that benefits from a clean context (a web search session, a specialised review pass, a document generation step), it calls runSubagent, passing only the relevant prompt. The subagent runs independently and returns its result. This appears in chat as a collapsible tool call.

Example - a TDD agent that delegates to three specialists:

---
name: TDD
tools: [agent, read, edit]
agents: [Red, Green, Refactor]
---

Implement features using Test-Driven Development.
Use the Red agent to write failing tests.
Use the Green agent to make them pass with minimal code.
Use the Refactor agent to clean up without breaking tests.

Here Red, Green, and Refactor are themselves .agent.md files - each knows only its part of the workflow.

Brave Copilot's research agent is a real example of this pattern. The top-level research agent orchestrates the whole process - gathering context, deciding on perspectives, and then spawning research.sub subagents in parallel (one per research perspective) to do the actual web searching and report writing. A final research.sub.review subagent analyses the assembled report for gaps. Each subagent runs with its own focused instructions and a restricted tool set.

Subagent rules¶

• Nested subagents (subagents spawning further subagents) are off by default - enable with the chat.subagents.allowInvocationsFromSubagents setting
• Maximum nesting depth is 5
• A subagent's model cannot exceed the cost tier of the parent model

When to use a custom agent vs. plain Agent mode¶

Example: Brave Copilot's research agent¶

Brave Copilot ships a research agent that shows what custom agents and subagents can do together.

What it does: You give it a topic. It searches the web from multiple angles, writes a structured research report, and then reviews its own output for gaps - all without you having to prompt each step.

How it works:

1. research (main agent) - orchestrates the session. Takes your topic, proposes research perspectives, confirms with you, then spawns subagents.
2. research.sub (subagent) - web search worker. Runs once per perspective. Uses the Foundation websearch MCP tool to search the web, extracts facts, and writes its findings into the report file.
3. research.sub.review (subagent) - quality reviewer. Reads the assembled report and flags unsubstantiated claims, missing information, and gaps.

The research.sub and research.ask agents have user-invocable: false - they never appear in the dropdown. They only exist to be called by the orchestrating agent.

Full detail on Brave Copilot - including how to install it and what agents and skills it contains - is in section 12.