Sebastian Petrus

Posted on Jul 6 • Originally published at apidog.com

Tại sao khả năng tương thích CI/CD là điều kiện bắt buộc cho các công cụ Agent

Đây là phần 8 trong loạt 10 bài về cách Apidog phát triển Apidog CLI: công cụ dòng lệnh để kiểm thử API và quản lý vòng đời API. Bạn có thể đọc tuần tự hoặc mở trực tiếp phần phù hợp với nhu cầu triển khai của mình.

Dùng thử Apidog ngay hôm nay

	Tiêu đề	Trọng tâm
1	Chúng tôi đã xây dựng 126 công cụ MCP. Nhưng đó không phải là giải pháp tốt nhất cho Agent	Phát hiện vấn đề
2	Tại sao chúng tôi phát triển Apidog CLI hoàn toàn mới	Phát triển kiến trúc
3	Quy tắc vàng: CLI tạo ra sự thật, Model hành động dựa trên sự thật	Triết lý cốt lõi
4	`agentHints`: Dạy CLI nói chuyện với Agents	Đầu ra có cấu trúc
5	SKILL: Chuyển trải nghiệm vận hành thành mã	Trải nghiệm vận hành
6	Các con số không nói dối: Giảm 30% cuộc gọi công cụ, giảm 25% Tokens	Kết quả định lượng
7	Từ PRD đến vòng lặp kiểm thử: Một quy trình làm việc Agent hoàn chỉnh với Apidog CLI	Hướng dẫn thực hành
8	Tại sao khả năng tương thích CI/CD là không thể thiếu đối với các công cụ Agent	Góc nhìn DevOps
9	Nhánh AI: Thay đổi dự án an toàn hơn với AI Agents	Lớp bảo mật
10	Spec-First là chuyện của ngày hôm qua. Chào mừng đến với Skill-First.	Tầm nhìn & tương lai

Khả năng thân thiện với Agent nên được xây dựng trên nền tảng đã phục vụ tốt cho CI/CD. Trong bài này, chúng ta xem cách apidog run phục vụ cùng lúc CI pipelines, scripts, con người và AI Agents.

Vấn đề: một CLI phải phục vụ nhiều đối tượng

Khi xây dựng công cụ cho AI Agent, rất dễ chỉ tối ưu cho trải nghiệm đàm thoại: Agent gọi lệnh, đọc kết quả, rồi quyết định bước tiếp theo.

Nhưng với một CLI kỹ thuật, đó chưa đủ.

Apidog CLI vẫn phải phục vụ một đối tượng quan trọng: CI/CD.

Đối tượng ban đầu	Đối tượng mới
CI/CD pipelines	AI Agents
Hệ thống lập lịch bên ngoài	Quy trình làm việc đàm thoại
Scripts và tự động hóa	Các tác vụ do người dùng điều khiển

Nhiều nhóm đã dùng Apidog trong pipeline để:

Chạy kiểm thử API tự động
Tạo báo cáo kiểm thử
Duy trì cổng chất lượng trước khi triển khai

Các kịch bản này cần CLI có hành vi ổn định:

Yêu cầu	Tại sao quan trọng
Đầu ra ổn định	Script có thể phân tích kết quả dự đoán được
Lệnh có thể lập trình	Có thể chạy tự động trong CI
Mã thoát rõ ràng	Pipeline biết khi nào pass/fail
Tham số có thể cấu hình	Chạy theo môi trường, scenario, báo cáo khác nhau

Tự động hóa CI không nên bị phá vỡ chỉ để thêm hỗ trợ cho Agents.

Nguyên tắc thiết kế

Khả năng thân thiện với Agent phải được xây dựng trên nền tảng khả năng thân thiện với CI/CD.

Thay vì tạo một giao thức riêng chỉ dành cho AI, Apidog CLI mở rộng nền tảng CLI hiện có bằng:

Đầu ra có cấu trúc
Schema để xác thực
Gợi ý bước tiếp theo cho Agent
Cùng một cơ chế chạy kiểm thử đã dùng trong CI

