Custom agent trong VS Code

Custom agent gộp chỉ dẫn, tool và (tuỳ chọn) model thành một cấu hình dùng lại được cho một vai trò cụ thể như lập kế hoạch hay review code. Bài này tóm tắt cách tạo, dùng, quản lý custom agent, cấu hình file của nó và nối các agent bằng handoff.

Custom agent là gì và khi nào dùng

Các vai trò agent có sẵn là cấu hình đa dụng. Custom agent là cấu hình theo vai trò của riêng bạn, viết trong file Markdown .agent.md. Lưu trong workspace để chia sẻ với người đóng góp, hoặc ở mức user để dùng cho mọi workspace. Một định nghĩa agent dùng được với nhiều harness; tool và cách quản lý có sẵn tuỳ harness được chọn.

Dùng custom agent khi một tác vụ lặp lại cần chỉ dẫn và bộ tool riêng, ví dụ:

• Agent lập kế hoạch chỉ có tool đọc để nghiên cứu trước khi hiện thực (implement).
• Agent review code mang tiêu chí review của nhóm.
• Agent hiện thực có tool sửa file và chỉ dẫn bám theo khuôn mẫu sẵn có của dự án.

Sub-agent cũng có thể chạy bằng custom agent, xem subagents with custom agents.

Tạo custom agent

Chọn harness bằng control Session Target, rồi mở Agent Customizations editor (Preview):

• Agents window: chọn Agents trong panel Customizations ở sidebar trái.
• Chat view: chọn Configure Chat (biểu tượng bánh răng), rồi Agents.

Tạo thủ công:

1. Chọn New Agent (Workspace) hoặc New Agent (User) trong dropdown, hoặc chạy lệnh Chat: New Custom Agent từ Command Palette.
2. Chọn vị trí và đặt tên file; tên này là tên mặc định trong dropdown agent.
3. Điền frontmatter YAML (tên, mô tả, tool…) và viết chỉ dẫn trong phần thân, rồi lưu.

Trong Chat view, khi chọn Copilot, gõ /agents để mở thẳng mục Agents của editor. Khi chọn Local, /agents mở bộ chọn agent, trong đó có Configure Custom Agents.

Sinh custom agent bằng AI

Từ trang Overview của editor: nhập prompt mô tả vai trò và phạm vi (workspace hay mọi workspace), trả lời câu hỏi làm rõ, rồi rà soát file .agent.md sinh ra (tool, chỉ dẫn, frontmatter) trước khi lưu. Ví dụ:

Create a workspace custom agent for code reviews. Review changes for correctness, maintainability, and consistency with this repository's conventions. Report findings without editing files.

Bạn cũng có thể rút agent từ một hội thoại đang diễn ra, ví dụ sau một phiên debug nhiều lượt, hỏi "make an agent for this kind of task". Với Local còn có /create-agent trong chat chế độ Agent và Generate Agent trong mục Agents của editor; hai lối tắt này không có trong session Agent Host như Copilot.

Dùng custom agent

1. Chọn harness trong Session Target ở Chat view hoặc Agents window.
2. Mở dropdown Agent và chọn custom agent.
3. Nhập prompt theo vai trò của nó.
4. Xem phản hồi (response) và các lời gọi tool để chắc agent theo đúng chỉ dẫn và dùng tool phù hợp.

Nếu agent không xuất hiện, kiểm tra file nằm đúng vị trí được hỗ trợ và cấu hình hiển thị cho phép người dùng gọi.

Muốn agent chỉ dùng làm sub-agent mà không hiện trong dropdown, đặt trong frontmatter:

user-invocable: false

Thuộc tính này áp cho cả Local và Copilot; việc gọi làm sub-agent được điều khiển riêng bằng disable-model-invocation. Đây là thay đổi định nghĩa agent, nên nếu file được chia sẻ trong repo thì áp cho mọi người.

Vị trí file

Setting chat.agentFilesLocations và chat.modeFilesLocations đã deprecated và chỉ Local agent dùng; nếu đã cấu hình chúng, hãy chuyển sang vị trí được hỗ trợ. Trong monorepo, bật chat.useCustomizationsInParentRepositories để tìm custom agent từ gốc repo cha.

Cấu trúc file .agent.md

File gồm header YAML (tuỳ chọn) và phần thân Markdown. VS Code coi mọi file .md trong .github/agents là custom agent. Các trường header chính:

Tool không khả dụng sẽ bị bỏ qua.

Phần thân chứa chỉ dẫn: nhiệm vụ, nguyên tắc, output mong đợi. Tham chiếu file khác bằng link Markdown hoặc cú pháp #file: (đường dẫn tương đối tính từ file agent; ~/ là thư mục home, ví dụ #file:~/copilot/security-guidelines.md; nên dùng dấu /). Tham chiếu tool bằng #tool:<tool-name>, ví dụ #tool:web/fetch. Khi chọn agent trong Chat view, nội dung thân được đặt trước prompt của người dùng.

