Đây là một chuỗi bài viết gồm 10 phần chia sẻ cách Apidog phát triển Apidog CLI, một công cụ dòng lệnh để kiểm thử API và quản lý vòng đời API. Đọc theo thứ tự hoặc chuyển đến bất kỳ bài viết nào bạn quan tâm:
| Tiêu đề | Tập trung | |
|---|---|---|
| 1 | Chúng Ta Đã Xây 126 Công Cụ MCP. Nhưng Không Là Giải Pháp Tốt Nhất cho Agent | Phát hiện vấn đề |
| 2 | Tại Sao Chúng Ta 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 Facts, Model Hành Động Theo Facts | Triết lý cốt lõi |
| 4 | agentHints: Dạy CLIs Giao Tiếp với Agents |
Output có cấu trúc |
| 5 | SKILL: Đóng Gói Kinh Nghiệm Vận Hành như Code | Kinh nghiệm vận hành |
| 6 | Con Số Không Nói Dối: 30% Ít Tool Calls, 25% Ít Tokens | Kết quả định lượng |
| 7 | Từ PRD đến Vòng Lặp Testing: Workflow Hoàn Chỉnh với Apidog CLI | Tutorial thực tế |
| 8 | Tại Sao CI/CD Compatibility Không Thể Thỏa Hiệp cho Tools Agent | Góc nhìn DevOps |
| 9 | AI Branch: Thay Đổi Project An Toàn Hơn với AI Agents | Lớp bảo mật |
| 10 | Spec-First Là Quá Khứ. Chào Mừng Skill-First. | Tầm nhìn & tương lai |
Chúng Ta Đã Xây 126 Công Cụ MCP. Sau Đó Chúng Ta Phát Hiện Đây Không Là Giải Pháp Tốt Nhất để Làm Việc trên Phát Triển API với Agents.
Khi MCP (Model Context Protocol) trở thành điểm nóng của ngành vào đầu 2025, câu hỏi mà mọi sản phẩm API phải đối mặt rất đơn giản: "Bạn có MCP?"
Với Apidog, chúng tôi trả lời có. Chúng tôi xây dựng một MCP Server hoàn chỉnh—không chỉ là một demo đơn giản. MCP client sẽ khởi tạo một session, server sẽ tạo sessionId, và lưu trạng thái session qua Redis. Đây là một hệ thống session ở mức protocol. Chúng tôi chia các tools thành categories: tools native của project, tools domain built-in, và 126 tools được tạo tự động từ định nghĩa endpoint OpenAPI.
Apidog MCP tiếp tục hoạt động và phục vụ người dùng cần tích hợp MCP. Nó cung cấp kết nối tools theo chuẩn MCP protocol, điều này có giá trị cho ecosystem.
Nhưng khi chúng tôi đi vào các task thực tế liên quan workflow R&D phức tạp, chúng tôi phát hiện ra giới hạn. Khi một người dùng nói "giúp tôi thêm test cho endpoint này và chạy verification", Agent phải đối mặt với một đống tools ngẫu nhiên—quyết định dùng nào, theo thứ tự gì, với validation gì.
Chúng tôi nhận ra: MCP xuất sắc trong việc kết nối tools, nhưng các task R&D phức tạp cần nhiều hơn kết nối tools—cần các quy trình engineering có thể thực thi.
Đ insight đó dẫn chúng tôi phát triển Apidog CLI như một cách tiếp cận tốt hơn—cách xử lý workflow development tốt hơn.
Apidog CLI là gì?
Apidog CLI là một công cụ dòng lệnh để kiểm thử API cho phép bạn chạy test scenarios, quản lý API documentation, và tự động hóa testing workflow trực tiếp từ terminal hoặc CI/CD pipelines. Xây dựng đặc biệt để AI agents quản lý tài nguyên API, nó vượt xa CLI truyền thống cho API testing—cung cấp output có cấu trúc, schema validation, và hướng dẫn next steps mà agents cần để thực thi workflow phức tạp an toàn. Dù bạn đang chạy automated API tests trên GitHub Actions, tạo test cases từ code với Claude Code, hay duy trì test scenarios giữa các projects, Apidog CLI đóng vai trò cầu nối giữa AI agents và infrastructure kiểm thử API của bạn.
Quick Start: Thử Apidog CLI + SKILL
Nếu bạn muốn thử cách tiếp cận được mô tả trong chuỗi này, đây là cách bắt đầu:
# Install Apidog CLI
npm install -g apidog-cli@latest
# Install companion SKILL for AI Agents
apidog skill install
# Check version (need 2.2.5+ for new capabilities)
apidog -v
# Authenticate
Hoặc yêu cầu AI Agent của bạn cài đặt:
Read the instructions and help me install Apidog CLI:
Task Đầu Tiên với Agent
Sau khi cài đặt, đưa cho Agent một task nhỏ và ít rủi ro:
Use Apidog CLI to help me create my first API endpoint in Apidog.
First, check my Apidog CLI setup and list the projects I can access.
Ask me which project to use. After I confirm, create a simple GET /health
endpoint named Health Check with a 200 response example. Validate any
structured input before writing, then read the endpoint back and summarize
Điều này cho bạn một điểm bắt đầu cụ thể: Agent kiểm tra setup, hỏi trước khi viết, tạo một API definition nhỏ, validate trước khi viết, và xác nhận kết quả đã lưu.
Kiến Trúc Cốt Lõi
| Lớp | Trách nhiệm |
|---|---|
| Apidog | Quản lý tài nguyên API và test (docs, schemas, mocks, tests, reports) |
| CLI | Cung cấp execution deterministic (read, validate, write, run) |
| SKILL | Cung cấp task judgment và operation paths (8 Skills companion) |
| AI Branch | Cô lập changes để human review trước merge |
| Agents | Hiểu goals, gọi commands, điều chỉnh theo feedback |
Vòng Lặp An Toàn Hơn cho Agent-Driven Testing
Với AI Branch như lớp bảo mật bên ngoài, workflow hoàn chỉnh như sau:
┌─────────────────────────────────────────────────────────────────────┐
│ AI BRANCH (Lớp Bảo Mật) │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Read Assets │────▶│ Generate │────▶│ Validate │ │
│ │ (CLI get) │ │ (Agent) │ │ (cli-schema)│ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Run Tests │◀────│ Read Back │◀────│ Write │ │
│ │ (apidog run)│ │ (CLI get) │ │ (to AI Br.) │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────┐ │
│ │ Human Review & Merge │ │
│ │ (User confirms before main branch) │ │
│ └──────────────────────────────────────┘ │
Vòng lặp này quan trọng vì nhiều tài nguyên Apidog có cấu trúc. Test cases và test scenarios bao gồm request data, assertions, variable extraction, pre/post processors, step order, và environment references. Nếu Agent đoán cấu trúc, những lỗi nhỏ gây failed writes, display không đầy đủ, hoặc tests không hoạt động như mong đợi.
Cho Agent generate, cho CLI validate, và cho AI Branch cô lập changes đến khi human review.
Tổng Quan Journey Apidog CLI
Chuỗi này ghi lại cách chúng tôi phát triển Apidog CLI như một chiến lược tốt hơn cho workflow R&D API.
Apidog MCP tiếp tục cung cấp kết nối tools theo chuẩn—đó là giá trị và chúng tôi duy trì. Nhưng cho các task liên quan multi-step workflows, validation gates, và structured execution, chúng tôi thấy CLI + SKILL mang đến experience tốt hơn.
Chúng tôi không chỉ thêm commands vào CLI cũ, nơi users chạy automatic API tests tích hợp với CI/CD của họ. Chúng tôi systematcally đưa core capabilities của Apidog vào CLI, làm nó thành một workflow layer cho developers, scripts, và AI Agents.
Sự khác biệt key là nơi complexity sống:
- MCP route: Complexity trong model context và tool selection stage—tốt cho simple tool calls
- CLI + SKILL route: Complexity distributed vào engineering system—tốt hơn cho workflow nâng cao hơn
Kết quả: agent workflows an toàn hơn cho tasks phức tạp, ít tool calls, ít token waste, và error recovery tốt hơn—trong khi MCP vẫn available cho users thích cách đó.
Map Journey Apidog CLI
┌─────────────────────────────────────────────────────────────────┐
│ THE APIDOG CLI + SKILL JOURNEY │
├─────────────────────────────────────────────────────────────────┤
│ │
│ [Problem Discovery] │
│ │ │
│ ┌───┐ │
│ │ 1 │ We Built 126 MCP Tools. Then We Found │
│ └───┘ a Better Approach for Workflows. │
│ │ │
│ ▼ │
│ [Architecture Development] │
│ ┌───┐ │
│ │ 2 │ Why We Developed a Brand-new Apidog CLI │
│ └───┘ │
│ │ │
│ ├──────────────────┬──────────────────┐ │
│ ▼ ▼ ▼ │
│ [Core Philosophy] [Technical Design] │
│ ┌───┐ ┌───┐ ┌───┐ │
│ │ 3 │ CLI Produces │ 4 │ agentHints: │ 5 │ SKILL: Shipping │
│ └───┘ Facts └───┘ Teaching └───┘ Operational │
│ │ │ CLIs │ Experience │
│ │ │ │ │
│ └──────────────┴──────────────────┘ │
│ │ │
│ ▼ │
│ [Validation & Practice] │
│ ┌───┐ ┌───┐ │
│ │ 6 │───────│ 7 │ │
│ └───┘ Numbers│ PRD to Testing │
│ │ │ Loop │
│ ▼ ▼ │
│ [Foundation] [Security Layer] │
│ ┌───┐ ┌───┐ │
│ │ 8 │───────│ 9 │ │
│ └───┘ CI/CD │ AI Branch │
│ │ │ │
│ └────────┘ │
│ │ │
│ ▼ │
│ [Vision] │
│ ┌────┐ │
│ │ 10 │ Spec-First → Skill-First │
│ └────┘ │
│ │
Điều Hướng Journey Nhanh
Phần 1: Phát Hiện Vấn Đề
MCP cung cấp kết nối tools theo chuẩn—nhưng cho R&D workflows phức tạp, chúng tôi phát hiện giới hạn. Agents phải đối mặt đống tools ngẫu nhiên khi tasks liên quan multi-step processes. Post này khám phá bốn structural challenges và tại sao CLI + SKILL tốt hơn cho workflow-heavy tasks.
Phần 2: Phát Triển Kiến Trúc
2. Tại Sao Chúng Ta Phát Triển Apidog CLI Hoàn Toàn Mới
Chúng tôi không bỏ MCP—chúng tôi xây CLI + SKILL để xử lý những gì MCP không tối ưu: complex workflows với validation gates và structured execution. Post này so sánh execution chains và giải thích cách CLI + SKILL distribute complexity vào engineering system trong khi MCP tiếp tục phục vụ mục đích của nó.
Phần 3: Triết Lý Cốt Lõi
3. Quy Tắc Vàng: CLI Tạo Ra Facts, Model Hành Động Theo Facts
Principle cốt lõi: không làm model ghi nhớ tất cả rules—cho rules được execute ở đúng places. Post này introdu `cli-schema validate`, quality gate captures field errors, wrong enums, và structural problems trước khi trở thành failed writes.
Phần 4-5: Thiết Kế Kỹ Thuật
4. agentHints: Dạy CLIs Giao Tiếp với Agents
CLI output truyền thống dành cho humans. Agents cần structured results, failure reasons, và next-step suggestions. `agentHints` biến product experience thành machine-readable guidance—xuất hiện đúng nơi Agents cần đưa ra decisions.
5. SKILL: Đóng Gói Kinh Nghiệm Vận Hành như Code
Một SKILL không chỉ là command reference. Nó là operating guide cho AI Agents: khi dùng command, nào đến trước, fields nào không nên đoán, khi validate, khi read back. SKILL packages workflow knowledge vào guides versionable, evolvable.
Phần 6-7: Validation & Thực Tế
6. Con Số Không Nói Dối: 30% Ít Tool Calls, 25% Ít Tokens
Chúng tôi so MCP vs. CLI + SKILL trên typical tasks. Tool call steps giảm ~30%. Token consumption từ invalid descriptions và retries giảm ~25%. Structural error retries giảm ~40%. Post này phân tích nơi savings đến từ.
7. Từ PRD đến Vòng Lặp Testing: Workflow Hoàn Chỉnh với Apidog CLI
Walk through một ví dụ thực tế: một team có Order Refund PRD và codebase. Xem cách Agent dùng CLI + SKILL để generate OpenAPI, tạo test cases, validate structures, build test scenarios, và run verification—end to end.
Phần 8-9: Foundation & Bảo Mật
8. Tại Sao CI/CD Compatibility Không Thể Thỏa Hiệp cho Agent Tools
Agent-friendliness phải được xây trên CI/CD-friendliness. `apidog run` phục vụ cả hai: CI quan tâm exit codes, report files, stable parameters; Agents quan tâm structured results, failure reasons, next-step suggestions. Một command, nhiều consumers.
9. AI Branch: Thay Đổi Project An Toàn Hơn với AI Agents
Khi Agents modify project resources, security quan trọng. AI Branch cung cấp isolated editing—changes stay trong separate branch đến human review. Điều này ngăn automatic changes ảnh hưởng trực tiếp main branch. Create, review, rồi merge với confidence.
Phần 10: Tầm Nhìn & Tương Lai
10. Spec-First Là Quá Khứ. Chào Mừng Skill-First.
API development đang thay đổi với AI Agents tham gia workflow. Spec-First dành cho human collaboration. Skill-First packages specs, tests, và scenarios thành executable, verifiable skills—complementing existing approaches cho Agent era. Post này phác thảo tương lai và cung cấp concrete getting-started steps.
Key Takeaways (TL;DR)
| Insight | Ý Nghĩa |
|---|---|
| MCP và CLI + SKILL phục vụ needs khác nhau | MCP kết nối tools; CLI + SKILL execute workflows—dùng cái nào phù hợp task |
| Complexity thuộc engineering, không context | 126 tools × 500 tokens = 50,000 tokens burden cho complex workflows |
| `cli-schema validate` là quality gate | Catch errors locally, không qua failed writes |
| `agentHints` hướng dẫn next steps | Ngăn Agents viết dựa trên "imagination" |
| SKILL packages operational experience | Không chỉ commands—workflow wisdom cho Agents |
| CI/CD vẫn là foundation | Agent features added on top, không replacing CI |
| AI Branch cung cấp security layer | Isolated editing + human review trước merge |
Bắt Đầu Đọc
Sẵn sàng dive in? Bắt đầu với Post 1: Chúng Ta Đã Xây 126 Công Cụ MCP. Sau Đó Chúng Ta Phát Hiện Giải Pháp Tốt Hơn cho Workflows.
Download Apidog để design, mock, test, và document APIs trong một workspace. Tìm hiểu thêm về Apidog CLI cho command-line API testing, CI automation, và AI Agent workflows.