Một CLI tốt trong kỷ nguyên Agent nên phục vụ được bốn nhóm người dùng:

Người dùng	Họ cần gì
Con người	Output dễ đọc, help text, tương tác trực tiếp
Scripts	Output ổn định, tham số rõ ràng
CI pipelines	Mã thoát, báo cáo, cấu hình môi trường
AI Agents	JSON có cấu trúc, lỗi có ngữ cảnh, hướng dẫn bước tiếp theo

Lệnh cốt lõi: `apidog run`

Nền tảng của quy trình là lệnh:

apidog run --project <projectId> \
  --test-scenario <scenarioId> \
  --environment <environmentId> \
  -r "cli,html,junit" \
  --out-dir ./apidog-reports

Lệnh này có thể được dùng trong:

Terminal của developer
GitHub Actions
Jenkins/GitLab CI/CircleCI/Azure DevOps
Script nội bộ
Workflow do AI Agent điều khiển

Điểm quan trọng là: không cần một lệnh riêng cho Agent và một lệnh riêng cho CI.

Cách dùng trong CI/CD

Trong CI, điều quan trọng không phải là output “đẹp”, mà là output có thể tự động xử lý.

Yêu cầu CI	Cách CLI đáp ứng
Mã thoát	`0` cho pass, `1` cho fail
Tệp báo cáo	HTML, JUnit, JSON trong `--out-dir`
Tham số ổn định	Các option nhất quán giữa các lần chạy
Chạy theo cấu hình	Scenario, environment, số lần lặp, độ trễ request

Ví dụ GitHub Actions:

# GitHub Actions
- name: Chạy Kiểm thử API
  run: |
    apidog run --project $PROJECT_ID \
      --test-scenario $SCENARIO_ID \
      --environment $ENV_ID \
      -r "junit" \
      --out-dir ./reports
  env:
    PROJECT_ID: ${{ secrets.APIDOG_PROJECT_ID }}
    SCENARIO_ID: ${{ secrets.APIDOG_SCENARIO_ID }}
    ENV_ID: production

- name: Công bố Báo cáo Kiểm thử
  uses: mikepenz/action-junit-report@v3
  with:
    report_paths: './reports/junit.xml'

Quy trình xử lý trong CI thường là:

Pipeline gọi apidog run
CLI chạy scenario kiểm thử API
CLI ghi báo cáo vào ./reports
Pipeline đọc mã thoát
Nếu fail, pipeline dừng hoặc đánh dấu build thất bại
Báo cáo JUnit được công bố để developer kiểm tra

CI chỉ cần một hợp đồng rõ ràng: mã thoát + báo cáo.

Cách dùng trong workflow của Agent

Agent cần nhiều ngữ cảnh hơn CI. Một pipeline chỉ cần biết pass/fail, nhưng Agent cần biết:

Bước nào thất bại
Lỗi cụ thể là gì
Response liên quan là gì
Nên làm gì tiếp theo

Yêu cầu của Agent	Cách CLI đáp ứng
Kết quả có cấu trúc	Output JSON với đối tượng dữ liệu rõ ràng
Lý do thất bại	Chi tiết lỗi trong object `error` hoặc danh sách failure
Gợi ý bước tiếp theo	`agentHints.nextSteps`
Xác thực trước khi ghi	`cli-schema validate`

Ví dụ output mà Agent có thể đọc:

{
  "success": true,
  "stats": {
    "total": 10,
    "passed": 8,
    "failed": 2
  },
  "failures": [
    {
      "step": "Xử lý thanh toán",
      "error": "Xác nhận thất bại: status != 'success'",
      "response": {
        "status": "failed",
        "message": "Payment provider rejected request"
      }
    }
  ],
  "agentHints": {
    "summary": "2 bài kiểm thử thất bại. Xem lại chi tiết lỗi.",
    "nextSteps": [
      "Gỡ lỗi bước 'Xử lý thanh toán' bị lỗi.",
      "Kiểm tra xác nhận: trạng thái mong muốn là 'success'.",
      "Cập nhật trường hợp kiểm thử hoặc endpoint sau khi sửa lỗi."
    ]
  }
}