Ví dụ: agent lập kế hoạch

---
description: Generate an implementation plan for new features or refactoring existing code.
name: Planner
tools: ['web/fetch', 'search/codebase', 'search/usages']
model: ['Claude Opus 4.5', 'GPT-5.2']  # Tries models in order
handoffs:
  - label: Implement Plan
    agent: agent
    prompt: Implement the plan outlined above.
    send: false
---
# Planning instructions
You are in planning mode. Your task is to generate an implementation plan for a new feature or for refactoring existing code.
Don't make any code edits, just generate a plan.

The plan consists of a Markdown document that describes the implementation plan, including the following sections:

* Overview: A brief description of the feature or refactoring task.
* Requirements: A list of requirements for the feature or refactoring task.
* Implementation Steps: A detailed list of steps to implement the feature or refactoring task.
* Testing: A list of tests that need to be implemented to verify the feature or refactoring task.

Thêm ví dụ từ cộng đồng ở Awesome Copilot.

Ví dụ: điều phối sub-agent

Agent chính dùng agents để giới hạn sub-agent được gọi:

---
name: Feature Builder
description: Build features by researching first, then implementing
tools: ['agent']
agents: ['Researcher', 'Implementer']
---
You are a feature builder. For each task:
1. Use the Researcher agent to gather context and find relevant patterns in the codebase
2. Use the Implementer agent to make the actual code changes based on research findings

Researcher chỉ có tool đọc (search/codebase, web/fetch, search/usages) và trả về bản tóm tắt; Implementer có edit và read/terminalLastCommand, sửa tối thiểu theo khuôn mẫu sẵn có. Nguồn còn có ví dụ agent khai báo hook PostToolUse trong frontmatter để format code sau mỗi lời gọi tool thành công (xem Agent hooks).

Định dạng agent của Claude

File trong .claude/agents là .md thường theo định dạng Claude sub-agents, với các trường name (bắt buộc), description, tools và disallowedTools (chuỗi phân cách bằng dấu phẩy, ví dụ "Read, Grep, Glob, Bash"). VS Code ánh xạ tên tool của Claude sang tool tương ứng, và hỗ trợ cả hai định dạng.

Handoff

Handoff nối các agent thành quy trình (workflow) có gợi ý bước tiếp theo: sau khi phản hồi xong, nút handoff cho bạn chuyển sang agent khác kèm ngữ cảnh (context) hội thoại và prompt điền sẵn. Ví dụ: lập kế hoạch sang hiện thực, hiện thực sang review, test đang fail sang agent sửa cho pass.

---
description: Generate an implementation plan
tools: ['search', 'web']
handoffs:
  - label: Start Implementation
    agent: implementation
    prompt: Now implement the plan outlined above.
    send: false
    model: GPT-5.2 (copilot)
---

Với send: true, prompt được gửi tự động.

Thứ tự ưu tiên tool, chia sẻ và bảo mật

• Với Local, khi cả custom agent và prompt file khai báo tools, tool của prompt file được ưu tiên. Session Agent Host không nạp prompt file. Xem Tool list priority.
• Chia sẻ cho nhóm bằng agent mức workspace (.github/agents), hoặc cho cả tổ chức bằng agent mức GitHub organization. Bật github.copilot.chat.organizationCustomAgents.enabled để VS Code tìm các agent đó. Xem hướng dẫn của GitHub.
• Custom agent giới hạn được tool, nên với quy trình nhạy cảm, dùng agent chỉ có tool đọc. Khi chia sẻ trong repo, rà soát tool và chỉ dẫn theo nguyên tắc quyền tối thiểu.

Câu hỏi thường gặp

• Custom agent khác chat mode không? Custom agent trước đây gọi là custom chat mode; chức năng giữ nguyên. Đổi tên file .chatmode.md thành .agent.md và đặt vào vị trí được hỗ trợ.
• Xoá custom agent thế nào? Xoá file, hoặc chọn Configure Custom Agents, rê chuột lên agent và chọn biểu tượng thùng rác. Xoá agent workspace dùng chung cũng xoá với người khác khi họ nhận thay đổi. Agent do extension cung cấp chỉ gỡ được bằng cách tắt hoặc gỡ extension.
• Agent đến từ đâu? Chọn Configure Custom Agents và rê chuột lên agent để xem nguồn. Chuột phải trong Chat view, chọn Diagnostics để xem mọi customization đã nạp cùng lỗi.

Tài liệu liên quan

• Planning with agents
• Customize AI with custom instructions
• Use tools with agents

Nguồn

• Tóm tắt từ https://raw.githubusercontent.com/microsoft/vscode-docs/main/docs/agent-customization/custom-agents.md, giấy phép CC-BY-3.0-US.