Custom Agent trong GitHub Copilot – Tùy biến AI cho từng vai trò và tác vụ cụ thể¶

Custom Agent là gì?¶

Custom Agent (trước đây gọi là Custom Chat Mode) là tính năng cho phép bạn cấu hình AI để đảm nhận các vai trò chuyên biệt, phù hợp với từng nhiệm vụ phát triển phần mềm cụ thể. Ví dụ, bạn có thể tạo các agent cho: Security Reviewer, Planner, Solution Architect, Code Reviewer, hoặc bất kỳ vai trò chuyên môn nào khác.

Mỗi Custom Agent bao gồm: - Instructions (Hướng dẫn): Định nghĩa cách AI hoạt động và phản hồi - Tools (Công cụ): Danh sách các công cụ mà agent được phép sử dụng - Handoffs (Chuyển giao): Các hành động gợi ý để chuyển sang agent khác

Custom Agent được định nghĩa trong file Markdown với đuôi .agent.md, có thể lưu trong workspace để chia sẻ với team, hoặc trong user profile để sử dụng xuyên suốt các dự án.

Lưu ý: Custom Agent có sẵn từ VS Code phiên bản 1.106 trở lên.

Tại sao cần sử dụng Custom Agent?¶

1. Kiểm soát công cụ theo từng tác vụ¶

Mỗi tác vụ yêu cầu khả năng khác nhau. Một Planning Agent chỉ cần các công cụ read-only để nghiên cứu và phân tích, tránh vô tình thay đổi code. Trong khi đó, một Implementation Agent cần đầy đủ quyền chỉnh sửa file. Custom Agent cho phép bạn chỉ định chính xác những công cụ nào khả dụng cho từng tác vụ.

2. Hướng dẫn chuyên biệt cho từng vai trò¶

Bạn có thể cung cấp hướng dẫn chi tiết để AI hoạt động theo cách phù hợp với vai trò cụ thể: - Planning Agent: Thu thập ngữ cảnh dự án và tạo kế hoạch triển khai chi tiết - Code Review Agent: Tập trung phát hiện lỗ hổng bảo mật và đề xuất cải thiện - Documentation Agent: Viết tài liệu rõ ràng, tuân thủ quy chuẩn của team

3. Quy trình làm việc tuần tự với Handoffs¶

Tính năng Handoffs cho phép tạo các workflow tuần tự, chuyển giao từ agent này sang agent khác với ngữ cảnh phù hợp. Ví dụ: - Planning → Implementation: Tạo kế hoạch, sau đó chuyển sang agent triển khai để bắt đầu code - Implementation → Review: Hoàn thành code, chuyển sang agent review để kiểm tra chất lượng - Write Failing Tests → Write Passing Tests: Viết test case thất bại trước, sau đó chuyển sang agent triển khai để làm test pass

Cấu trúc file Custom Agent¶

File Custom Agent có đuôi .agent.md và bao gồm hai phần chính:

Header (YAML Frontmatter)¶

---
description: Mô tả ngắn về agent, hiển thị trong chat input
name: Tên agent (nếu không có, sẽ dùng tên file)
argument-hint: Gợi ý cách tương tác với agent
tools: ['tool1', 'tool2', 'serverName/*']
model: Claude Sonnet 4
target: vscode | github-copilot
handoffs:
  - label: Tên nút chuyển giao
    agent: target-agent-name
    prompt: Prompt gửi đến agent tiếp theo
    send: false
---

Thuộc tính	Mô tả
`description`	Mô tả ngắn về agent, hiển thị như placeholder trong chat input
`name`	Tên của agent. Nếu không chỉ định, sẽ dùng tên file
`argument-hint`	Gợi ý hiển thị trong chat input để hướng dẫn người dùng
`tools`	Danh sách tool hoặc tool set. Dùng `serverName/*` để include tất cả tool của một MCP server
`model`	Model AI sử dụng. Nếu không chỉ định, dùng model đang chọn trong picker
`target`	Môi trường target: `vscode` hoặc `github-copilot`
`handoffs`	Danh sách các hành động chuyển giao sang agent khác

Body (Markdown)¶

Phần body chứa hướng dẫn chi tiết cho agent, viết bằng Markdown. Đây là nơi bạn cung cấp: - Vai trò và mục tiêu của agent - Cách thức xử lý yêu cầu - Quy tắc và ràng buộc cần tuân thủ - Format output mong muốn