Một Agent có thể xử lý output này theo luồng:

Parse JSON từ CLI
Kiểm tra success
Nếu có failure, đọc failures
Đọc agentHints.nextSteps
Sửa test case, endpoint hoặc dữ liệu kiểm thử
Chạy lại apidog run để xác minh

Agent không chỉ cần biết kiểm thử thất bại. Nó cần biết nên điều tra ở đâu.

Cùng một lệnh, nhiều cách tiêu thụ kết quả

Ví dụ lệnh tối giản:

apidog run --project <projectId> --out-dir ./apidog-reports

Các đối tượng khác nhau sẽ lấy thông tin khác nhau từ cùng một lần chạy:

Người dùng	Điều họ trích xuất
CI pipeline	Mã thoát `0/1`, đường dẫn báo cáo
Agent	JSON output, `agentHints`, chi tiết lỗi
Con người	Console output, báo cáo HTML
Script	Stdout/stderr, file output, format cấu hình được

Điểm thiết kế quan trọng: CLI không cần đoán ai đang gọi nó.

Thay vào đó, CLI cung cấp các primitive ổn định:

Lệnh rõ ràng
Tham số rõ ràng
Exit code rõ ràng
Report file rõ ràng
Output có thể đọc bởi máy

Điểm tích hợp CI/CD

Apidog CLI có thể tích hợp với các hệ thống CI phổ biến bằng cùng một nền tảng apidog run.

Công cụ CI	Cách tích hợp
Jenkins	Pipeline steps, công bố báo cáo
GitLab CI	YAML config, artifacts
GitHub Actions	Workflow steps, secrets
CircleCI	Workflow config
Azure DevOps	Pipeline tasks, test results

Ví dụ cấu trúc chung trong hầu hết CI:

apidog run --project "$PROJECT_ID" \
  --test-scenario "$SCENARIO_ID" \
  --environment "$ENV_ID" \
  -r "junit,html" \
  --out-dir ./apidog-reports

Sau đó CI có thể:

Upload ./apidog-reports làm artifact
Đọc JUnit report
Dừng deployment nếu exit code khác 0
Gửi notification cho team

Cổng chất lượng CI và xác minh của Agent

Cùng một lệnh có thể phục vụ hai mục đích khác nhau.

Trường hợp sử dụng	Ý nghĩa
Cổng chất lượng CI	Pass/fail quyết định pipeline có được đi tiếp hay không
Xác minh Agent	Chạy sau khi Agent tạo hoặc sửa kiểm thử để xác nhận kết quả

Ngữ cảnh	Khi sử dụng	Mục đích
CI	Sau khi push code	Ngăn mã lỗi được triển khai
Agent	Sau khi tạo/sửa kiểm thử	Xác nhận công việc của Agent là đúng

Ví dụ:

# CI dùng để chặn deployment nếu API test fail
apidog run --project "$PROJECT_ID" \
  --test-scenario "$SCENARIO_ID" \
  --environment production \
  -r "junit" \
  --out-dir ./reports

# Agent dùng để xác minh sau khi chỉnh sửa test scenario
apidog run --project "$PROJECT_ID" \
  --test-scenario "$SCENARIO_ID" \
  --environment staging \
  -r "cli,json" \
  --out-dir ./agent-verification

Cả hai đều dùng apidog run, nhưng mục tiêu vận hành khác nhau:

CI bảo vệ pipeline
Agent xác minh hành động vừa thực hiện

Kiến trúc nền tảng

Các tính năng dành cho Agent như cli-schema, agentHints, SKILL không thay thế nền tảng CI/CD. Chúng được xây trên nền đó.

┌─────────────────────────────────────────┐
│          Tính năng của Agent             │
│  (cli-schema, agentHints, SKILL)        │
├─────────────────────────────────────────┤
│          Nền tảng CI/CD                 │
│  (apidog run, mã thoát, báo cáo)        │
├─────────────────────────────────────────┤
│          CLI cốt lõi                    │
│  (lệnh, tham số, thực thi)              │
└─────────────────────────────────────────┘

Cách nhìn thực tế:

