Cách sử dụng Apidog CLI trong Hermes Agent

Hermes Agent chạy từ terminal, ghi nhớ ngữ cảnh qua các phiên làm việc và có thể thực thi lệnh shell thật. Vì vậy, nếu Hermes có thể chạy một lệnh, nó cũng có thể chạy bộ kiểm thử API của bạn.

Dùng thử Apidog ngay hôm nay

Trong bài này, bạn sẽ cấu hình Hermes để chạy kiểm thử API bằng Apidog CLI (apidog-cli). CLI này chạy các kịch bản kiểm thử đã tạo trong Apidog trực tiếp từ terminal và trả về mã thoát để Hermes xử lý.

Nếu chưa cài CLI, hãy làm theo hướng dẫn cài đặt Apidog CLI với tác nhân mã hóa AI. Quay lại khi lệnh sau in ra phiên bản:

apidog --version

Bạn cũng cần:

• Một tài khoản Apidog
• Ít nhất một kịch bản kiểm thử API đã lưu
• CLI đã đăng nhập bằng apidog login

“Sử dụng CLI trong Hermes” nghĩa là gì?

Hermes Agent, được xây dựng bởi Nous Research, chạy trong terminal và thao tác qua các công cụ tích hợp. Công cụ quan trọng ở đây là terminal: Hermes gọi lệnh shell trong thư mục làm việc, đọc stdout/stderr, rồi đưa kết quả vào vòng suy luận.

Bạn không cần plugin Apidog riêng cho Hermes. Quy trình gồm 3 phần:

1. Dạy Hermes workflow một lần bằng tệp ngữ cảnh như AGENTS.md.
2. Cho Hermes chạy apidog run thông qua công cụ terminal.
3. Tùy chọn kết nối Apidog MCP server để Hermes đọc thông số kỹ thuật API trong lúc viết mã.

Điểm quan trọng là mã thoát của apidog run:

• 0: tất cả assertion đều pass
• Khác 0: có lỗi kiểm thử

Hermes phải coi mã thoát là nguồn sự thật, không phải bản tóm tắt do chính nó viết ra.

Cơ chế: dùng tệp ngữ cảnh, không dùng prompt tạm thời

Hermes tải ngữ cảnh dự án khi bắt đầu phiên. Công cụ ngữ cảnh của nó quét thư mục làm việc để tìm các tệp hướng dẫn như:

• AGENTS.md
• CLAUDE.md

Nếu repo đã có AGENTS.md, Hermes sẽ đọc tệp đó khi khởi động.

Vì vậy, đừng chỉ gõ ID kịch bản trong một phiên chat. Hãy lưu workflow kiểm thử vào AGENTS.md để mọi phiên Hermes sau này đều biết cách chạy kiểm thử.

SOUL.md dành cho tính cách của tác nhân, không phải hướng dẫn dự án. Hãy đặt quy trình kiểm thử trong AGENTS.md.

Bước 1: Thêm khối Apidog vào AGENTS.md

Tạo hoặc mở tệp AGENTS.md ở thư mục gốc repo, rồi thêm khối sau. Thay 605067 và 1629989 bằng ID thật của bạn.

## Kiểm thử API với Apidog CLI

Repo này sử dụng Apidog CLI (`apidog-cli`, lệnh `apidog`) để chạy các kịch bản kiểm thử API. Các kịch bản nằm trong dự án Apidog, không nằm trong repo này.

Khi bạn thay đổi API handler, route hoặc định dạng response, hãy chạy kịch bản Apidog liên quan qua công cụ terminal trước khi coi thay đổi là hoàn tất:

    apidog run -t 605067 -e 1629989 -n 1 -r cli

- `-t 605067` là ID kịch bản kiểm thử quy trình thanh toán.
- `-e 1629989` là môi trường staging.
- Máy đã được xác thực bằng `apidog login`, vì vậy KHÔNG truyền access token và KHÔNG in token.

Coi mã thoát là nguồn sự thật:
- `0` nghĩa là mọi assertion đều thành công.
- Khác `0` nghĩa là kiểm thử thất bại.

Nếu lệnh thoát khác `0`, hãy đọc assertion thất bại trong báo cáo, sửa mã, rồi chạy lại. Không báo cáo thành công khi mã thoát khác `0`.

Khối này giúp Hermes biết chính xác:

• Lệnh cần chạy
• ID kịch bản
• ID môi trường
• Không được truyền token trong chat
• Cách diễn giải mã thoát

Đây là phần quan trọng nhất để tránh lỗi phổ biến: tác nhân nói “test đã pass” trong khi lệnh thực tế thất bại.

Bước 2: Lấy lệnh apidog run từ Apidog

Trước khi yêu cầu Hermes chạy kiểm thử, hãy lấy một lệnh chuẩn từ Apidog.

Trong Apidog:

1. Mở kịch bản kiểm thử.
2. Chuyển sang tab CI/CD.
3. Chọn tùy chọn dòng lệnh.
4. Sao chép lệnh apidog run.

