iTranslated by AI
Introduction to GitHub Copilot Custom Agents
Target Audience
Those who want to try running a custom agent with Copilot for now.
Introduction
- I want to create a custom agent with GitHub Copilot!
- I've heard of custom agents, but I'm not sure when to use them!
This article is for those people, introducing how to set up custom agents and their use cases.
To avoid complicating the discussion this time, we will not delve deeply into sub-agents.
How to use custom agents as sub-agents will be covered in a separate article.
What are Custom Agents?
Custom agents are a mechanism that allows you to create agents specialized for a specific purpose.
While agents in the regular "Agent Mode" are general-purpose, their lack of specialization can lead to unstable accuracy and inconsistent behavior. Custom agents address this by providing agents with a limited persona and tools, thereby enhancing their expertise and restricting their actions to improve the stability of their responses.
For example, in coding, effective uses might include:
- An agent that reviews performance (only given tools to execute and measure)
- An agent that reviews from a security perspective (only given tools to read code)
- An agent that provides legal advice (only given MCPs that return legal data)
These seem to be effective use cases.
How to Create a Custom Agent
- Click the gear icon ⚙ in the chat screen and select "Custom Agents".
- The Command Palette will open; click "+ Create New Custom Agent".
- Select ".github/agents".
- Enter the name of the agent you want to create.
- The custom agent file will open; customize it here.
Custom Prompt Configuration Items
Metadata can be defined in the hyphen-enclosed section (YAML front matter). The supported metadata items are as follows:
| Item | Required | Description |
|---|---|---|
| name | × | Agent name. Used when calling from another agent. If omitted, the file name without the .agent.md part will be used. |
| description | × | Description displayed when hovering over the agent name in the chat. Also used as a reference when calling from other agents.
|
| tools | × | Tool specification |
| target | × |
vscode/github-copilot Allows you to decide whether to use it on VS Code or GitHub (described later). If omitted, it can be used on both. |
| model | × | Model specification (ignored if target: github-copilot) |
| argument-hint | × | Placeholder in the chat field (ignored if target: github-copilot) |
| disable-model-invocation | × |
true/false If true, prevents the agent from being called as a sub-agent. (ignored if target: github-copilot) |
| user-invokable | × |
true/false If false, the agent will not be displayed in the agent list in the chat field. (ignored if target: github-copilot) |
| agents | × | List of agent names that can be called as sub-agents. (ignored if target: github-copilot) |
| handoffs | × | Displays buttons in the chat field to transition to the next agent after the current agent's response. (described later) (ignored if target: github-copilot) |
| mcp-servers | × | Defines the mcp server to be used on GitHub (ignored if target: vscode) |
About Handoffs
Handoffs is a feature that displays a "transition to next agent" button in the chat input field.
By pressing the button, you can smoothly switch to a different agent while carrying over the current conversation context. This mechanism allows you to execute multi-step development tasks (e.g., planning → implementation → review) in stages, using different agents for each step.
Handoffs configuration items
handoffs:
- label: Start Implementation # Label displayed on the button
agent: implementation # Name of the destination agent
prompt: Now implement the plan outlined above. # Additional prompt to pass to the next agent
send: false # Whether to automatically start the next agent after pressing the button
model: GPT-5.2 (copilot) # Model name
Example of how to write a custom agent
Although it's not a reference for anything practical, I created a "MyTime agent to check the current time in a specified country" for verification purposes. For handoffs verification, I also created a "MyHoliday agent to return the next public holiday in a specified country."
---
name: MyTime
description: 指定した国の現在時刻を調べて返却します
target: vscode
model: GPT-5 mini (copilot)
argument-hint: 国や都市名を指定してください
tools: ['web']
disable-model-invocation: false
user-invokable: true
agents: []
handoffs:
- label: 祝日も調べるよ
agent: MyHoliday
prompt: 指定された国の祝日を調べてください
send: false
---
あなたは指定された国や都市の現在時刻を調べて返却するエージェントです。
1. #tool:web/fetch を利用して指定された国の現在時刻を調べます
## 注意事項
- 正確な現在時刻を提供するために、信頼できる情報源を使用してください
- ユーザーにわかりやすい形式で時刻を返却してください
- 必要に応じて、タイムゾーン情報も提供してください
#tool syntax to recommend tool usage
By writing #tool:<tool_name> within a custom agent's prompt, you can prioritize the use of that tool during task execution.
#tool:web/fetch を利用して指定された国の現在時刻を調べます
Positioning of Custom Agents
Among other ways to instruct agents, such as:
- Custom instructions
- Custom prompts (custom slash commands)
- Skills
You might be wondering, "How do I differentiate custom agents from these?" To be honest, for some uses, you might not feel much difference. However, there is a difference between them in terms of instruction priority.
Custom agents fix the personality and role on an agent-by-agent basis, so their behavior is less likely to deviate even with continued conversation, and answers tend to be relatively stable. On the other hand, the regular agent mode + custom prompt tends to change perspective and tone as the conversation lengthens.
That said, this difference is not that significant, and it's perfectly fine to use custom agents when there's a clear reason, and otherwise stick with the easier-to-use custom prompts.
The article below introduces a method of using custom prompts only as an entry point to custom agents. This combined approach seems promising as well.
My Use Cases
1. Onboarding Agent for New Graduates
While I can't go into details, at our company, we face the challenge of different programming language versions being used for each service. During new graduate training, fundamental programming language concepts are taught, but since it's unclear which team they will be assigned to after training, it's undesirable for them to acquire knowledge dependent on a specific version.
Therefore, when there are version differences in how things are written, we have created and operate an agent that always provides how to write code in multiple versions when asked a question. This helps new graduates learn languages without bias toward a specific version and with an awareness of version differences.
2. Vulnerability Checking Agent
LLMs tend to provide more stable results when instructions are given in separate sessions for each specific objective rather than continuously within the same session. In fact, throughout the chatbot development process, we have repeatedly observed improved accuracy by isolating specific decisions into separate sessions.
Therefore, for highly specialized reviews, we pre-define them as dedicated agents and run them in an independent context. This reduces the variability in review perspectives and leads to more precise feedback.
For example, a custom agent specialized in vulnerability checking is an effective application:
SQL Injection Detection
## Objective
Analyze source code and report implementations that may lead to SQL injection.
## Basic Policy
1. Check if user input is used in string concatenation for SQL generation.
2. Verify if parameter binding (prepared statements) is used.
3. Check if dynamic SQL execution is performed, including within ORMs and stored procedures.
XSS Vulnerability Detection
## Objective
Analyze source code and report implementations that may lead to XSS.
## Basic Policy
1. Track data flow from Source to Sink and confirm proper escaping or validation is performed according to the output context.
2. Check for the use of unescaped output or dangerous APIs.
3. Verify if scheme validation is performed for URL attributes.
4. Confirm that CSP is configured appropriately.
3. Plan Mode
Shifting gears a bit, the Plan mode, which creates an implementation plan before actual implementation, is actually a custom agent provided by GitHub Copilot itself.
You can view its instructions at /home/<username>/.vscode-server/data/User/globalStorage/github.copilot-chat/plan-agent/Plan.agent.md.
GitHub also provides examples of a "test-specific agent" and an "implementation planning agent" for reference.
Using Custom Agents on GitHub
Finally, this section introduces that custom agents defined in .github/agents can also be executed on GitHub. To use them, the following conditions must be met:
- The
.github/agentsdirectory must be managed by Git. - Its contents must exist on the main branch (default branch).
Currently, I don't frequently give instructions or ask questions on GitHub itself, but being able to use it from the GitHub app might be convenient.
Summary
Custom agents can be thought of as a mechanism to create experts for specific tasks!
Conversely, if you have multiple roles or want general-purpose use, consider whether custom prompts, custom instructions, or even skills can address your needs.
This time, I didn't cover sub-agents, but I plan to introduce them later (they are quite important).
Discussion