Đây là loạt bài 10 phần về cách Apidog phát triển Apidog CLI, công cụ dòng lệnh dùng để kiểm thử API và quản lý vòng đời API. Bạn có thể đọc theo thứ tự hoặc nhảy đến phần phù hợp với vấn đề đang triển khai.
| 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 | Khám phá 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 dữ kiện, Mô hình hoạt động dựa trên dữ kiện | Triết lý cốt lõi |
| 4 | agentHints: Dạy CLI giao tiếp với Agent |
Đầu ra có cấu trúc |
| 5 | SKILL: Chuyển giao kinh nghiệm vận hành dưới dạng mã | Kinh nghiệm vận hành |
| 6 | Các con số không biết nói dối: Giảm 30% số lần gọi công cụ, giảm 25% số Token | Kết quả định lượng |
| 7 | Từ PRD đến vòng lặp kiểm thử: Quy trình làm việc hoàn chỉnh của Agent 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 Agent | Lớp bảo mật |
| 10 | Ưu tiên đặc tả đã là quá khứ. Chào mừng đến với Ưu tiên kỹ năng. | Tầm nhìn & tương lai |
Chúng tôi đã so sánh MCP với CLI + SKILL trên các tác vụ người dùng thường gặp. Kết quả: ít lần gọi công cụ hơn, ít token lãng phí hơn, khôi phục lỗi tốt hơn — và dữ liệu cho thấy lý do.
Câu hỏi cần kiểm chứng
Các nguyên tắc thiết kế đã nêu ở các phần trước có thật sự hiệu quả trong quy trình triển khai không?
Để kiểm chứng, chúng tôi so sánh nội bộ nhiều tác vụ phổ biến trên hai cách tiếp cận:
| Loại tác vụ | Mô tả |
|---|---|
| Thêm trường hợp kiểm thử + xác minh | Tạo trường hợp kiểm thử cho endpoint, sau đó chạy kiểm thử |
| Duy trì kịch bản kiểm thử | Cập nhật các kịch bản đa bước phức tạp |
| Nhập/xác minh tài sản dự án | Nhập dữ liệu, xác nhận cấu trúc, chạy kiểm thử |
Kết quả không chỉ là cảm nhận chủ quan. Chúng là các mức giảm có thể đo lường được.
Tác vụ 1: Thêm trường hợp kiểm thử dựa trên endpoint
Yêu cầu của người dùng:
"Thêm một kiểm thử cho endpoint này và chạy xác minh"
Cách MCP thường xử lý
| Giai đoạn | Điều gì xảy ra |
|---|---|
| Khám phá công cụ | Agent tìm trong danh sách công cụ |
| Lựa chọn công cụ | Agent cần nhiều vòng để chọn đúng công cụ |
| Khám phá trường | Agent đọc schema của công cụ |
| Phỏng đoán trường | Agent đoán các trường bắt buộc |
| Thử ghi | Agent gọi công cụ tạo |
| Phản hồi lỗi | Máy chủ từ chối do sai/thiếu trường |
| Thử lại | Agent điều chỉnh rồi thử lại |
| Thử lại nhiều lần | Lặp lại đến khi thành công |
| Chạy kiểm thử | Agent tìm công cụ chạy và thực thi |
Mẫu thực thi thường gặp:
Tìm kiếm công cụ
→ Chọn công cụ
→ Đọc schema
→ Đoán trường
→ Ghi
→ Lỗi
→ Thử lại
→ Ghi
→ Lỗi
→ Thử lại
→ Thành công
→ Tìm công cụ chạy
→ Chạy
Vấn đề chính: mô hình phải tự xử lý quá nhiều việc trong ngữ cảnh — chọn công cụ, hiểu schema, đoán trường và khôi phục lỗi.
Cách CLI + SKILL xử lý
| Giai đoạn | Điều gì xảy ra |
|---|---|
| Hướng dẫn SKILL | SKILL nhận diện loại tác vụ và cung cấp workflow |
| Đọc endpoint | CLI đọc dữ kiện endpoint |
| Tạo trường hợp kiểm thử | Agent tạo test case dựa trên dữ liệu endpoint thực tế |
| Xác thực cục bộ |
cli-schema xác thực trước khi ghi |
| Ghi | CLI tạo trường hợp kiểm thử |
| Đọc lại | CLI trả về cấu trúc đã tạo và agentHints
|
| Chạy kiểm thử |
agentHints gợi ý bước chạy, Agent làm theo |
Mẫu thực thi:
SKILL hướng dẫn
→ Đọc endpoint
→ Tạo test case
→ Xác thực cục bộ
→ Ghi
→ Đọc lại
→ Chạy kiểm thử
Điểm khác biệt triển khai: workflow được định hướng từ đầu, còn lỗi schema được bắt trước khi gọi mạng.
Kết quả
| Chỉ số | Lộ trình MCP | CLI + SKILL | Cải thiện |
|---|---|---|---|
| Số bước gọi công cụ | ~15-20 | ~10-12 | ↓ ~30% |
| Token từ mô tả | ~50.000 đã tải | ~2.000 đã tải | ↓ ~96% |
| Token từ các lần thử lại | ~5.000+ lãng phí | ~500 lãng phí | ↓ ~90% |
| Tổng số token lãng phí | ~55.000 | ~2.500 | ↓ ~25% |
Kết luận triển khai: nếu workflow có thể được mô tả bằng SKILL và CLI có thể trả về dữ kiện đáng tin cậy, Agent không cần dùng token để tự khám phá mọi thứ.
Tác vụ 2: Ghi có cấu trúc cho processor, assertion và extractor
Yêu cầu của người dùng:
"Thêm các khẳng định sau thao tác và trích xuất biến vào trường hợp kiểm thử này"
Cách MCP thường xử lý
| Giai đoạn | Điều gì xảy ra |
|---|---|
| Phỏng đoán tên trường | Agent không biết tên trường chính xác |
| Phỏng đoán giá trị enum | Agent đoán comparator, type hoặc subject |
| Thử ghi | Máy chủ từ chối giá trị sai |
| Thử lại mạng | Mỗi lỗi tạo thêm một lượt request/response |
| Nhiều lần thử | 3-5 lần thử lại là phổ biến |
Ví dụ lỗi thường gặp:
| Phỏng đoán sai | Giá trị đúng | Số lần thử lại |
|---|---|---|
comparator: "contains" |
comparator: "include" |
1-2 |
type: "global" |
type: "globals" |
1-2 |
subject: "responseBody" |
subject: "responseJson" |
1-2 |
Mỗi lỗi tạo thêm:
request lỗi
→ response lỗi
→ Agent đọc lỗi
→ Agent sửa
→ request lại
Chi phí không chỉ nằm ở network call. Agent còn tiêu tốn token để đọc phản hồi lỗi và quyết định cách sửa.
Cách CLI + SKILL xử lý
| Giai đoạn | Điều gì xảy ra |
|---|---|
| Đọc trường hợp kiểm thử | CLI lấy cấu trúc thực tế |
| Tạo phần bổ sung | Agent tạo assertion/extractor theo định dạng thực |
| Xác thực cục bộ |
cli-schema bắt lỗi trước khi gọi mạng |
| Sửa lỗi cục bộ | Agent điều chỉnh dựa trên đầu ra xác thực |
| Xác thực lại | Xác nhận bản sửa hợp lệ |
| Ghi | Chỉ dữ liệu hợp lệ mới được gửi đến máy chủ |
Mẫu triển khai tốt hơn:
Đọc cấu trúc thực
→ Sinh thay đổi
→ Validate local
→ Sửa nếu cần
→ Validate lại
→ Ghi lên server
Tất cả lỗi trường được bắt cục bộ. Không cần thử lại mạng cho lỗi cấu trúc.
Kết quả
| Chỉ số | Lộ trình MCP | CLI + SKILL | Cải thiện |
|---|---|---|---|
| Thử lại mạng do lỗi cấu trúc | 3-5 | 0 | ↓ ~100% |
| Token từ phản hồi lỗi | ~2.000 | ~0 | ↓ ~100% |
| Tổng số lần gọi lặp lại | ~5 | ~1 | ↓ ~40% |
Kết luận triển khai: nếu dữ liệu có schema rõ ràng, hãy validate ở CLI trước. Đừng để mô hình học schema bằng cách gửi request sai lên server.
Tác vụ 3: Tiếp tục thao tác sau khi tạo
Yêu cầu của người dùng:
"Tạo một kịch bản kiểm thử với các endpoint này"
Cách MCP thường xử lý
| Giai đoạn | Điều gì xảy ra |
|---|---|
| Tạo kịch bản | Agent gọi công cụ tạo |
| Phản hồi thành công | Agent thấy trạng thái "đã tạo" |
| Tiếp tục ghi | Agent ngay lập tức cập nhật hoặc thêm nội dung |
| Bỏ qua đọc lại | Agent không đọc cấu trúc thực tế sau khi tạo |
| Ghi dựa trên giả định | Agent dùng ID/cấu trúc được phỏng đoán |
| Lỗi hoặc không hoàn chỉnh | Kết quả không khớp kỳ vọng |
Vấn đề ở đây là quán tính thực thi.
Sau khi nhận phản hồi thành công, mô hình thường tiếp tục bước kế tiếp mà không xác minh lại trạng thái thực tế của tài nguyên vừa tạo.
Cách CLI + SKILL xử lý
| Giai đoạn | Điều gì xảy ra |
|---|---|
| Tạo kịch bản | CLI tạo kịch bản |
Thành công + agentHints
|
CLI trả về kết quả kèm gợi ý bước tiếp theo |
agentHints: đọc lại trước |
Agent thấy gợi ý cụ thể |
| Làm theo gợi ý | Agent đọc lại tài nguyên |
| Làm việc với cấu trúc thực | Agent tiếp tục dựa trên dữ liệu chính xác |
Ví dụ mẫu hành vi mong muốn:
create scenario
→ nhận scenarioId
→ read scenario theo scenarioId
→ cập nhật dựa trên cấu trúc thực
→ validate
→ run
agentHints không thay Agent ra quyết định, nhưng giúp Agent tránh tiếp tục một cách mù quáng.
Kết quả
| Chỉ số | Lộ trình MCP | CLI + SKILL | Cải thiện |
|---|---|---|---|
| Tỷ lệ đọc lại trước khi tiếp tục | ~20% | ~85% | ↑ ~425% |
| Thử lại lỗi do nhảy trực tiếp | ~3-5 | ~0-1 | ↓ ~21% |
Kết luận triển khai: sau thao tác tạo/cập nhật, CLI nên gợi ý rõ bước đọc lại hoặc xác minh. Đây là cách giảm lỗi do Agent ghi tiếp trên giả định cũ.
Tóm tắt: Khoản tiết kiệm đến từ đâu?
| Nguồn tiết kiệm | Cách hoạt động |
|---|---|
| Khám phá công cụ | CLI có lệnh rõ nghĩa; SKILL hướng dẫn lựa chọn |
| Xác thực schema | Validate cục bộ trước khi gọi mạng |
| Phục hồi lỗi |
agentHints trả về gợi ý có thể hành động, không chỉ báo "failed" |
| Hướng dẫn đọc lại | Ngăn Agent ghi dựa trên giả định |
| Trình tự workflow | SKILL giảm số điểm Agent phải tự quyết định |
Nếu triển khai công cụ cho Agent, hãy ưu tiên các cơ chế sau:
1. Cung cấp workflow rõ ràng
2. Trả về dữ kiện có cấu trúc
3. Validate trước khi gọi server
4. Gợi ý bước tiếp theo bằng agentHints
5. Bắt buộc hoặc khuyến khích đọc lại sau thao tác ghi
Phân tích chi phí thực tế
Insight chính:
Kích hoạt Agent cho sản phẩm không có nghĩa là cung cấp càng nhiều công cụ càng tốt.
Điều mô hình thực sự tiêu thụ gồm nhiều loại chi phí:
| Loại chi phí | Gánh nặng MCP | Gánh nặng CLI + SKILL |
|---|---|---|
| Ngữ cảnh | Mô tả công cụ, schema | Chỉ SKILL tập trung vào tác vụ |
| Sự chú ý | Chọn trong nhiều công cụ | Theo workflow được hướng dẫn |
| Chọn đường dẫn | Tự đoán trình tự | Trình tự do SKILL xác định |
| Chi phí token người dùng | Thử lại, cuộc gọi thất bại | Ghi đã validate, ít cuộc gọi hơn |
Khi số lượng công cụ tăng, thứ mô hình tiêu thụ không chỉ là khả năng gọi API. Nó còn tiêu thụ ngữ cảnh, sự chú ý, khả năng chọn đường đi và ngân sách token của người dùng.
Nguyên tắc kỹ thuật
Mục tiêu:
Chuyển chi phí ra khỏi ngữ cảnh của mô hình và đưa về nơi hệ thống kỹ thuật có thể xử lý tốt hơn.
| Chi phí | Vị trí trong MCP | Vị trí trong CLI + SKILL |
|---|---|---|
| Khám phá công cụ | Mô hình phải tìm kiếm | SKILL cung cấp hướng dẫn |
| Xác thực trường | Mô hình phải biết |
cli-schema xác thực |
| Hướng dẫn bước tiếp theo | Mô hình phải tự quyết định |
agentHints gợi ý |
| Ngữ nghĩa sản phẩm | Mô hình phải hiểu | CLI xử lý |
Cách thiết kế này chia vai trò rõ hơn:
CLI: đọc dữ kiện, ghi dữ liệu, validate, trả về trạng thái
SKILL: định nghĩa workflow và kinh nghiệm vận hành
Agent: tạo nội dung, suy luận, quyết định trong phạm vi đã được hướng dẫn
Hệ thống kỹ thuật hấp thụ độ phức tạp. Mô hình tập trung vào tạo và phán đoán.
Ý nghĩa của các con số
| Thông tin đo được | Hàm ý kỹ thuật |
|---|---|
| Giảm 30% số lần gọi công cụ | Độ phức tạp chuyển từ khám phá sang hướng dẫn |
| Giảm 25% token lãng phí | Lỗi được bắt trước khi gọi mạng |
| Giảm 40% lần thử lại cấu trúc | Cổng xác thực cục bộ hoạt động |
| Giảm 21% lỗi nhảy bước |
agentHints giảm tiếp tục mù quáng |
CLI + SKILL không chỉ là tinh chỉnh kiến trúc. Nó tạo ra hiệu quả có thể đo lường được trong workflow của Agent.
Tiếp theo là gì?
Sau khi phương pháp đã được kiểm chứng bằng số liệu, bước tiếp theo là xem nó vận hành trong một workflow hoàn chỉnh.
Trong Phần 7, Từ PRD đến vòng lặp kiểm thử: Quy trình làm việc hoàn chỉnh của Agent, chúng ta sẽ đi qua một ví dụ thực tế: nhóm có PRD "Hoàn tiền đơn hàng", và Agent dùng CLI + SKILL để tạo OpenAPI, tạo kiểm thử, xác thực và xác minh.
Những điểm chính
- Số bước gọi công cụ giảm khoảng 30%.
- Token lãng phí từ mô tả và thử lại giảm khoảng 25%.
- Số lần thử lại lỗi cấu trúc giảm khoảng 40%.
- Lỗi nhảy bước do bỏ qua đọc lại giảm khoảng 21%.
- Tiết kiệm đến từ khám phá có hướng dẫn, xác thực cục bộ và gợi ý có thể hành động.
- Độ phức tạp nên được chuyển từ ngữ cảnh của mô hình sang hệ thống kỹ thuật.
Tải xuống Apidog để thiết kế, mock, 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 dòng lệnh, tự động hóa CI và workflow AI Agent.
Top comments (0)