Ví dụ:

apidog run --access-token YOUR_ACCESS_TOKEN -t 605067 -e 1629989 -n 1 -r cli

Trong đó:

• 605067: ID kịch bản
• 1629989: ID môi trường
• YOUR_ACCESS_TOKEN: token do Apidog tạo cho CI/CD

Vì máy local đã đăng nhập bằng CLI, hãy bỏ --access-token trước khi đưa vào AGENTS.md:

apidog run -t 605067 -e 1629989 -n 1 -r cli

Không commit access token vào repo.

Bước 3: Yêu cầu Hermes chạy kiểm thử

Khởi động Hermes trong thư mục repo, rồi yêu cầu nó chạy kiểm thử theo AGENTS.md.

Ví dụ prompt:

Hãy chạy kịch bản kiểm thử API Apidog của chúng ta theo cách mà AGENTS.md mô tả. Tôi đã xác thực CLI rồi, vì vậy đừng truyền access token. Sử dụng apidog run -t 605067 -e 1629989 -n 1 -r cli. Hiển thị toàn bộ output và cho tôi biết mã thoát.

Hermes sẽ gọi công cụ terminal để chạy:

apidog run -t 605067 -e 1629989 -n 1 -r cli

Với reporter -r cli, kết quả từng bước sẽ được in ra terminal để Hermes và bạn cùng đọc.

Sau khi chạy, hãy kiểm tra:

exit code: 0

Nếu mã thoát khác 0, kiểm thử thất bại. Đừng chỉ tin vào phần tóm tắt bằng văn bản.

Để xem các flag hỗ trợ trong phiên bản CLI hiện tại, yêu cầu Hermes chạy:

apidog run --help

Bạn cũng có thể xem hướng dẫn Apidog CLI đầy đủ, bao gồm các reporter như:

• cli
• html
• json
• junit

Bước 4: Đưa kiểm thử vào vòng lặp làm việc của Hermes

Sau khi AGENTS.md đã có hướng dẫn, Hermes có thể tự chạy kiểm thử khi chỉnh sửa mã liên quan đến API.

Ví dụ workflow:

1. Hermes sửa một API handler.
2. Hermes chạy:

   apidog run -t 605067 -e 1629989 -n 1 -r cli

1. Hermes đọc mã thoát.
2. Nếu pass, tiếp tục công việc.
3. Nếu fail, đọc assertion lỗi, sửa mã, rồi chạy lại.

Lúc này, kiểm thử API trở thành một phần của vòng lặp:

edit -> test -> inspect failure -> fix -> test again

Đây là cùng mô hình mà các tác nhân AI thường dùng với unit test, nhưng áp dụng cho kiểm thử API end-to-end hoặc workflow-level.

Với những lần chạy lâu, Hermes có thể dùng background=true cho công cụ terminal để chạy nền, tiếp tục làm việc, rồi kiểm tra kết quả sau.

Để hiểu thêm về mô hình này, xem:

• Cách sử dụng tác nhân AI để kiểm thử API
• Khung kiểm thử AI của Apidog

Tùy chọn: kết nối Apidog MCP server

Apidog CLI cho phép Hermes chạy kiểm thử. Apidog MCP server cho phép Hermes đọc thông số kỹ thuật API trong lúc viết mã.

Hai lớp này bổ sung cho nhau:

• MCP cung cấp schema/API contract.
• CLI xác minh implementation bằng kịch bản kiểm thử thật.

Hermes hỗ trợ Model Context Protocol. Để thêm Apidog MCP server, chỉnh sửa:

~/.hermes/config.yaml

Thêm cấu hình:

mcp_servers:
  apidog:
    command: "npx"
    args: ["-y", "apidog-mcp-server@latest", "--project=YOUR_PROJECT_ID"]
    env:
      APIDOG_ACCESS_TOKEN: "YOUR_ACCESS_TOKEN"

Sau khi lưu, trong Hermes chạy:

/reload-mcp

Hoặc khởi động lại Hermes.

Hermes sẽ phát hiện MCP server khi khởi động và đăng ký các công cụ của nó theo namespace dạng:

mcp_apidog_<tool>

Để biết cách lấy project ID và token, xem hướng dẫn máy chủ Apidog MCP.

Nếu bạn muốn xem một vòng lặp tương tự với Claude Skills, tham khảo hướng dẫn Apidog CLI với Claude Skills.

Từ local loop đến CI

Khi Hermes đã chạy được kịch bản local, bạn đã có lệnh gần như giống hệt lệnh dùng trong CI.

Khác biệt chính:

• Local: dùng phiên đăng nhập đã lưu bằng apidog login
• CI: truyền access token qua secret

Bạn có thể yêu cầu Hermes viết bước GitHub Actions:

Viết một bước GitHub Actions để cài đặt apidog-cli và chạy apidog run -t 605067 -e 1629989 -r junit, đọc access token từ secret của repo tên APIDOG_ACCESS_TOKEN.

Ví dụ bước CI:

- name: Install Apidog CLI
  run: npm install -g apidog-cli

- name: Run Apidog API tests
  env:
    APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}
  run: |
    apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 605067 -e 1629989 -r junit

Cơ chế chi tiết về secret, reporter và mã thoát được mô tả trong Apidog CLI trong GitHub Actions.

Sau khi thiết lập, cùng một kiểm thử có thể chạy ở 3 nơi:

1. Terminal local
2. Vòng lặp Hermes
3. CI pipeline

Tất cả đều dựa trên cùng một mã thoát.

Các vấn đề thường gặp

Hermes bỏ qua khối ngữ cảnh

Kiểm tra các điểm sau:

• Tệp có đúng tên AGENTS.md hoặc CLAUDE.md không?
• Tệp có nằm trong thư mục mà Hermes được khởi động không?
• Bạn đã khởi động lại phiên Hermes sau khi sửa tệp chưa?

Nếu Hermes chạy lệnh chung chung hoặc không chạy gì, khả năng cao là nó chưa đọc đúng tệp ngữ cảnh.

Hermes chỉ gợi ý lệnh thay vì chạy lệnh

Hermes chạy lệnh qua công cụ terminal và có thể cần phê duyệt.

Hãy kiểm tra:

• Có prompt phê duyệt đang chờ không?
• Cấu hình Hermes có chặn lệnh terminal không?
• Bạn có cần cho phép riêng apidog run không?

apidog whoami báo chưa xác thực

Thông tin đăng nhập được lưu trên máy, không nằm trong Hermes.

Tự chạy:

apidog login --with-token

Sau đó yêu cầu Hermes kiểm tra:

apidog whoami

Không đưa token vào chat nếu không cần thiết.

Hermes tự bịa flag

Nếu thấy lỗi dạng:

unknown option

Nghĩa là Hermes đã đoán một flag không tồn tại.

Cách xử lý:

apidog run --help

Yêu cầu Hermes đọc help output và dùng đúng flag có trong phiên bản CLI đang cài.

Hermes nói test pass nhưng lệnh fail

Luôn kiểm tra mã thoát.

Quy tắc:

• Text summary có thể sai.
• Exit code là nguồn sự thật.
• apidog run chỉ trả về 0 khi mọi assertion pass.

Nếu summary và mã thoát mâu thuẫn, hãy tin mã thoát.

Tổng kết

Thiết lập Hermes với Apidog CLI chỉ cần một tệp và một thói quen:

• Một khối AGENTS.md mô tả lệnh apidog run, môi trường, xác thực và quy tắc mã thoát.
• Một workflow yêu cầu Hermes chạy kiểm thử qua công cụ terminal và kiểm tra exit code.

Nếu cần Hermes đọc API contract trong lúc viết mã, thêm Apidog MCP server vào ~/.hermes/config.yaml.

Bạn vẫn tạo và quản lý kịch bản kiểm thử trực quan trong Apidog. Hermes chỉ chạy chúng, đọc kết quả và sửa mã dựa trên lỗi thật.

Bước tiếp theo:

• Đưa cùng lệnh vào CI với Apidog CLI trong GitHub Actions
• Tra cứu toàn bộ flag trong hướng dẫn Apidog CLI đầy đủ

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

Tôi có cần plugin Hermes để sử dụng Apidog CLI không?

Không. Hermes có thể chạy lệnh shell qua công cụ terminal, nên nó gọi trực tiếp apidog run. Phần dành riêng cho Hermes là AGENTS.md và MCP server tùy chọn.

Tôi nên đặt hướng dẫn workflow cho Hermes ở đâu?

Đặt trong AGENTS.md ở thư mục gốc repo. Hermes sẽ đọc tệp này khi khởi động phiên trong repo đó.

Làm thế nào để đảm bảo Hermes không báo giả test pass?

Yêu cầu Hermes luôn báo mã thoát. apidog run chỉ trả về 0 khi mọi assertion pass. Nếu mã thoát khác 0, kiểm thử thất bại dù summary nói gì.

Làm thế nào để kết nối Apidog MCP server với Hermes?

Thêm mục mcp_servers vào ~/.hermes/config.yaml, dùng apidog-mcp-server và project ID của bạn. Sau đó chạy /reload-mcp hoặc khởi động lại Hermes. Xem hướng dẫn máy chủ Apidog MCP.

Quy trình này có áp dụng cho tác nhân AI khác không?

Có. CLI vẫn giống nhau; chỉ khác cách bạn cung cấp hướng dẫn cho tác nhân. Hermes đọc AGENTS.md và dùng công cụ terminal, còn tác nhân khác có thể dùng tệp hướng dẫn riêng. Cài đặt và xác thực CLI vẫn theo cùng hướng dẫn cài đặt.