Bạn có thể: - Tham chiếu file khác bằng Markdown link: [instructions](./instructions.md) - Tham chiếu tool trong body: #tool:toolName

Ví dụ Custom Agent¶

Ví dụ 1: Planning Agent¶

File: .github/agents/planner.agent.md

---
description: Tạo kế hoạch triển khai cho feature mới hoặc refactor code
name: Planner
tools: ['fetch', 'githubRepo', 'search', 'usages']
model: Claude Sonnet 4
handoffs:
  - label: Bắt đầu Implementation
    agent: agent
    prompt: Triển khai kế hoạch đã nêu ở trên.
    send: false
---

# Hướng dẫn Planning

Bạn đang ở chế độ planning. Nhiệm vụ của bạn là tạo kế hoạch triển khai cho feature mới hoặc refactor code hiện có.

**QUAN TRỌNG:** KHÔNG thực hiện bất kỳ thay đổi code nào, chỉ tạo kế hoạch.

## Cấu trúc kế hoạch

Kế hoạch cần bao gồm các phần sau:

### 1. Tổng quan
- Mô tả ngắn gọn về feature hoặc tác vụ refactor
- Mục tiêu cần đạt được

### 2. Yêu cầu
- Liệt kê các yêu cầu chức năng
- Liệt kê các yêu cầu phi chức năng (performance, security, etc.)

### 3. Các bước triển khai
- Chi tiết từng bước cần thực hiện
- File nào cần tạo/sửa
- Dependencies cần thêm (nếu có)

### 4. Testing
- Các test case cần viết
- Cách kiểm tra tính năng hoạt động đúng

### 5. Rủi ro và giảm thiểu
- Các rủi ro tiềm ẩn
- Cách giảm thiểu từng rủi ro

Ví dụ 2: Security Review Agent¶

File: .github/agents/security-reviewer.agent.md

---
description: Đánh giá bảo mật cho code và đề xuất cải thiện
name: Security Reviewer
tools: ['codebase', 'search', 'usages', 'problems']
---

# Hướng dẫn Security Review

Bạn là một chuyên gia bảo mật phần mềm. Nhiệm vụ của bạn là review code và phát hiện các vấn đề bảo mật tiềm ẩn.

## Checklist đánh giá

Khi review code, hãy kiểm tra các vấn đề sau:

### Input Validation
- [ ] Tất cả input từ user được validate
- [ ] Escape đúng cách khi render HTML
- [ ] Parameterized queries cho database

### Authentication & Authorization
- [ ] Session management an toàn
- [ ] Password được hash đúng cách (bcrypt, argon2)
- [ ] Kiểm tra quyền truy cập ở mọi endpoint

### Sensitive Data
- [ ] Secrets không hardcode trong source code
- [ ] Log không chứa thông tin nhạy cảm
- [ ] HTTPS được sử dụng cho mọi API call

### Dependencies
- [ ] Không có thư viện lỗi thời với CVE đã biết
- [ ] Lock file được commit

## Format báo cáo

Với mỗi vấn đề tìm thấy, hãy báo cáo theo format:

**Vấn đề:** [Tên vấn đề]
**Mức độ nghiêm trọng:** Critical / High / Medium / Low
**Vị trí:** [File và dòng code]
**Mô tả:** [Chi tiết vấn đề]
**Đề xuất:** [Cách khắc phục]

Ví dụ 3: Test Writer Agent¶

File: .github/agents/test-writer.agent.md

---
description: Viết unit test và integration test cho code
name: Test Writer
tools: ['codebase', 'search', 'usages', 'editFiles', 'terminalCommand']
handoffs:
  - label: Chạy Tests
    agent: agent
    prompt: Chạy tất cả test vừa tạo và báo cáo kết quả.
    send: false
---

# Hướng dẫn viết Test

Bạn là một Test Engineer chuyên nghiệp. Nhiệm vụ của bạn là viết test coverage đầy đủ cho code.

## Nguyên tắc viết test

1. **Mỗi test chỉ kiểm tra một behavior duy nhất**
2. **Sử dụng naming convention rõ ràng:** `should_[expected behavior]_when_[condition]`
3. **Arrange-Act-Assert (AAA) pattern**
4. **Mock external dependencies**

## Loại test cần viết

### Unit Tests
- Test từng function/method riêng lẻ
- Mock tất cả dependencies
- Cover cả happy path và edge cases