CLI cốt lõi cung cấp lệnh và tham số
CI/CD dựa vào exit code và report
Agent dùng thêm output có cấu trúc và hint
Tất cả cùng dùng một execution path

Tính năng Agent nên mở rộng tính năng CI, không phá vỡ hoặc thay thế chúng.

Checklist khi thiết kế CLI thân thiện với CI và Agent

Nếu bạn đang xây CLI cho workflow tương tự, hãy kiểm tra các điểm sau:

[ ] Lệnh có thể chạy không cần tương tác không?
[ ] Có exit code rõ ràng cho pass/fail không?
[ ] Có thể ghi báo cáo ra thư mục được chỉ định không?
[ ] Có format output dành cho máy đọc không?
[ ] Có giữ ổn định tên option giữa các phiên bản không?
[ ] Có thể chạy theo environment khác nhau không?
[ ] Agent có đủ thông tin để hiểu lỗi không?
[ ] Agent có biết bước tiếp theo nên làm gì không?
[ ] CI có thể dùng cùng lệnh mà không cần logic đặc biệt không?

Nếu câu trả lời là “có”, CLI của bạn không chỉ thân thiện với Agent mà còn đủ chắc chắn cho tự động hóa sản xuất.

Tiếp theo là gì

Chúng ta đã đi từ phát hiện vấn đề, thiết kế kiến trúc, output có cấu trúc, SKILL, đến workflow thực tế và nền tảng CI/CD.

Phần tiếp theo là một lớp quan trọng khác: bảo mật.

Khi Agents có thể sửa đổi tài nguyên dự án, làm thế nào để ngăn chúng ảnh hưởng trực tiếp đến nhánh chính?

Trong Phần 9, Nhánh AI: Thay đổi dự án an toàn hơn với AI Agents, chúng ta sẽ xem cách Nhánh AI tạo môi trường chỉnh sửa biệt lập: thay đổi nằm trong một nhánh riêng cho đến khi được con người xem xét.

Những điểm chính

Khả năng tương thích CI/CD là nền tảng, không phải tính năng phụ.
Khả năng thân thiện với Agent nên được xây trên nền tảng thân thiện với CI.
Cùng một lệnh apidog run có thể phục vụ CI, Agents, con người và scripts.
CI cần exit code, báo cáo và tham số ổn định.
Agents cần output có cấu trúc, chi tiết lỗi và gợi ý bước tiếp theo.
Cổng chất lượng CI và xác minh Agent là hai ngữ cảnh khác nhau của cùng một cơ chế chạy.

Tải xuống Apidog để thiết kế, giả lập, kiểm thử và tài liệu hóa API trong một không gian làm việc. Tìm hiểu thêm về Apidog CLI để kiểm thử API bằng dòng lệnh, tự động hóa CI và xây dựng workflow cho AI Agent.

DEV Community

Tại sao khả năng tương thích CI/CD là điều kiện bắt buộc cho các công cụ Agent

Vấn đề: một CLI phải phục vụ nhiều đối tượng

Nguyên tắc thiết kế

Lệnh cốt lõi: `apidog run`

Cách dùng trong CI/CD

Cách dùng trong workflow của Agent

Cùng một lệnh, nhiều cách tiêu thụ kết quả

Điểm tích hợp CI/CD

Cổng chất lượng CI và xác minh của Agent

Kiến trúc nền tảng

Checklist khi thiết kế CLI thân thiện với CI và Agent

Tiếp theo là gì

Những điểm chính

Top comments (0)

Vấn đề: một CLI phải phục vụ nhiều đối tượng

Nguyên tắc thiết kế

Lệnh cốt lõi: apidog run

Cách dùng trong CI/CD

Cách dùng trong workflow của Agent

Cùng một lệnh, nhiều cách tiêu thụ kết quả

Điểm tích hợp CI/CD

Cổng chất lượng CI và xác minh của Agent

Kiến trúc nền tảng

Checklist khi thiết kế CLI thân thiện với CI và Agent

Tiếp theo là gì

Những điểm chính

Lệnh cốt lõi: `apidog run`