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

Đây là một loạt bài 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. Hãy đọc theo thứ tự hoặc chuyển đến bất kỳ bài viết nào bạn quan tâm:

Đừng bắt mô hình ghi nhớ tất cả các quy tắc—hãy để các quy tắc được thực thi đúng chỗ. cli-schema validate biến Schema từ kiến thức thành một cổng chất lượng.

Nguyên tắc cốt lõi: Hãy để các quy tắc được thực thi đúng chỗ.

Chúng tôi đã đúc kết một nguyên tắc cốt lõi từ kinh nghiệm của mình:

Đừng bắt mô hình ghi nhớ tất cả các quy tắc. Hãy để các quy tắc được thực thi đúng chỗ.

Điều này tương tự như một bài học từ đánh giá Agent:

Trong Apidog CLI + SKILL:

Hãy để CLI xác thực cấu trúc. Hãy để Agent tạo nội dung.

Vấn đề với bộ nhớ của mô hình

Khi một AI Agent giúp tạo hoặc cập nhật tài nguyên Apidog, phần rủi ro không chỉ là tạo nội dung.

Phần rủi ro là việc ghi nội dung được tạo vào một dự án thực mà không có đủ cấu trúc hoặc xác minh.

Tài nguyên Apidog có cấu trúc. Hãy xem xét những gì một trường hợp kiểm thử hoặc kịch bản kiểm thử bao gồm:

Nếu một Agent đoán cấu trúc:

• Tên trường sai → Ghi thất bại
• Giá trị enum không hợp lệ → Server từ chối
• Thiếu trường bắt buộc → Tài nguyên không đầy đủ
• Sai kiểu dữ liệu → Lỗi hiển thị UI
• Lồng ghép không chính xác → Các kiểm thử không hoạt động như mong đợi

cli-schema validate: Cổng chất lượng

Hiện thân trực tiếp nhất của nguyên tắc của chúng tôi là cli-schema validate.

apidog cli-schema validate test-scenario-update --file ./scenario-update.json

Khi một Agent muốn ghi hoặc cập nhật một kịch bản kiểm thử, việc để AI tạo các cấu trúc bước phức tạp rất dễ gây lỗi.

Lệnh validate:

• Xác nhận tên trường
• Kiểm tra tính hợp lệ của cấu trúc
• Xác minh hiệu lực của giá trị enum
• Xác thực các ràng buộc kiểu

Tất cả trước khi bắt đầu yêu cầu ghi.

Các lỗi phổ biến mà cli-schema bắt được

Dưới đây là các ví dụ thực tế về các lỗi mà Agent thường mắc phải—và cli-schema validate bắt được:

Đây không phải là lý thuyết. Chúng tôi đã phát hiện ra chúng thông qua các tương tác Agent thực tế.

Mỗi lỗi sẽ gây ra:

• Một yêu cầu ghi thất bại
• Một phản hồi lỗi API
• Agent bối rối về điều gì đã sai
• Nhiều lần thử lại
• Lãng phí token cho các cuộc gọi lặp lại

Với cli-schema validate, những lỗi này được bắt cục bộ, trước khi thực hiện cuộc gọi mạng.

Triết lý thiết kế

Hãy xem xét các lựa chọn thay thế:

Giải pháp thay thế 1: Viết quy tắc vào prompt

Nếu chúng ta viết tất cả các quy tắc trường vào prompt của Agent:

• Mọi tên trường được ghi lại
• Mọi giá trị enum được liệt kê
• Mọi ràng buộc kiểu được giải thích
• Mọi cấu trúc lồng ghép được mô tả

Kết quả: Gánh nặng ngữ cảnh khổng lồ.

Một lược đồ kịch bản kiểm thử toàn diện có thể dễ dàng yêu cầu hơn 5.000 token mô tả. Đó là ngữ cảnh mà mô hình phải mang theo cho mọi tác vụ, ngay cả khi hầu hết các quy tắc không liên quan.

Giải pháp thay thế 2: Dựa vào bộ nhớ của mô hình

Nếu chúng ta dựa vào mô hình để "biết" cấu trúc chính xác:

• Mô hình được huấn luyện trên một số mẫu API
• Nhưng không cụ thể trên các lược đồ Apidog
• Tên trường khác nhau giữa các sản phẩm
• Giá trị enum dành riêng cho sản phẩm

Kết quả: Tỷ lệ lỗi cao.

Mô hình không có bộ nhớ hoàn hảo về các quy ước dành riêng cho Apidog. Nó sẽ đoán—và các dự đoán sẽ sai.

Cách tiếp cận tốt hơn: Xác thực cục bộ

Hãy để Agent tạo các bản nháp. Hãy để CLI thực thi xác thực trước khi ghi.

# Agent tạo JSON
# (Agent không cần ghi nhớ tất cả các quy tắc)

# CLI xác thực
apidog cli-schema validate test-case-create --file ./test-case-create.json

# CLI xuất các lỗi cụ thể nếu có
# Agent điều chỉnh dựa trên các lỗi

# Chỉ các ghi hợp lệ mới được tiến hành
apidog test-case create --project <projectId> --file ./test-case-create.json

Chuyển đổi lược đồ

cli-schema validate chuyển đổi ý nghĩa của Schema:

Các vấn đề không bị tiêu tốn vào các yêu cầu mạng qua lại vô nghĩa.

Các kiểm tra chất lượng được hoàn thành thông qua các lệnh cục bộ.

Ví dụ thực tế

Hãy cùng xem xét một quy trình làm việc thực tế:

# Agent đọc endpoint
apidog endpoint get <endpointId> --project <projectId>

# Agent tạo JSON của trường hợp kiểm thử
# (Tạo ./test-case-create.json)

# Xác thực trước khi ghi
apidog cli-schema validate test-case-create --file ./test-case-create.json

Nếu xác thực thành công:

apidog test-case create --project <projectId> --file ./test-case-create.json

Nếu xác thực thất bại:

Lỗi: Trường "assertions[0].comparator" có giá trị không hợp lệ "contains"
Các giá trị hợp lệ: equal, not_equal, greater, less, include, not_include, exists, not_exists

Lỗi: Trường "extractors[0].type" có giá trị không hợp lệ "global"
Các giá trị hợp lệ: globals, environment, collection, local

Gợi ý: Sửa các trường này và xác thực lại trước khi ghi.

Agent:

1. Đọc các lỗi cụ thể
2. Hiểu chính xác điều gì đã sai
3. Điều chỉnh tệp JSON
4. Chạy lại xác thực
5. Chỉ tiếp tục khi hợp lệ

Không có ghi thất bại. Không có thử lại bối rối. Không lãng phí token.

Bài học rộng hơn

Nguyên tắc này mở rộng ra ngoài việc xác thực.

Các quy tắc mang tính xác định → Hệ thống kỹ thuật

Đánh giá ngữ nghĩa → Agent

Tiếp theo là gì

Bây giờ chúng ta đã thiết lập nguyên tắc xác thực, câu hỏi tiếp theo là:

Sau khi xác thực, CLI hướng dẫn Agent đến bước tiếp theo như thế nào?

Trong Phần 4, agentHints: Dạy CLI giao tiếp với Agent, chúng ta sẽ khám phá cách đầu ra có cấu trúc với các gợi ý bước tiếp theo biến CLI từ một công cụ thực thi lệnh thành một công cụ điều hướng quy trình làm việc.

Các điểm chính

• Nguyên tắc cốt lõi: các quy tắc thuộc về việc thực thi, không phải ngữ cảnh
• cli-schema validate là cổng chất lượng trước khi ghi
• Các lỗi phổ biến: tên trường sai, enum không hợp lệ, kiểu sai
• Xác thực bắt lỗi cục bộ, tiết kiệm các vòng lặp mạng
• Schema chuyển đổi từ "kiến thức để ghi nhớ" thành "cổng để vượt qua"
• Các quy tắc mang tính xác định → kỹ thuật; đánh giá ngữ nghĩa → Agent

Tải xuống Apidog để thiết kế, mô phỏng, 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à quy trình làm việc của AI Agent.