Một tác nhân mã hóa AI đã chạy một tập lệnh, thấy nó thành công, sau đó chứng kiến một bảng cơ sở dữ liệu sản xuất biến mất. Bài viết phân tích sự cố trên Hacker News đã lan truyền với tiêu đề sắc bén: “AI không xóa cơ sở dữ liệu của bạn, bạn đã làm điều đó.” Luận điểm này được chấp nhận vì nó đúng. Tác nhân đã tuân theo định nghĩa công cụ, công cụ đó đã truy cập một endpoint thực, endpoint đó không có cơ chế bảo vệ, và một con người đã giao quyền điều khiển cho một quy trình không tạm dừng để hỏi liệu DELETE FROM users có vẻ đáng ngờ hay không. Một chủ đề r/ClaudeAI riêng biệt đã kể một câu chuyện tương tự từ một góc độ khác: một tác nhân trong một vòng lặp thanh toán đã tiêu tốn hàng trăm đô la token trước khi bất kỳ ai nhận ra. Bề mặt khác nhau, cùng một loại lỗi. Vấn đề không phải là mô hình ngu ngốc. Vấn đề là không ai kiểm tra API.
TL;DR (Tóm tắt)
Các tác nhân thất bại trong môi trường sản xuất khi các công cụ của chúng không có cơ chế bảo vệ phía API: thiếu giới hạn tốc độ, không có tính bất biến (idempotency), xóa nóng (hot deletes), schema bị lỗi. Bạn khắc phục điều này bằng bốn bước: kiểm tra hợp đồng định nghĩa công cụ của tác nhân so với đặc tả OpenAPI của bạn, chạy một máy chủ giả lập cho các endpoint phá hoại, thực thi ngân sách và khóa bất biến cho từng tác nhân, và phát lại các kịch bản thất bại trong CI. Apidog cung cấp cho bạn khả năng nhập OpenAPI, các bản giả lập (mocks), và trình chạy kịch bản để thực hiện tất cả những điều này từ một dự án duy nhất.
Giới thiệu
Một năm trước, "kiểm thử tác nhân AI" có nghĩa là nhập prompt cho Claude hoặc GPT và đánh giá câu trả lời. Đó không còn là tiêu chuẩn nữa. Các tác nhân ngày nay gọi các hàm, các hàm đó truy cập API của bạn, và API của bạn giao tiếp với các cơ sở dữ liệu thực, bộ xử lý thanh toán và dịch vụ bên thứ ba. Một định nghĩa công cụ kém hoặc thiếu giới hạn tốc độ không phải là vấn đề về phong cách. Đó là một sự cố sản xuất có tên bạn trên đó.
Câu chuyện lan truyền trên Hacker News tháng này đã ghi lại sự thay đổi. Tác giả lập luận rằng AI không xóa cơ sở dữ liệu; con người đã làm điều đó, bằng cách cấp quyền ghi cho tác nhân mà không đặt bất kỳ biện pháp kiểm soát nào giữa mô hình và dữ liệu. Chủ đề này đã bùng nổ vì mọi nhà phát triển đọc nó đều nghĩ, “Tôi suýt nữa đã triển khai thứ đó.” Vài tuần trước, một bài đăng trên Reddit đã mô tả một vòng lặp thanh toán nơi một tác nhân đã thử lại một lệnh gọi thất bại nhiều lần đến mức hóa đơn vượt quá 800 euro trước khi bất kỳ ai nhận ra. Cùng một nguyên nhân gốc rễ: niềm tin đặt sai lớp.
Bạn có thể khắc phục điều này. Lớp mô hình quan trọng, nhưng lớp API là nơi bạn ngăn chặn thiệt hại. Bài viết này sẽ chỉ cho bạn cách kiểm thử tích hợp API của tác nhân AI từ đầu đến cuối. Chúng tôi sẽ đề cập đến bốn cơ chế bảo vệ mà mọi thiết lập tác nhân-API cần, hướng dẫn chi tiết quy trình làm việc từng bước với Apidog để mô phỏng các endpoint phá hoại, và kết thúc bằng các kỹ thuật nâng cao như phát hiện sai lệch schema và phân tách khóa kép. Bạn sẽ có được các mẫu cụ thể mà bạn có thể sao chép vào kho lưu trữ của mình ngay hôm nay. Tải Apidog trước khi bắt đầu để bạn có thể làm theo các bước thiết lập máy chủ giả lập.
Tại sao lỗi tác nhân lại giống lỗi API
Đọc đủ các bài phân tích sự cố sau khi tác nhân gặp lỗi và một mô hình sẽ xuất hiện: mô hình không phải là nhân vật chính. API mới là.
Lấy ví dụ về prompt injection. Người dùng tải lên một tệp PDF với các hướng dẫn ẩn, tác nhân đọc nó, và lệnh gọi công cụ tiếp theo sẽ đến endpoint /admin/users của bạn với delete_all=true. Mô hình không chọn điều này; nó tuân theo các hướng dẫn mà nó không có lý do gì để không tin tưởng. Cách khắc phục không phải là làm cứng prompt. Cách khắc phục là xây dựng một API không để lộ delete_all=true cho một token đến từ phiên ngữ cảnh người dùng. OWASP gọi đây là LLM01 trong danh sách 10 mối đe dọa hàng đầu của LLM, và biện pháp giảm thiểu là ủy quyền phía API, không phải kỹ thuật prompt.
Lấy ví dụ về các schema công cụ bị lỗi. Đặc tả OpenAPI của bạn nói rằng amount là một số nguyên tính bằng cent. Định nghĩa công cụ của tác nhân nói rằng amount là một số thập phân tính bằng đô la. Ba tháng sau, ai đó hoàn lại 19 cent thành 19 đô la và bạn phát hiện ra sự không khớp này từ bộ phận kế toán. Mô hình không sai; mô hình đã sử dụng schema bạn cung cấp. Schema đã bị lệch so với API. Không ai kiểm tra hợp đồng.
Lấy ví dụ về việc thiếu giới hạn tốc độ. Một tác nhân trong vòng lặp thử lại đã tấn công endpoint email giao dịch của bạn hàng nghìn lần trong hai phút vì bộ lập kế hoạch của tác nhân liên tục đánh dấu bước đó là "chưa thành công". Mỗi lần thử lại đều tốn tiền. Mỗi lần thử lại đều xếp hàng một email thực. Đến lúc bạn thức dậy, nhà cung cấp của bạn đã gắn cờ tài khoản của bạn và khách hàng của bạn đang bị spam. Mô hình không có ý đồ xấu. Mô hình hoạt động từ một công cụ không có giới hạn.
Lấy ví dụ về việc thiếu tính bất biến (idempotency). Tác nhân gọi POST /payments để tính phí khách hàng, gặp lỗi timeout mạng, thử lại vì bộ lập kế hoạch nghĩ rằng lệnh gọi đã thất bại, và bây giờ khách hàng bị tính phí hai lần. Lớp tác nhân không thể biết liệu lệnh gọi ban đầu có thành công hay không; API không cung cấp cách để hỏi. Khóa bất biến giải quyết vấn đề này chỉ trong năm dòng mã máy chủ, nhưng bạn phải tự viết chúng.
Điểm chung: trong mỗi sự cố này, tác nhân đang làm chính xác những gì các công cụ của nó bảo nó làm. Các công cụ chính là API. Vì vậy, khi bạn kiểm toán nơi độ tin cậy của tác nhân bị hỏng, hãy xem xét hợp đồng API trước, sau đó là cơ chế điều khiển tác nhân, và gần như không bao giờ là chính mô hình. Việc thay đổi cách nhìn này quan trọng vì nó cho bạn biết nên đầu tư vào đâu. Bạn không cần một mô hình thông minh hơn. Bạn cần các API có thể kiểm thử được với các cơ chế bảo vệ đã được bật.
Bốn cơ chế bảo vệ mà mọi tích hợp tác nhân-API cần
Bốn biện pháp kiểm soát phân biệt các thiết lập tác nhân thất bại an toàn với các thiết lập thất bại tốn kém. Nếu bạn chỉ có thời gian để thêm một biện pháp trong quý này, hãy bắt đầu từ đầu. Nếu bạn có thể thực hiện cả bốn, bạn đã bao quát hơn 90 phần trăm các kịch bản sự cố mà bạn sẽ thấy vào năm 2026.
1. Kiểm thử hợp đồng schema công cụ
Đặc tả OpenAPI của bạn là nguồn đáng tin cậy cho API của bạn. Tác nhân của bạn có một định nghĩa công cụ riêng biệt, thường được viết thủ công hoặc sao chép từ tài liệu. Hai thành phần này liên tục bị lệch. Kiểm thử hợp đồng sẽ làm thất bại quá trình xây dựng CI của bạn ngay khi chúng khác biệt.
import json
from jsonschema import Draft202012Validator
def validate_tool_against_openapi(tool_def: dict, openapi_spec: dict) -> list[str]:
"""Return a list of mismatch errors, empty list = pass."""
errors = []
op = openapi_spec["paths"][tool_def["path"]][tool_def["method"].lower()]
api_schema = op["requestBody"]["content"]["application/json"]["schema"]
tool_schema = tool_def["input_schema"]
api_props = set(api_schema.get("properties", {}).keys())
tool_props = set(tool_schema.get("properties", {}).keys())
for missing in api_props - tool_props:
if missing in api_schema.get("required", []):
errors.append(f"Tool missing required field: {missing}")
for extra in tool_props - api_props:
errors.append(f"Tool defines field not in API: {extra}")
for prop, api_def in api_schema.get("properties", {}).items():
if prop in tool_schema.get("properties", {}):
tool_def_prop = tool_schema["properties"][prop]
if api_def.get("type") != tool_def_prop.get("type"):
errors.append(
f"Type mismatch on {prop}: API={api_def.get('type')} "
f"tool={tool_def_prop.get('type')}"
)
return errors
Chạy mã này trên mỗi PR chạm đến đặc tả OpenAPI hoặc định nghĩa công cụ. Làm thất bại quá trình xây dựng nếu danh sách không trống. Kiểm tra duy nhất này đã có thể phát hiện lỗi float-vs-cents trong phần trước đó vài tháng trước khi bất kỳ khoản hoàn tiền nào được thực hiện.
2. Môi trường sandbox và giả lập cho các endpoint phá hoại
Các tác nhân cần một nơi để thực hành. Chúng không bao giờ nên thực hành trong môi trường sản xuất. Mô hình này rất đơn giản: mọi endpoint làm thay đổi trạng thái đều có một bản giả lập tương đương trả về cùng dạng phản hồi mà không thực hiện công việc. Vòng lặp phát triển tác nhân của bạn sử dụng các bản giả lập. Các bài kiểm thử staging của bạn sử dụng cơ sở dữ liệu sandbox. Môi trường sản xuất vẫn không bị ảnh hưởng cho đến khi một con người chấp thuận triển khai.
Apidog tạo các bản giả lập trực tiếp từ đặc tả OpenAPI, bao gồm các giá trị trường thực tế được điều khiển bởi các mẫu Faker. Bạn trỏ URL cơ sở API của tác nhân của mình đến máy chủ giả lập, chạy hàng trăm lần lặp prompt của bạn, và theo dõi cách nó hoạt động. Nếu tác nhân tiếp tục cố gắng PUT đến /users/{id}/delete vì nó hiểu sai tài liệu, bản giả lập sẽ phát hiện ra. Bảng người dùng trong môi trường sản xuất sẽ không bao giờ thấy lỗi này. Xem phát triển hợp đồng trước để biết mẫu rộng hơn mà điều này phù hợp.
3. Khóa bất biến và xóa mềm cho các hoạt động không thể đảo ngược
Mọi endpoint ghi mà tác nhân của bạn có thể gọi đều phải chấp nhận một khóa bất biến. Mọi thao tác xóa mặc định nên là xóa mềm với một đường dẫn xóa cứng riêng biệt do con người ủy quyền.
const idempotencyCache = new Map();
function idempotency(req, res, next) {
const key = req.headers['idempotency-key'];
if (!key) {
return res.status(400).json({ error: 'Missing Idempotency-Key header' });
}
if (idempotencyCache.has(key)) {
const cached = idempotencyCache.get(key);
return res.status(cached.status).json(cached.body);
}
const originalJson = res.json.bind(res);
res.json = function (body) {
idempotencyCache.set(key, { status: res.statusCode, body });
setTimeout(() => idempotencyCache.delete(key), 24 * 60 * 60 * 1000);
return originalJson(body);
};
next();
}
app.post('/payments', idempotency, createPayment);
Tác nhân tạo một UUID cho mỗi thao tác logic và sử dụng lại nó khi thử lại. API của bạn trả về phản hồi được lưu trữ trong lần gọi thứ hai thay vì tính phí hai lần. Mẫu tương tự này bảo vệ chống gửi trùng lặp trong API nhắn tin, tạo hàng trùng lặp trong CRM, và hầu hết các kịch bản "tác nhân thử lại và bây giờ chúng ta có một mớ hỗn độn" khác.
4. Giới hạn ngân sách cho từng tác nhân
Mỗi tác nhân đều có một ngân sách. Ngân sách token, ngân sách yêu cầu, ngân sách tiền tệ, ngân sách thời gian. Khi ngân sách cạn kiệt, tác nhân sẽ dừng lại. Không có ngoại lệ. Sự cố Reddit 800 euro xảy ra vì không ai đặt giới hạn cho một vòng lặp ngoài tầm kiểm soát, và vào thời điểm con người kiểm tra, thiệt hại đã xảy ra.
Một middleware ngân sách bọc quanh API gateway của bạn có thể theo dõi:
- Số lượng token mỗi phiên, giới hạn 50.000
- Số lượng lệnh gọi API mỗi phút, giới hạn 30
- Tổng chi tiêu tích lũy tính bằng cent, giới hạn 500
- Độ sâu lệnh gọi công cụ, giới hạn 10 lệnh gọi lồng nhau
Khi bất kỳ giới hạn nào bị vượt quá, trả về HTTP 429 với tiêu đề Retry-After có cấu trúc và tiêu đề X-Budget-Exceeded nêu rõ giới hạn. Bộ lập kế hoạch của tác nhân sau đó có thể chuyển vấn đề lên con người hoặc hủy bỏ tác vụ. Kết hợp điều này với việc ghi nhật ký để bạn có thể thấy tác nhân nào đang vượt quá giới hạn và điều chỉnh cho phù hợp.
Bốn biện pháp kiểm soát này kết hợp với nhau. Kiểm thử hợp đồng phát hiện các lỗi schema rõ ràng. Bản giả lập phát hiện các lỗi phá hoại. Tính bất biến phát hiện các cơn bão thử lại. Ngân sách phát hiện các vòng lặp ngoài tầm kiểm soát. Cùng nhau, chúng biến "tác nhân đã làm điều gì đó kinh khủng" thành "tác nhân gặp lỗi 429, ghi nhật ký vấn đề và yêu cầu trợ giúp." Đó là tiêu chuẩn.
Kiểm thử lệnh gọi API của tác nhân với Apidog
Bây giờ là phần thực hành. Dưới đây là cách thiết lập một quy trình làm việc kiểm thử tác nhân-API hoàn chỉnh trong Apidog. Bạn sẽ cần đặc tả OpenAPI cho API mà tác nhân của bạn gọi, cộng với danh sách các định nghĩa công cụ của tác nhân.
Bước 1: Nhập đặc tả OpenAPI
Mở Apidog, tạo một dự án mới, và nhập tệp OpenAPI 3.x của bạn. Apidog phân tích mọi đường dẫn, schema, và ví dụ, sau đó tạo các endpoint tương ứng trong dự án. Nếu API của bạn chưa được tài liệu hóa trong OpenAPI, đây là thời điểm để làm điều đó; độ tin cậy của tác nhân phụ thuộc vào việc có một nguồn sự thật duy nhất mà cả con người và tác nhân AI của bạn đều đọc. Hướng dẫn quy trình làm việc API thiết kế-trước sẽ hướng dẫn bạn điều này nếu bạn bắt đầu từ đầu.
Bước 2: Định nghĩa phản hồi giả lập cho các endpoint phá hoại
Tìm mọi endpoint làm thay đổi dữ liệu: POST, PUT, PATCH, DELETE. Với mỗi endpoint, nhấp vào đó và thêm một phản hồi giả lập. Apidog có thể tự động tạo các bản giả lập thực tế từ schema của bạn, nhưng bạn nên ghi đè các giá trị trường để chúng trông giống dữ liệu kiểm thử, chứ không phải dữ liệu sản xuất. Sử dụng các tiền tố như mock_user_ và dấu thời gian vào năm 1970 để mọi rò rỉ đều dễ dàng nhận thấy trong nhật ký.
Khởi động máy chủ giả lập. Apidog cung cấp cho bạn một URL ổn định như https://mock.apidog.com/m1/your-project-id/. Trỏ URL cơ sở API của tác nhân của bạn đến máy chủ giả lập trong quá trình phát triển. Bây giờ, DELETE /users/{id} của bạn sẽ trả về 200 với một payload người dùng giả, và cơ sở dữ liệu thực của bạn được an toàn. Xem phát triển hợp đồng trước để biết mẫu rộng hơn mà điều này phù hợp.
Bước 3: Viết một kịch bản mô phỏng chuỗi lệnh gọi của tác nhân
Các kịch bản Apidog cho phép bạn xâu chuỗi các lệnh gọi API với các xác nhận, tương tự như cách một bộ kiểm thử hoạt động. Đối với một tác nhân phân loại phiếu hỗ trợ, kịch bản có thể là:
- POST
/auth/tokenvới thông tin xác thực kiểm thử, lấy token bearer - GET
/tickets?status=openvới token, lấy ID của phiếu đầu tiên - POST
/tickets/{id}/triagevới một danh mục, xác nhận 200 và lấy trường assigned-to - POST
/notificationsvới một tin nhắn mẫu, xác nhận nội dung tin nhắn khớp với biểu thức chính quy (regex)
Bạn đang thực hiện diễn tập những gì tác nhân sẽ làm, trên máy chủ giả lập, với các xác nhận ở mỗi bước. Nếu một nhà phát triển thay đổi schema phiếu và biểu thức chính quy không còn khớp, kịch bản sẽ thất bại và bạn sẽ biết trước khi tác nhân tiếp cận môi trường sản xuất. Xem kiểm thử API cho kỹ sư QA để biết sổ tay kiểm thử kịch bản rộng hơn.
Bước 4: Chạy từ CI
Apidog cung cấp một CLI chạy các kịch bản từ GitHub Action, GitLab pipeline, hoặc bất kỳ trình chạy CI nào. Lệnh trông như apidog run -t scenario-id --env test. Tích hợp nó vào pipeline PR của bạn để mọi thay đổi đối với đặc tả OpenAPI hoặc định nghĩa công cụ của tác nhân sẽ kích hoạt việc phát lại toàn bộ kịch bản.
Bước 5: So sánh hai phiên bản mô hình cạnh nhau
Khi bạn đang đánh giá xem có nên nâng cấp từ mô hình này sang mô hình khác hay không, bạn muốn biết liệu các lệnh gọi công cụ của mô hình mới có hoạt động giống nhau trên cùng các kịch bản hay không. Chạy tác nhân với cùng kịch bản Apidog bằng mô hình A, ghi lại dấu vết. Chạy lại với mô hình B, ghi lại dấu vết. So sánh các phần thân yêu cầu. Những bất ngờ sẽ xuất hiện ngay lập tức: mô hình B truyền một giá trị priority khác, hoặc bỏ qua một trường, hoặc sử dụng một định dạng khác cho ngày tháng. Bạn phát hiện sự thay đổi hành vi trước khi nó được triển khai. Đây là một trong những mẫu được đề cập trong tích hợp API GPT-5.5, nơi việc đánh giá hành vi mô hình mới là một nhu cầu thường xuyên.
Toàn bộ quy trình làm việc mất khoảng một giờ để thiết lập lần đầu và vài phút cho mỗi lần chạy sau đó. Lợi ích là mọi thay đổi đối với API hoặc các công cụ tác nhân của bạn đều được kiểm tra so với cùng một tiêu chuẩn mong đợi.
Kỹ thuật nâng cao và mẹo chuyên nghiệp
Một vài mẫu mà các nhóm có kinh nghiệm thường sử dụng sau khi đã có những kiến thức cơ bản.
Đặt nhiệt độ về 0 trong các bài kiểm thử. Các tác nhân không xác định tạo ra các lỗi kiểm thử không xác định. Khi bạn đang kiểm thử hành vi gọi công cụ, hãy đặt nhiệt độ về 0 và gieo mầm cho bất kỳ nguồn ngẫu nhiên nào. Bạn đang kiểm thử lớp công cụ, không phải lớp sáng tạo.
Chụp nhanh dấu vết lệnh gọi công cụ. Mỗi lần chạy kiểm thử sẽ ghi lại chuỗi chính xác các lệnh gọi công cụ mà tác nhân đã thực hiện, cùng với các đối số. So sánh với đường cơ sở trước đó. Nếu tác nhân đột nhiên bắt đầu gọi /users hai lần thay vì một lần, bạn muốn biết điều đó ngay lập tức, không phải ba tuần sau khi hóa đơn đến.
Không bao giờ cấp thông tin xác thực sản xuất cho tác nhân. Các tác nhân nhận tài khoản dịch vụ có phạm vi giới hạn. Thông tin xác thực sản xuất nằm trong kho bảo mật (vaults), không phải trong các tệp .env mà tác nhân có thể đọc. Nếu một tác nhân cần gọi một endpoint sản xuất, nó sẽ đi qua một proxy ký yêu cầu bằng các token có thời hạn ngắn.
Tách biệt khóa API đọc và ghi. Hầu hết các tác vụ của tác nhân chủ yếu là đọc. Cấp khóa chỉ đọc cho những tác vụ đó. Khóa ghi được dành riêng cho các tác vụ có cổng phê duyệt của con người. Thay đổi đơn lẻ này làm giảm một nửa phạm vi ảnh hưởng của một tác nhân bị xâm nhập.
Sử dụng HTTP 423 Locked cho các endpoint cần phê duyệt của con người. Khi một tác nhân cố gắng gọi một endpoint yêu cầu xác nhận của con người, hãy trả về 423 với trường confirmation_url. Bộ lập kế hoạch của tác nhân thấy trạng thái bị khóa, hiển thị URL cho con người và chờ. Điều này rõ ràng hơn 403, vì 403 ngụ ý "bạn không thể làm điều này" trong khi 423 ngụ ý "bạn chưa thể làm điều này".
Thất bại đóng khi schema bị lệch. Nếu định nghĩa công cụ của tác nhân không khớp với đặc tả OpenAPI của bạn, quá trình xây dựng sẽ thất bại. Đừng chỉ đưa ra cảnh báo. Hãy đưa ra lỗi. Chi phí của một vài lần xây dựng thất bại bổ sung thấp hơn nhiều so với một sự cố sản xuất.
Những lỗi phổ biến cần tránh:
- Ghi cứng URL giả lập vào các prompt của tác nhân. Sử dụng biến môi trường để cùng một prompt chạy trên môi trường giả lập, staging và sản xuất.
- Bỏ qua tính bất biến trên các endpoint "nhỏ". Mọi thao tác ghi đều cần nó. Gửi email cũng không ngoại lệ.
- Ghi nhật ký toàn bộ nội dung yêu cầu trong môi trường sản xuất. PII rò rỉ vào ngăn xếp quan sát của bạn. Thay thế token, email và định danh trước khi chúng đến nhật ký.
- Cho phép tác nhân truy cập trực tiếp vào cơ sở dữ liệu. Luôn đi qua API. API là nơi các bài kiểm thử của bạn tồn tại.
- Tin tưởng điểm tự tin của tác nhân. Điểm số phản ánh sự chắc chắn của mô hình về câu trả lời, không phải sự an toàn của API. Một tác nhân tự tin 99 phần trăm vẫn có thể gọi sai endpoint.
Nếu tác nhân của bạn giao tiếp với các dịch vụ nội bộ không nằm sau một API gateway duy nhất, các mẫu kiểm thử microservice bao gồm cách phân tán các bài kiểm thử kịch bản trên các dịch vụ.
Các lựa chọn thay thế và công cụ
Bạn có nhiều lựa chọn. Dưới đây là so sánh công bằng về bốn phương pháp phổ biến.
| Phương pháp | Thời gian thiết lập | Ưu điểm | Nhược điểm | Tốt nhất cho |
|---|---|---|---|---|
| Kiểm thử đơn vị thủ công | Thấp | Kiểm soát hoàn toàn, không bị khóa nhà cung cấp | Bảo trì cao, dễ lệch khỏi API thực | Dự án nhỏ, nhóm phát triển độc lập |
| Cơ chế đánh giá LangSmith / LangGraph | Trung bình | Phát lại dấu vết tích hợp, số liệu nhận biết mô hình | Nặng về phía tác nhân, nhẹ về phía API | Các nhóm AI chuyên đánh giá |
| Postman + Postbot | Trung bình | Giao diện quen thuộc, thư viện mẫu lớn | Máy chủ giả lập là tiện ích trả phí, cú pháp kịch bản lỗi thời | Các nhóm đã đầu tư vào Postman |
| Kịch bản Apidog + giả lập | Trung bình | OpenAPI gốc, giả lập miễn phí, CLI kịch bản cho CI | Nhận diện thương hiệu kém hơn Postman | Các nhóm muốn một công cụ duy nhất cho thiết kế, giả lập và kiểm thử |
Tóm tắt chân thực: nếu bạn đang sử dụng LangSmith, hãy tiếp tục làm những gì hiệu quả ở phía tác nhân và thêm một lớp kiểm thử API riêng biệt. Nếu bạn đã vượt qua giới hạn giá của Postman hoặc mô hình giả lập của nó, Apidog là một sự thay thế mạnh mẽ. Nếu bạn đang bắt đầu mới, hãy chọn công cụ xử lý OpenAPI, giả lập và kịch bản trong một dự án, vì đó là nơi 80 phần trăm thời gian kiểm thử tác nhân-API của bạn sẽ dành cho.
Một số nhóm kết hợp các công cụ này. Họ giữ LangSmith để đánh giá cấp độ prompt và sử dụng Apidog cho các bài kiểm thử hợp đồng phía API và phát lại kịch bản. Điều đó hoạt động tốt; các công cụ phục vụ các lớp khác nhau.
Các trường hợp sử dụng thực tế
Tác nhân cập nhật các hàng cơ sở dữ liệu sản xuất. Một nhóm hỗ trợ khách hàng đã xây dựng một tác nhân cập nhật các trường tài khoản từ các phiếu hỗ trợ. Trước khi triển khai, họ đã cấu hình mọi endpoint ghi yêu cầu một khóa bất biến và chạy 200 lần phát lại kịch bản trong Apidog đối với một cơ sở dữ liệu sandbox. Các lần phát lại đã phát hiện hai trường hợp tác nhân cố gắng đặt subscription_status thành một chuỗi không có trong enum. Họ đã thêm xác thực schema và triển khai mà không gặp sự cố nào.
Tác nhân gọi API thanh toán. Một nhóm công nghệ tài chính xây dựng tác nhân hoàn tiền tự động đã đặt các giới hạn cứng: tối đa 5 lần hoàn tiền mỗi phiên, tối đa 50 đô la mỗi lần hoàn tiền, yêu cầu tính bất biến trên mỗi lệnh gọi. Họ đã chạy bộ kiểm thử hợp đồng đối với OpenAPI của Stripe trên mỗi PR. Sau sáu tháng, họ đã xử lý 12.000 khoản hoàn tiền mà không có phí trùng lặp nào.
Tác nhân phân loại các vấn đề trên GitHub. Một nhóm nền tảng đã xây dựng một tác nhân phân loại vấn đề lấy cảm hứng từ Clawsweeper. Họ đã giả lập API GitHub trong Apidog, chạy tác nhân qua 50 bài kiểm thử kịch bản bao gồm các trường hợp đặc biệt (vấn đề đã xóa, thiếu nhãn, dữ liệu người dùng sai định dạng), và tìm thấy ba sự cố trước khi ra mắt. Tác nhân hiện đang xử lý việc phân loại trên một kho lưu trữ công khai với 5.000 vấn đề đang mở.
Kết luận
Nếu bạn rút ra một điều từ hướng dẫn này, hãy nhớ: tác nhân không phải là vấn đề. API mới là vấn đề, hoặc là giải pháp, tùy thuộc vào việc bạn đã kiểm thử nó hay chưa.
Năm điểm chính:
- Coi schema công cụ là hợp đồng và chạy các bài kiểm thử hợp đồng trong CI.
- Giả lập các endpoint phá hoại cho mọi vòng lặp phát triển tác nhân.
- Yêu cầu khóa bất biến trên mọi thao tác ghi mà tác nhân của bạn có thể gọi.
- Đặt giới hạn ngân sách cho từng tác nhân và đóng khi chúng bị vượt quá.
- Phát lại các kịch bản trên mỗi PR chạm đến API hoặc định nghĩa công cụ.
Các sự cố lan truyền trong năm nay sẽ không phải là cuối cùng. Mọi nhóm triển khai tác nhân sẽ gặp một trong những chế độ thất bại này ít nhất một lần. Các nhóm phục hồi nhanh chóng là những nhóm đã có sẵn các cơ chế bảo vệ. Tải Apidog và bắt đầu với bước máy chủ giả lập; chỉ riêng điều đó đã có thể giúp bạn tránh một đêm mất ngủ trong quý này. Để có góc nhìn của nhóm QA về cùng vấn đề này, hãy xem các công cụ kiểm thử API cho kỹ sư QA. Để có thêm ngữ cảnh rộng hơn về việc viết định nghĩa công cụ mà tác nhân có thể sử dụng an toàn, hãy xem cách viết tệp AGENTS.md.
Câu hỏi thường gặp
Làm cách nào để kiểm thử các lệnh gọi API của tác nhân AI mà không tốn tiền token?
Chạy tác nhân của bạn đối với một máy chủ giả lập trong quá trình phát triển. Các URL giả lập của Apidog trả về phản hồi thực tế miễn phí, do đó các vòng lặp kiểm thử của bạn không tiêu tốn tín dụng API thực. Đặt nhiệt độ về 0 và sử dụng một bộ prompt nhỏ cố định. Bạn có thể chạy hàng nghìn lần lặp kiểm thử với chi phí của máy chủ giả lập là bằng không. Xem danh sách kiểm thử của kỹ sư QA để biết thiết lập đầy đủ.
Sự khác biệt giữa kiểm thử tác nhân và kiểm thử API là gì?
Kiểm thử tác nhân kiểm tra xem mô hình có chọn đúng công cụ và điền các đối số chính xác hay không. Kiểm thử API kiểm tra xem endpoint có hoạt động đúng cách khi được gọi hay không. Cả hai đều quan trọng. Một tác nhân hoàn hảo gọi một API lỗi vẫn tạo ra kết quả lỗi, và một tác nhân lỗi gọi một API hoàn hảo vẫn gây ra lỗi. Bạn cần kiểm thử cả hai lớp riêng biệt.
Tôi có cần khóa bất biến trên mọi endpoint không?
Có, trên mọi endpoint ghi. Đọc (Reads) vốn dĩ là bất biến. Ghi (Writes) thì không, và các tác nhân sẽ thử lại. Năm dòng middleware để hỗ trợ một tiêu đề bất biến sẽ tự chứng minh giá trị của chúng ngay lần đầu tiên tác nhân thử lại một lỗi 500 và bạn không bị tạo ra hàng trùng lặp.
Làm cách nào để ngăn prompt injection kích hoạt các lệnh gọi API xấu?
Đừng chỉ dựa vào lớp prompt. API phải thực thi ủy quyền dựa trên ngữ cảnh người dùng gốc, chứ không phải yêu cầu của tác nhân. Nếu một phiên ngữ cảnh người dùng bình thường không thể truy cập /admin/delete-all-users, thì tác nhân hoạt động thay mặt cho người dùng đó cũng không nên có khả năng đó, bất kể prompt nói gì. LLM Top 10 của OWASP đề cập chi tiết về vấn đề này.
Tôi có thể sử dụng Apidog trực tiếp với Claude hoặc GPT mà không cần viết lớp công cụ riêng không?
Bạn trỏ định nghĩa công cụ của tác nhân của mình đến URL giả lập của Apidog trong quá trình kiểm thử. Cả Claude và GPT đều hỗ trợ các URL cơ sở HTTP tùy ý trong định nghĩa công cụ của chúng, vì vậy việc thay đổi chỉ là một biến môi trường. Khi bạn sẵn sàng kiểm thử trên môi trường staging hoặc sản xuất, hãy thay đổi biến đó.
Mức giới hạn ngân sách phù hợp cho tác nhân là bao nhiêu?
Bắt đầu nghiêm ngặt và nới lỏng dần theo dữ liệu. Bắt đầu với 50.000 token mỗi phiên, 30 lệnh gọi API mỗi phút, 5 đô la mỗi tác vụ. Theo dõi các số liệu trong hai tuần. Nâng các giới hạn mà bạn gặp phải một cách hợp lý. Giảm các giới hạn mà bạn không bao giờ đạt tới. Xem xét hàng tháng. Mục tiêu không phải là một con số cố định; mà là một con số đủ chặt để bắt các vòng lặp ngoài tầm kiểm soát và đủ lỏng để công việc thực tế diễn ra.
Làm cách nào để phát hiện sự lệch schema giữa các công cụ của tác nhân và API của tôi?
Chạy so sánh schema trong CI trên mỗi PR. So sánh định nghĩa công cụ của tác nhân (JSON schema) với schema phần thân yêu cầu của OpenAPI cho cùng một endpoint. Làm thất bại quá trình xây dựng nếu chúng khác biệt. Đoạn mã Python 30 dòng trong phần cơ chế bảo vệ ở trên thực hiện điều này; sao chép nó vào kho lưu trữ của bạn và tích hợp nó vào GitHub Actions.