Chế độ tác nhân (agent mode) của GitHub Copilot là một vòng lặp: nó chỉnh sửa tệp, chạy các lệnh terminal, đọc đầu ra và quyết định hành động tiếp theo. Vậy tại sao các bài kiểm tra API của bạn lại không nằm trong vòng lặp đó? Chúng nằm trong Apidog phía sau giao diện người dùng đồ họa (GUI), chỉ chạy khi ai đó nhớ nhấp chuột. Copilot không bao giờ chạm đến chúng.
Giải pháp chỉ là một tệp cấu hình. Apidog CLI là một gói npm, apidog-cli, chạy các kịch bản kiểm thử bạn đã xây dựng trong Apidog trực tiếp từ terminal. Sau khi CLI được cài đặt và Copilot biết nó tồn tại, chế độ tác nhân sẽ chạy một kịch bản Apidog theo cách tương tự như nó chạy các bài kiểm thử đơn vị của bạn: thực thi lệnh, đọc mã thoát (exit code), sửa mã nếu nó báo lỗi (màu đỏ).
Nếu bạn chưa cài đặt CLI, hãy làm điều đó trước tiên. Bài viết Cách cài đặt Apidog CLI với tác nhân mã hóa AI hướng dẫn từng bước cài đặt npm, đăng nhập và chạy lần đầu tiên, với tác nhân thực hiện việc nhập liệu. Bài viết này giả định rằng apidog --version in ra một số và tài khoản Apidog của bạn đã được xác thực.
Bài viết này nói về Copilot nào
Copilot là một số sản phẩm và tên của chúng chồng chéo một cách khó hiểu. Bài viết này nói về các giao diện có thể chạy lệnh shell.
Cái chính là chế độ tác nhân (agent mode) trong VS Code. Bạn mở chế độ xem Copilot Chat, chuyển menu thả xuống chế độ sang Agent, và nó có thể chỉnh sửa nhiều tệp, chạy lệnh terminal và lặp lại cho đến khi tác vụ hoàn thành. Khi nó muốn chạy một lệnh, nó sẽ hiển thị lệnh đó cho bạn và yêu cầu xác nhận trước khi thực thi. Bước xác nhận đó chính là nơi apidog run phù hợp.
Hai giao diện liên quan đáng được đề cập để bạn biết mình đang sử dụng cái nào. **Tác nhân mã hóa Copilot (Copilot coding agent)** chạy bất đồng bộ trong GitHub Actions sau khi bạn gán cho nó một vấn đề; nó tạo ra một pull request thay vì làm việc trong trình soạn thảo của bạn. **Copilot CLI** là một ứng dụng khách terminal riêng biệt. Cả hai đều có thể chạy lệnh, nhưng bài viết này tập trung vào chế độ tác nhân trong VS Code, vì đó là nơi bạn làm việc khi viết mã và nơi vòng lặp chỉnh sửa-kiểm tra-sửa lỗi (edit-test-fix) diễn ra chặt chẽ nhất. Thiết lập bên dưới cũng hoạt động cho tác nhân mã hóa, vốn đọc cùng một tệp hướng dẫn. Để có cái nhìn tổng quan rộng hơn về những gì đã thay đổi khi Copilot trở thành tác nhân, hãy xem tác nhân mã hóa mới của GitHub Copilot.
Sự khác biệt này quan trọng bởi vì Copilot có cách riêng để học các quy tắc dự án, và cơ chế đó biến một lệnh “chạy kiểm thử của tôi” một lần thành một thứ mà Copilot tự động thực hiện. Cơ chế đó là một tệp hướng dẫn tùy chỉnh.
Bước 1: Thêm các quy tắc Apidog vào tệp hướng dẫn của Copilot
Copilot đọc các hướng dẫn tùy chỉnh của kho lưu trữ từ một tệp duy nhất: .github/copilot-instructions.md tại thư mục gốc của repo của bạn. Chế độ tác nhân, Copilot Chat, đánh giá mã và tác nhân mã hóa đều tự động tải nó, theo tài liệu GitHub về hướng dẫn tùy chỉnh kho lưu trữ. Hãy nghĩ về nó như CLAUDE.md cho Claude Code hoặc AGENTS.md cho Codex: một tệp Markdown thuần túy chứa các hướng dẫn dự án mà Copilot đưa vào ngữ cảnh trước khi bắt đầu làm việc.
Tạo tệp và thêm một khối Apidog ngắn:
## Kiểm thử API với Apidog CLI
Khi bạn thay đổi một điểm cuối API, hãy xác minh nó bằng Apidog CLI trước khi
tuyên bố tác vụ hoàn thành. Chạy:
apidog run -t 812345 -e 671234 -r cli
- `apidog run` thoát với mã 0 khi mọi xác nhận (assertion) đều thành công, và khác 0 khi có bất kỳ lỗi nào.
Coi mã thoát khác 0 là một kiểm thử thất bại, ngay cả khi văn bản tóm tắt trông ổn.
- Máy đã được xác thực qua `apidog login`. KHÔNG thêm cờ `--access-token` và không bao giờ đặt mã thông báo (token) vào tệp này.
- Nếu bạn gặp lỗi "unknown option" (tùy chọn không xác định), hãy chạy `apidog run --help` và sử dụng các cờ thực. Đừng đoán.
Thay thế các giá trị -t và -e bằng ID kịch bản và môi trường thực của bạn từ bước tiếp theo.
Hãy viết nó vào tệp hướng dẫn thay vì đề cập trong chat vì ID kịch bản được nhập vào chat sẽ biến mất khi phiên kết thúc. Một ID trong .github/copilot-instructions.md sẽ tồn tại cho mọi đồng đội, mọi phiên chế độ tác nhân và mọi pull request mà tác nhân mã hóa mở từ nay về sau. Nếu bạn muốn quy tắc chỉ áp dụng cho một số tệp nhất định, GitHub cũng hỗ trợ các hướng dẫn cụ thể theo đường dẫn trong .github/instructions/NAME.instructions.md, nhưng một tệp duy nhất cho toàn bộ repo là đủ ở đây.
Bước 2: Lấy lệnh từ Apidog
Bạn không cần phải viết lệnh apidog run bằng tay. Apidog sẽ tạo ra nó cho bạn.
Mở kịch bản kiểm thử trong Apidog, đi đến tab CI/CD của nó, và sao chép lệnh. Lệnh này được tạo ra hoàn chỉnh với ID kịch bản (-t), ID môi trường (-e) chính xác và một cờ báo cáo viên (reporter flag):
apidog run -t 812345 -e 671234 -r cli
Dán chính xác các ID đó vào khối trong tệp .github/copilot-instructions.md của bạn. Các ID này là nguồn chân lý; khi Copilot và tệp hướng dẫn của bạn không khớp, tab CI/CD sẽ thắng. Để biết toàn bộ các cờ và báo cáo viên, hãy xem tài liệu tham khảo lệnh apidog run.
Bước 3: Yêu cầu chế độ tác nhân chạy kiểm thử
Mở chế độ xem Copilot Chat trong VS Code và chuyển menu thả xuống chế độ sang Agent. Vì chế độ tác nhân tải .github/copilot-instructions.md khi khởi động, nó đã biết CLI có mặt ở đó. Thực hiện một thay đổi liên quan đến API của bạn, hoặc hỏi trực tiếp:
Chạy kịch bản kiểm thử API của Apidog và cho tôi biết kết quả.
Copilot phát lệnh apidog run từ tệp hướng dẫn của bạn. Chế độ tác nhân không chạy các lệnh terminal một cách âm thầm; nó hiển thị cho bạn lệnh và yêu cầu bạn xác nhận trước khi thực thi, để bạn thấy chính xác những gì sắp chạy. Hãy chấp thuận nó. Báo cáo viên -r cli sau đó sẽ in ra kết quả từng bước và một bản tóm tắt ngay trong terminal tích hợp, nơi bạn theo dõi từng yêu cầu và xác nhận khi chúng diễn ra.
Bạn muốn thấy hai điều: quá trình chạy đang thực thi và Copilot báo cáo lại cả tóm tắt và mã thoát. Nếu bạn chấp thuận lệnh một lần, VS Code có thể ghi nhớ lựa chọn của bạn cho lệnh đó trong không gian làm việc, do đó các lệnh apidog run sau này sẽ thực thi mà không cần nhắc lại. Một kịch bản kiểm thử chỉ đọc chống lại môi trường staging chính xác là loại lệnh an toàn, trong không gian làm việc mà bạn có thể cho phép.
Bước 4: Đọc báo cáo bên trong Copilot
Khi một lần chạy báo lỗi (màu đỏ), báo cáo sẽ có câu trả lời. Với -r cli, Copilot nhận được một bản phân tích dễ đọc trong terminal: mỗi yêu cầu, mỗi xác nhận và cái nào đã thất bại với giá trị mong đợi so với giá trị thực tế. Xác nhận thất bại nêu tên trường hoặc mã trạng thái chính xác, điều này thường đủ để Copilot tìm ra bản sửa lỗi trong lần lặp tiếp theo.
Để có một báo cáo mà bạn có thể mở trong trình duyệt hoặc đưa cho đồng đội, hãy thêm báo cáo viên HTML:
apidog run -t 812345 -e 671234 -r cli,html
Báo cáo viên html ghi một tệp độc lập vào ./apidog-reports. Giữ cli trong danh sách để Copilot vẫn nhận được đầu ra nội tuyến mà nó đọc để quyết định bước tiếp theo. Để biết mọi định dạng báo cáo, bao gồm cả đầu ra JUnit mà bảng điều khiển CI phân tích, hãy xem hướng dẫn Apidog CLI đầy đủ và cách đọc báo cáo kiểm thử Apidog CLI.
Copilot kiểm thử trong vòng lặp riêng của nó
Điểm mấu chốt là điều gì xảy ra khi bạn ngừng yêu cầu và Copilot tự chạy kịch bản vì tệp hướng dẫn đã yêu cầu nó làm vậy.
Hãy hình dung chế độ tác nhân chỉnh sửa một handler xây dựng phản hồi thanh toán. Vòng lặp của nó thay đổi. Nó chỉnh sửa mã, sau đó, thay vì tuyên bố thành công, nó chạy kịch bản Apidog của bạn chống lại môi trường staging, đọc mã thoát và hành động theo đó. Xanh, nó tiếp tục. Đỏ, nó mở báo cáo, đọc xem xác nhận nào đã thất bại (mã trạng thái, trường bị thiếu, giá trị sai), thử sửa lỗi và chạy lại. Kiểm thử API trở thành một phần của cùng một vòng lặp chỉnh sửa-kiểm tra-sửa lỗi mà Copilot đã chạy các kiểm thử đơn vị của bạn. Bạn đã viết một hướng dẫn và Copilot đã tích hợp lệnh đó vào cách nó hoạt động.
Đây là mô hình ủy quyền-sau-đó-xác minh (delegate-then-verify) giúp mọi quy trình làm việc của tác nhân trở nên an toàn. Copilot chạy lệnh và đọc kết quả; bạn tiếp tục tạo kịch bản một cách trực quan trong Apidog và kiểm tra ngẫu nhiên xem tác nhân có đọc mã thoát một cách trung thực hay không. Để biết mẫu rộng hơn, hãy xem cách sử dụng tác nhân AI để kiểm thử API và công cụ kiểm thử AI của Apidog.
Xác minh Copilot thực sự đang chạy CLI
Các tác nhân báo cáo thành công mà họ không thực sự đạt được, và Copilot cũng không ngoại lệ. Ba kiểm tra, theo thứ tự tần suất chúng phát hiện vấn đề.
Đầu tiên, xác nhận lệnh đã chạy. Chế độ tác nhân hiển thị các lệnh nó đã thực thi và đầu ra của chúng trực tiếp trong terminal. Tìm dòng apidog run ... và kết quả bên dưới nó. Nếu Copilot nói rằng nó đã chạy các kiểm thử nhưng bạn không thấy lệnh, điều đó có nghĩa là nó đã tóm tắt một cái gì đó mà nó chưa bao giờ làm. Yêu cầu nó chạy lại và hiển thị đầu ra thô.
Thứ hai, xác nhận mã thoát, cái quan trọng nhất:
Mã thoát của lệnh apidog run đó là gì?
apidog run thoát với 0 khi mọi xác nhận thành công và khác 0 khi có bất kỳ lỗi nào. Hành vi đơn giản đó cho phép Copilot, hoặc một pipeline, coi lần chạy là một cổng sạch. Khi văn xuôi của Copilot nói “kiểm thử đã vượt qua” nhưng mã thoát khác 0, mã thoát mới là đúng.
Thứ ba, xác nhận nó đã sử dụng kịch bản thực. Nếu một lần chạy thất bại với thông báo “scenario not found” (không tìm thấy kịch bản), Copilot có thể đã tự tạo hoặc nhớ sai ID. Kiểm tra lại các giá trị -t và -e so với tệp hướng dẫn của bạn và lệnh Apidog đã tạo trong tab CI/CD. Các ID từ Apidog là chân lý.
Tùy chọn: kết nối máy chủ Apidog MCP
Chạy apidog run từ tệp hướng dẫn của bạn bao gồm hầu hết những gì bạn cần. Để tiến thêm một bước, hãy kết nối máy chủ Apidog MCP.
Chế độ tác nhân trong VS Code đọc các máy chủ MCP từ tệp .vscode/mcp.json trong không gian làm việc tại thư mục gốc của repo của bạn, theo tài liệu GitHub về việc mở rộng Copilot với MCP. Máy chủ Apidog MCP hiển thị các đặc tả API của bạn qua MCP, vì vậy Copilot có thể đọc schema của bạn trong khi viết mã, chứ không chỉ sau khi thực tế. Sự phân chia công việc rõ ràng: CLI chạy các kiểm thử, và MCP cung cấp spec cho tác nhân.
Nếu bạn chạy tác nhân mã hóa Copilot trong GitHub Actions thay vì trong trình soạn thảo, cấu hình MCP của nó nằm ở một vị trí khác. Bạn thêm nó dưới dạng JSON trong Cài đặt của kho lưu trữ, trong phần Copilot dưới Cloud agent, với bất kỳ bí mật nào được lưu trữ dưới dạng Actions secrets có tiền tố COPILOT_MCP_. Tệp .vscode/mcp.json dành cho chế độ tác nhân trong trình soạn thảo của bạn.
Khi Copilot làm sai
Một vài lỗi thường xuất hiện trong quá trình thiết lập.
Nó bỏ qua tệp hướng dẫn. Nếu Copilot chạy một lệnh chung chung hoặc không chạy lệnh nào, tệp có thể không được tải. Xác nhận rằng nó được đặt tên chính xác là .github/copilot-instructions.md, nằm trong thư mục .github tại thư mục gốc của repo của bạn và các hướng dẫn tùy chỉnh được bật trong cài đặt VS Code của bạn. Một đường dẫn sai có nghĩa là Copilot không bao giờ đọc nó.
Nó vẫn truyền một mã truy cập (access token). Nếu Copilot cố gắng thêm --access-token, nó đang đoán từ các ví dụ công khai. Khối hướng dẫn đã nói rõ không nên làm vậy, vì máy đã được xác thực qua apidog login. Hãy củng cố dòng đó, và không bao giờ đặt mã thông báo thật vào tệp hướng dẫn. Để biết mô hình xác thực, hãy xem xác thực Apidog CLI.
Nó tự tạo ra một cờ (flag). Lỗi “unknown option” (tùy chọn không xác định) có nghĩa là Copilot đã đoán một cờ mà phiên bản của bạn không có. Hãy yêu cầu nó chạy apidog run --help và sao chép chính xác cờ từ đó, điều này luôn đúng với phiên bản đã cài đặt của bạn.
Nó báo cáo thành công cho một lần chạy thất bại. Đây là lỗi tốn kém nhất, và là lý do tại sao quy tắc mã thoát có mặt cả trong tệp hướng dẫn của bạn và bước xác minh của bạn. Khi tóm tắt và mã thoát không khớp, mã thoát sẽ thắng.
Từ một tác nhân hàng ngày đến một vòng lặp được kiểm thử
Đó là cách thiết lập. Cài đặt apidog-cli một lần theo hướng dẫn cài đặt, thêm một khối Apidog ngắn vào tệp .github/copilot-instructions.md của repo của bạn, và Copilot sẽ biết cách chạy các kiểm thử API của bạn và đọc kết quả trong cùng một vòng lặp mà nó đã sử dụng để chỉnh sửa mã. Một điểm cuối bị hỏng sẽ được phát hiện khi Copilot vẫn đang làm việc trên thay đổi, chứ không phải sau khi nó đã triển khai.
Một kiểm thử phía sau GUI chạy khi một người nhấp chuột; một lệnh một dòng chạy bất cứ khi nào Copilot quyết định. Bạn tiếp tục xây dựng các kịch bản một cách trực quan trong Apidog, và tác nhân của bạn sẽ chạy chúng ở nơi bạn không quan sát. Tải Apidog, xây dựng một kịch bản, thả lệnh apidog run của nó vào .github/copilot-instructions.md, và xem Copilot tự động nhận biết nó trong lần thay đổi tiếp theo. Khi bạn sẵn sàng chạy cùng một lệnh trong một pipeline mà không có Copilot, bài viết Apidog CLI trong GitHub Actions sẽ đề cập đến các bí mật (secrets), báo cáo viên và cổng mã thoát.