microsoft/hve-core
Publicmirrored fromhttps://github.com/microsoft/hve-coreAvailable
docs/customization/custom-agents.md
313lines · modecode
| 1 | --- |
| 2 | title: Creating Custom Agents |
| 3 | description: Build specialized agents with tool restrictions, subagent delegation, and mode-based workflows for your team |
| 4 | author: Microsoft |
| 5 | ms.date: 2026-02-24 |
| 6 | ms.topic: how-to |
| 7 | keywords: |
| 8 | - agents |
| 9 | - custom agents |
| 10 | - subagents |
| 11 | - copilot |
| 12 | estimated_reading_time: 7 |
| 13 | --- |
| 14 | |
| 15 | ## Agent Architecture |
| 16 | |
| 17 | Agents are specialized Copilot configurations that define behavior, available tools, and domain-specific instructions for complex workflows. In the artifact hierarchy, agents sit between prompts (single-shot tasks) and skills (knowledge packages): |
| 18 | |
| 19 | * Prompts invoke agents for one-shot execution |
| 20 | * Agents orchestrate multi-turn conversations or autonomous task execution |
| 21 | * Instructions provide scoped guidance that agents inherit automatically |
| 22 | * Skills supply domain knowledge that agents reference on demand |
| 23 | |
| 24 | An agent file (`.agent.md`) contains YAML frontmatter and a Markdown body. The frontmatter declares metadata, optional tool restrictions, subagent dependencies, and handoff configurations. The body defines the agent's protocol: its purpose, steps or phases, and response format. |
| 25 | |
| 26 | A minimal agent requires only `name` and `description` in frontmatter: |
| 27 | |
| 28 | ```yaml |
| 29 | --- |
| 30 | name: Code Review Assistant |
| 31 | description: "Reviews pull request changes for style, correctness, and security concerns - Brought to you by contoso/engineering" |
| 32 | --- |
| 33 | ``` |
| 34 | |
| 35 | More complex agents add `tools`, `agents`, `handoffs`, and `disable-model-invocation` fields. See the [Frontmatter Reference](#frontmatter-reference) section for the complete field set. |
| 36 | |
| 37 | Agent files live in `.github/agents/{collection-id}/`. Subagents go in a `subagents/` subdirectory within their collection folder: |
| 38 | |
| 39 | ```text |
| 40 | .github/agents/ |
| 41 | ├── contoso/ |
| 42 | │ ├── code-reviewer.agent.md |
| 43 | │ └── subagents/ |
| 44 | │ └── security-checker.agent.md |
| 45 | ``` |
| 46 | |
| 47 | ## Creating Your First Agent |
| 48 | |
| 49 | Walk through creating a code review agent for Contoso's engineering team using Prompt Builder. |
| 50 | |
| 51 | **Step 1:** Create the agent file at `.github/agents/contoso/code-reviewer.agent.md` with minimal frontmatter: |
| 52 | |
| 53 | ```yaml |
| 54 | --- |
| 55 | name: Contoso Code Reviewer |
| 56 | description: "Reviews code changes for Contoso's TypeScript API standards - Brought to you by contoso/engineering" |
| 57 | --- |
| 58 | ``` |
| 59 | |
| 60 | **Step 2:** Use `/prompt-build` to generate the agent body. Provide existing agents as reference context with `files` and specify the target file with `promptFiles`: |
| 61 | |
| 62 | ```text |
| 63 | /prompt-build files=.github/agents/hve-core/implementation-validator.agent.md promptFiles=.github/agents/contoso/code-reviewer.agent.md |
| 64 | ``` |
| 65 | |
| 66 | Prompt Builder analyzes the reference agents, generates the protocol body with purpose, steps, and response format, and validates the result against repository conventions. |
| 67 | |
| 68 | **Step 3:** Evaluate the generated agent with `/prompt-analyze`: |
| 69 | |
| 70 | ```text |
| 71 | /prompt-analyze promptFiles=.github/agents/contoso/code-reviewer.agent.md |
| 72 | ``` |
| 73 | |
| 74 | This produces a structured report covering purpose, capabilities, issues organized by severity, and an overall quality assessment. Address any critical or major findings before committing. |
| 75 | |
| 76 | **Step 4:** Iterate with `/prompt-build` to apply fixes identified by the analysis: |
| 77 | |
| 78 | ```text |
| 79 | /prompt-build files=.github/agents/contoso/code-reviewer.agent.md promptFiles=.github/agents/contoso/code-reviewer.agent.md |
| 80 | ``` |
| 81 | |
| 82 | When `promptFiles` points to an existing file, Prompt Builder refines it rather than starting from scratch. |
| 83 | |
| 84 | > [!TIP] |
| 85 | > Run `/prompt-analyze` first to identify quality issues, then use `/prompt-build` to apply fixes. This two-step pattern produces consistent, well-structured agents. |
| 86 | |
| 87 | **Step 5:** Invoke the agent in Copilot Chat by selecting it from the agent picker or referencing it by name. |
| 88 | |
| 89 | ### Consolidating Agents |
| 90 | |
| 91 | Use `/prompt-refactor` to merge overlapping agents or clean up related agent files: |
| 92 | |
| 93 | ```text |
| 94 | /prompt-refactor promptFiles=.github/agents/contoso/*.agent.md requirements="merge overlapping review agents into a single orchestrator" |
| 95 | ``` |
| 96 | |
| 97 | ## Subagent Patterns |
| 98 | |
| 99 | Subagents handle specialized subtasks that a parent agent delegates. The parent declares subagent dependencies in its `agents:` frontmatter using human-readable names. Orchestrator agents that only delegate work set `disable-model-invocation: true`: |
| 100 | |
| 101 | ```yaml |
| 102 | --- |
| 103 | name: Full Stack Reviewer |
| 104 | description: "Orchestrates frontend and backend code review - Brought to you by contoso/engineering" |
| 105 | disable-model-invocation: true |
| 106 | agents: |
| 107 | - Contoso Security Checker |
| 108 | - Contoso Style Validator |
| 109 | --- |
| 110 | ``` |
| 111 | |
| 112 | Agents that perform direct work alongside subagent delegation omit `disable-model-invocation` and optionally restrict their own tools: |
| 113 | |
| 114 | ```yaml |
| 115 | --- |
| 116 | name: Full Stack Reviewer |
| 117 | description: "Orchestrates frontend and backend code review - Brought to you by contoso/engineering" |
| 118 | agents: |
| 119 | - Contoso Security Checker |
| 120 | - Contoso Style Validator |
| 121 | tools: |
| 122 | - read |
| 123 | - search |
| 124 | - web |
| 125 | --- |
| 126 | ``` |
| 127 | |
| 128 | The parent references subagents using glob paths so resolution works regardless of nesting depth: |
| 129 | |
| 130 | ```markdown |
| 131 | Delegate security analysis to the security checker subagent |
| 132 | at `.github/agents/**/security-checker.agent.md`. |
| 133 | ``` |
| 134 | |
| 135 | Subagent files include `user-invocable: false` in frontmatter to prevent direct user invocation: |
| 136 | |
| 137 | ```yaml |
| 138 | --- |
| 139 | name: Contoso Security Checker |
| 140 | description: "Scans code for common security vulnerabilities - Brought to you by contoso/engineering" |
| 141 | user-invocable: false |
| 142 | tools: |
| 143 | - read_file |
| 144 | - grep_search |
| 145 | --- |
| 146 | ``` |
| 147 | |
| 148 | ### When to use subagents vs. inline logic |
| 149 | |
| 150 | * Use subagents when the subtask has its own distinct tool requirements or produces a structured output that the parent consumes. |
| 151 | * Keep logic inline when the task is a simple step within the parent's protocol and does not benefit from isolation. |
| 152 | * Subagents cannot invoke their own subagents. Only the parent agent orchestrates subagent calls. |
| 153 | |
| 154 | ## Tool Restrictions |
| 155 | |
| 156 | The `tools:` frontmatter field limits which tools an agent can access. Omitting `tools:` grants access to all available tools. Specifying a list restricts the agent to only those tools. |
| 157 | |
| 158 | ```yaml |
| 159 | tools: |
| 160 | - read_file |
| 161 | - grep_search |
| 162 | - semantic_search |
| 163 | ``` |
| 164 | |
| 165 | Tool restrictions serve two purposes: |
| 166 | |
| 167 | * Agents with read-only roles cannot modify files, run terminal commands, or access external services |
| 168 | * Restricting irrelevant tools reduces noise. A documentation agent does not need terminal access. |
| 169 | |
| 170 | > [!IMPORTANT] |
| 171 | > Agents that modify files or run commands require explicit tool grants. Read-only agents should omit tools like `run_in_terminal`, `replace_string_in_file`, and `create_file` to enforce safe operation. |
| 172 | |
| 173 | ## Mode-Based Workflows |
| 174 | |
| 175 | Agents support both conversational and autonomous modes. The mode is conveyed through protocol structure rather than a dedicated frontmatter field. |
| 176 | |
| 177 | **Conversational agents** use phase-based protocols for multi-turn interactions. Users guide the conversation through distinct stages: |
| 178 | |
| 179 | ```markdown |
| 180 | ## Phases |
| 181 | |
| 182 | ### Phase 1: Requirements Gathering |
| 183 | |
| 184 | Ask the user about project constraints, target audience, |
| 185 | and success criteria. |
| 186 | |
| 187 | ### Phase 2: Design Proposal |
| 188 | |
| 189 | Present architecture options based on gathered requirements. |
| 190 | Wait for user feedback before proceeding. |
| 191 | |
| 192 | ### Phase 3: Implementation Plan |
| 193 | |
| 194 | Generate a step-by-step plan incorporating user decisions. |
| 195 | ``` |
| 196 | |
| 197 | **Autonomous agents** use step-based protocols for bounded task execution. The agent receives instructions and completes the work with minimal interaction: |
| 198 | |
| 199 | ```markdown |
| 200 | ## Required Steps |
| 201 | |
| 202 | ### Step 1: Analyze Input |
| 203 | |
| 204 | Read the provided files and extract requirements. |
| 205 | |
| 206 | ### Step 2: Generate Output |
| 207 | |
| 208 | Create the requested artifacts based on analysis. |
| 209 | |
| 210 | ### Step 3: Validate |
| 211 | |
| 212 | Run validation commands and report results. |
| 213 | ``` |
| 214 | |
| 215 | HVE Core includes several mode-based agents you can study as patterns: task planners for research-plan-implement workflows, PR analyzers for autonomous review, and design thinking coaches for facilitated multi-turn sessions. |
| 216 | |
| 217 | ## Role Scenarios |
| 218 | |
| 219 | **Northwind Traders' architect** creates a design-review agent that evaluates proposed system changes against their microservices architecture standards. The agent reads architecture decision records, checks for service boundary violations, and produces a compatibility assessment. It restricts tools to read-only operations since it should never modify source code. |
| 220 | |
| 221 | **Woodgrove Bank's security lead** builds an authentication audit agent that scans OAuth configurations, token handling patterns, and session management code. The agent delegates credential scanning to a subagent and produces a consolidated report with severity ratings. |
| 222 | |
| 223 | **Tailspin Toys' engineering manager** authors a PR triage agent that categorizes incoming pull requests by area (frontend, backend, infrastructure), estimates review complexity, and suggests appropriate reviewers based on file ownership patterns. |
| 224 | |
| 225 | For full frontmatter schema, naming conventions, and contribution requirements, see [Contributing: Custom Agents](../contributing/custom-agents.md). |
| 226 | |
| 227 | ## Frontmatter Reference |
| 228 | |
| 229 | Agent frontmatter supports these fields: |
| 230 | |
| 231 | | Field | Type | Required | Purpose | |
| 232 | |----------------------------|---------|----------|--------------------------------------------------------------| |
| 233 | | `name` | string | Yes | Human-readable name shown in the agent picker | |
| 234 | | `description` | string | Yes | One-line purpose with attribution suffix | |
| 235 | | `tools` | array | No | Restrict available tools; omit for full access | |
| 236 | | `agents` | array | No | Human-readable names of subagent dependencies | |
| 237 | | `handoffs` | array | No | Structured transitions to other agents | |
| 238 | | `disable-model-invocation` | boolean | No | Set `true` for orchestrators that only delegate to subagents | |
| 239 | | `user-invocable` | boolean | No | Set `false` for subagents not meant for direct invocation | |
| 240 | |
| 241 | ### description |
| 242 | |
| 243 | Include attribution to identify the source organization or repository: |
| 244 | |
| 245 | ```yaml |
| 246 | description: "Reviews code for API standards - Brought to you by contoso/engineering" |
| 247 | ``` |
| 248 | |
| 249 | ### tools |
| 250 | |
| 251 | Tool values support four naming patterns: |
| 252 | |
| 253 | | Pattern | Example | |
| 254 | |-------------------|-----------------------------------------------| |
| 255 | | Individual tools | `read_file`, `grep_search`, `semantic_search` | |
| 256 | | Category | `read`, `search`, `edit`, `web`, `agent` | |
| 257 | | Category-specific | `edit/createFile`, `execute/runInTerminal` | |
| 258 | | Wildcard | `github/*`, `ado/*` | |
| 259 | |
| 260 | ### agents |
| 261 | |
| 262 | Declares subagent dependencies using their human-readable `name` values. Reference subagents in the body using glob paths so resolution works regardless of nesting depth: |
| 263 | |
| 264 | ```yaml |
| 265 | agents: |
| 266 | - Researcher Subagent |
| 267 | - Phase Implementor |
| 268 | ``` |
| 269 | |
| 270 | ```markdown |
| 271 | Delegate research to the researcher subagent |
| 272 | at `.github/agents/**/researcher-subagent.agent.md`. |
| 273 | ``` |
| 274 | |
| 275 | ### handoffs |
| 276 | |
| 277 | Defines structured transitions between agents. Each entry specifies a label (shown to the user), the target agent name, an optional prompt template, and whether to send the prompt automatically: |
| 278 | |
| 279 | ```yaml |
| 280 | handoffs: |
| 281 | - label: "Research Topic" |
| 282 | agent: "Researcher Subagent" |
| 283 | prompt: "Research the following topic" |
| 284 | send: true |
| 285 | - label: "Review Changes" |
| 286 | agent: "Implementation Validator" |
| 287 | prompt: "Validate the implementation against the plan" |
| 288 | send: true |
| 289 | ``` |
| 290 | |
| 291 | ### disable-model-invocation |
| 292 | |
| 293 | Set to `true` for orchestrator agents that coordinate subagents without performing direct work themselves: |
| 294 | |
| 295 | ```yaml |
| 296 | disable-model-invocation: true |
| 297 | agents: |
| 298 | - Researcher Subagent |
| 299 | - Phase Implementor |
| 300 | ``` |
| 301 | |
| 302 | ### user-invocable |
| 303 | |
| 304 | Set to `false` for subagents intended only for programmatic invocation by parent agents. These agents do not appear in the user-facing agent picker: |
| 305 | |
| 306 | ```yaml |
| 307 | user-invocable: false |
| 308 | ``` |
| 309 | |
| 310 | <!-- markdownlint-disable MD036 --> |
| 311 | *🤖 Crafted with precision by ✨Copilot following brilliant human instruction, |
| 312 | then carefully refined by our team of discerning human reviewers.* |
| 313 | <!-- markdownlint-enable MD036 --> |