### Integration Tests
- Test tương tác giữa các components
- Sử dụng test database nếu cần
- Verify end-to-end flow

## Test Coverage

Đảm bảo coverage tối thiểu:
- Statements: 80%
- Branches: 75%
- Functions: 80%
- Lines: 80%

Cách tạo Custom Agent¶

Bước 1: Mở Command Palette¶

Nhấn Cmd+Shift+P (macOS) hoặc Ctrl+Shift+P (Windows/Linux), gõ "Chat: New Custom Agent" và chọn lệnh này.

Bước 2: Chọn vị trí lưu trữ¶

Workspace: Lưu trong .github/agents/ của workspace hiện tại, có thể commit vào repo để chia sẻ với team
User Profile: Lưu trong profile cá nhân, sử dụng được ở mọi workspace

Bước 3: Đặt tên file¶

Nhập tên file cho agent (không cần đuôi .agent.md, VS Code sẽ tự thêm).

Bước 4: Viết nội dung¶

Điền YAML frontmatter và hướng dẫn Markdown trong body theo cấu trúc đã mô tả ở trên.

Cách khác: Tạo thủ công¶

Bạn cũng có thể tạo file .agent.md trực tiếp trong folder .github/agents/ của workspace.

Sử dụng Custom Agent¶

Mở Chat View (Cmd+Ctrl+I hoặc Ctrl+Alt+I)
Click vào Agent Picker (dropdown phía trên khung chat)
Chọn Custom Agent mong muốn từ danh sách

Tùy chỉnh danh sách Agent hiển thị¶

Chọn "Configure Custom Agents" từ dropdown
Hover vào agent và click icon con mắt để ẩn/hiện trong dropdown

Handoffs – Quy trình làm việc tuần tự¶

Handoffs cho phép tạo các workflow có hướng dẫn, chuyển giao từ agent này sang agent khác với các bước tiếp theo được gợi ý.

Cách hoạt động¶

Agent hoàn thành response
Các nút handoff xuất hiện ở cuối response
Người dùng click nút để chuyển sang agent tiếp theo với prompt đã định sẵn

Cấu hình Handoff¶

handoffs:
  - label: "Bắt đầu Implementation"
    agent: "agent"           # ID của agent đích
    prompt: "Triển khai kế hoạch ở trên."
    send: false              # false = prompt pre-fill, true = tự động gửi

Ví dụ Workflow¶

[Planning Agent] → "Bắt đầu Implementation" → [Agent Mode]
                                                    ↓
                                        "Review Code" → [Security Reviewer]

Tools trong Custom Agent¶

Các loại Tool¶

Built-in Tools: codebase, search, problems, usages, changes, terminalCommand, editFiles...
MCP Tools: Tool từ MCP servers đã cấu hình
Extension Tools: Tool từ VS Code extensions
Tool Sets: Nhóm các tool liên quan (ví dụ: #edit, #search)

Cú pháp chỉ định Tools¶

tools:
  - 'codebase'              # Built-in tool
  - 'search'                # Built-in tool
  - 'myMcpServer/*'         # Tất cả tools của MCP server
  - 'myMcpServer/toolName'  # Tool cụ thể từ MCP server

Tham chiếu Tool trong Body¶

Sử dụng cú pháp #tool:toolName để tham chiếu tool trong phần hướng dẫn:

Sử dụng #tool:codebase để tìm kiếm thông tin trong codebase.
Dùng #tool:githubRepo để tra cứu documentation của thư viện.

Thứ tự ưu tiên Tools¶

Khi sử dụng cả Prompt File và Custom Agent, thứ tự ưu tiên tools như sau:

Tools được chỉ định trong Prompt File (nếu có)
Tools từ Custom Agent được tham chiếu trong Prompt File
Tools mặc định của agent đang chọn

Prompt Files – Các prompt có thể tái sử dụng¶

Ngoài Custom Agent, bạn cũng có thể tạo Prompt Files (.prompt.md) để định nghĩa các prompt tái sử dụng cho những tác vụ phổ biến.

Khác biệt giữa Custom Agent và Prompt File¶

Đặc điểm	Custom Agent	Prompt File
Mục đích	Định nghĩa vai trò/persona cho AI	Định nghĩa prompt cho tác vụ cụ thể
Cách gọi	Chọn từ Agent Picker	Gõ `/promptName` trong chat
Phạm vi	Toàn bộ conversation	Một request duy nhất
File	`.agent.md`	`.prompt.md`
Thư mục	`.github/agents/`	`.github/prompts/`

Ví dụ Prompt File¶

File: .github/prompts/create-react-form.prompt.md

---
description: Tạo React form component với validation
name: create-react-form
agent: agent
tools: ['editFiles', 'codebase']
---

# Tạo React Form Component

Tạo một React form component với các yêu cầu sau:

## Yêu cầu
- Sử dụng React Hook Form cho form management
- Sử dụng Zod cho schema validation
- TypeScript với strict type checking
- Styling với Tailwind CSS

## Input
Form name: ${input:formName:Nhập tên form}

## Output
- File component trong `src/components/forms/`
- File schema trong `src/schemas/`
- Export trong `src/components/forms/index.ts`

Sử dụng Prompt File¶

Gõ / trong chat input để xem danh sách prompt files
Chọn prompt mong muốn
Nhập thêm thông tin nếu cần (ví dụ: /create-react-form LoginForm)

Best Practices¶

1. Giữ Instructions rõ ràng và cụ thể¶

# ❌ Không rõ ràng
Hãy viết code tốt.

# ✅ Cụ thể
Khi viết code, hãy tuân thủ:
- Đặt tên biến bằng tiếng Anh, dùng camelCase
- Mỗi function không quá 20 dòng
- Thêm JSDoc cho các public functions

2. Chỉ định đúng Tools cần thiết¶

# ❌ Quá nhiều tools không cần thiết
tools: ['*']

# ✅ Chỉ tools phù hợp với vai trò
tools: ['codebase', 'search', 'usages']  # Cho read-only agent

3. Sử dụng Handoffs cho workflow phức tạp¶

Thay vì một agent làm tất cả, hãy chia thành nhiều agent chuyên biệt với handoffs để review và approve từng bước.

4. Tận dụng Tool Sets¶

# Sử dụng tool set thay vì liệt kê từng tool
tools: ['#search', '#edit']

5. Test và iterate¶

Chạy agent với các prompt khác nhau
Quan sát response và điều chỉnh instructions
Thu thập feedback từ team

Kết hợp Custom Agent với các tính năng khác¶

Custom Agent + MCP¶

Bạn có thể sử dụng tools từ MCP servers trong Custom Agent:

---
tools:
  - 'github/*'        # Tất cả tools từ GitHub MCP server
  - 'playwright/*'    # Tools cho browser automation
  - 'context7/*'      # Documentation lookup
---

Custom Agent + Custom Instructions¶

Custom Instructions (.github/copilot-instructions.md) áp dụng cho tất cả requests, trong khi Custom Agent áp dụng khi bạn chọn agent đó. Bạn có thể kết hợp cả hai:

Custom Instructions: Quy tắc chung cho cả team (coding style, conventions)
Custom Agent: Vai trò và workflow cụ thể

Custom Agent + Prompt Files¶

Prompt Files có thể tham chiếu Custom Agent:

---
agent: planner  # Sử dụng Planning Agent
---

Chia sẻ Custom Agent với Team¶

Commit vào Repository¶

Tạo folder .github/agents/ trong repo
Thêm các file .agent.md
Commit và push

Team members khi clone repo sẽ tự động có access đến các Custom Agents này.

Sync qua Settings Sync¶

Nếu lưu trong User Profile, bạn có thể sync Custom Agents qua VS Code Settings Sync:

Bật Settings Sync trong VS Code
Chạy "Settings Sync: Configure"
Bật "Prompts and Instructions"

Kết luận¶

Custom Agent là một tính năng mạnh mẽ giúp bạn tùy biến GitHub Copilot để phù hợp với quy trình làm việc cụ thể của team. Bằng cách:

Tạo các agent chuyên biệt cho từng vai trò (Planner, Reviewer, Tester...)
Kiểm soát tools khả dụng cho từng tác vụ
Thiết lập workflow tuần tự với Handoffs
Kết hợp với MCP và Prompt Files

Bạn có thể xây dựng một hệ thống AI assistant hoàn chỉnh, hỗ trợ team trong suốt vòng đời phát triển phần mềm - từ planning, implementation, đến testing và review.

Hãy bắt đầu với một vài Custom Agent đơn giản, sau đó mở rộng dần khi nắm rõ cách chúng hoạt động. Đừng quên chia sẻ các agent hữu ích với team để cùng nhau nâng cao hiệu suất làm việc!