Cách Kiểm Thử AI Gọi API An Toàn, Không Mất Dữ Liệu

Một tác nhân mã hóa AI đã chạy một script, chứng kiến nó thành công, rồi sau đó nhìn thấy một bảng cơ sở dữ liệu sản xuất biến mất. Bài viết hậu sự cố trên Hacker News trở nên viral với tiêu đề sắc bén: “AI không xóa cơ sở dữ liệu của bạn, mà là bạn.” Điểm này đúng trọng tâm vì nó là sự thật. Tác nhân đã tuân theo một định nghĩa công cụ, công cụ đó đã chạm đến một điểm cuối (endpoint) thực sự, điểm cuối đó không có hàng rào bảo vệ (guardrails), và một người đã trao chìa khóa cho một quy trình không dừng lại để 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 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, 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 thử API.

💡

Nếu bạn đang triển khai các tác nhân tự động gọi API của mình, hướng dẫn này là dành cho bạn. Bạn sẽ học cách giả lập (mock) các điểm cuối (endpoint) bên ngoài trong quá trình phát triển tác nhân, kiểm tra (sandbox) các thao tác phá hủy, viết các bài kiểm tra hợp đồng (contract tests) cho lược đồ công cụ, đặt giới hạn ngân sách cho mỗi tác nhân, và diễn tập các chế độ lỗi trước khi chúng xảy ra trong môi trường sản xuất. Chúng tôi sẽ sử dụng Apidog cho giàn giáo kiểm thử vì nó hỗ trợ OpenAPI một cách tự nhiên, chạy máy chủ giả lập (mock servers) mà không cần viết mã kết nối, và cung cấp cho bạn các bài kiểm tra kịch bản (scenario tests) ánh xạ rõ ràng đến các chuỗi gọi công cụ của tác nhân.

nút

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ông cụ của chúng không có hàng rào bảo vệ phía API: thiếu giới hạn tốc độ (rate limits), không có tính chất bất biến (idempotency), xóa nóng (hot deletes), lược đồ bị hỏng (broken schemas). Bạn khắc phục điều này bằng bốn bước: kiểm thử hợp đồng (contract-test) các đị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áy chủ giả lập (mock server) cho các điểm cuối có tính phá hủy, thực thi ngân sách và khóa bất biến (idempotency keys) cho mỗi tác nhân, và phát lại các kịch bản lỗi trong CI. Apidog cung cấp cho bạn khả năng nhập OpenAPI, các giả lập (mocks) và trình chạy kịch bản để thực hiện tất cả trong một dự án.

Giới thiệu

Một năm trước, “kiểm thử tác nhân AI” có nghĩa là đưa câu lệnh cho Claude hoặc GPT và chấm điểm câu trả lời. Điều đó 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à các API của bạn giao tiếp với cơ sở dữ liệu thực, bộ xử lý thanh toán và các dịch vụ bên thứ ba. Một định nghĩa công cụ tồi hoặc thiếu giới hạn tốc độ không phải là một vấn đề về phong cách. Đó là một sự cố sản xuất với tên của bạn trên đó.

Câu chuyện viral trên Hacker News tháng này đã nắm bắt được sự thay đổi. Tác giả lập luận rằng AI không xóa cơ sở dữ liệu; chính 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ỳ 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 điều đó.” 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 trong đó một tác nhân đã thử lại một cuộc gọi thất bại quá nhiều lần đến nỗi hóa đơn đã vượt quá 800 euro trước khi bất kỳ ai phát hiệ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 hàng rào 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 Apidog từng bước để giả lập các điểm cuối có tính phá hủy, và kết thúc bằng các kỹ thuật nâng cao như phát hiện sai lệch lược đồ (schema-drift) và tách đôi khóa. 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 hậu sự cố về tác nhân và một mô hình sẽ hiện rõ: mô hình không phải là nhân vật chính. API mới là.

Lấy ví dụ về tấn công chèn câu lệnh (prompt injection). Một 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 điểm cuối /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. Giải pháp không phải là làm cứng câu lệnh. Giải pháp là xây dựng một API không để lộ delete_all=true cho một token đến từ phiên người dùng. OWASP gọi đây là LLM01 trong danh sách 10 mối đe dọa hàng đầu về LLM của họ, và biện pháp giảm thiểu là ủy quyền phía API, không phải kỹ thuật câu lệnh (prompt engineering).

Lấy ví dụ về lược đồ 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 xu. Định nghĩa công cụ của tác nhân nói rằng amount là một số thực tính bằng đô la. Ba tháng sau, ai đó hoàn trả khoản phí 19 xu 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 lược đồ mà bạn cung cấp. Lược đồ đã bị lệch khỏi API. Không ai kiểm thử hợp đồng.

Lấy ví dụ về thiếu giới hạn tốc độ (rate limits). Một tác nhân trong vòng lặp thử lại đã truy cập điểm cuối 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 sự. Đến khi 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 hại. Mô hình đang làm việc từ một công cụ không có giới hạn.

Lấy ví dụ về 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 hết thời gian chờ mạng, thử lại vì bộ lập kế hoạch nghĩ rằng cuộc 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 cuộc gọi ban đầu có thành công hay không; API không cung cấp cách để hỏi. Các khóa bất biến (Idempotency keys) 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ông cụ của nó yêu cầu. Các công cụ chính là API. Vì vậy, khi bạn kiểm tra nơi độ tin cậy của tác nhân bị phá vỡ, hãy xem xét hợp đồng API trước tiên, sau đó là công cụ tác nhân, và hầu như không bao giờ là bản thân mô hình. Cách nhìn nhận lại 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ử với các hàng rào bảo vệ được bật.

Bốn hàng rào bảo vệ mà mọi tích hợp tác nhân-API đều 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% 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 lược đồ công cụ

Đặc tả OpenAPI của bạn là nguồn thông tin đá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 tay 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 bản dựng CI của bạn ngay khi chúng khác biệt.

Dưới đây là một kiểm tra Python tối thiểu để xác thực định nghĩa công cụ kiểu Claude so với đặc tả OpenAPI trực tiếp:

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 kiểm tra 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 bản dựng nếu danh sách không trống. Kiểm tra đơn lẻ này sẽ bắt được lỗi float-vs-cents trong phần trước đó nhiều 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 điểm cuối có tính phá hủy

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 điểm cuối thay đổi trạng thái đều có một phiên bản giả lập tương đương trả về cùng một 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 giả lập. Các bài kiểm tra dàn dựng 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 con người phê duyệt việc triển khai.

Apidog tạo các 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 vào máy chủ giả lập, chạy hàng trăm lần lặp câu lệnh của mình và xem cách nó hoạt động. Nếu tác nhân liên tục cố gắng PUT đến /users/{id}/delete vì nó hiểu sai tài liệu, 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 theo hợp đồng trước (contract-first development) để biết mô hình rộng hơn mà điều này phù hợp.

3. Khóa bất biến (Idempotency keys) và xóa mềm (soft deletes) cho các thao tác không thể đảo ngược

Mọi điểm cuối 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 đều phải là xóa mềm theo mặc định, với một đường dẫn xóa cứng riêng biệt mà con người phải ủy quyền.

Middleware trông như thế này trong Express:

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 vào bộ nhớ cache trong lần gọi thứ hai thay vì tính phí hai lần. Mô hình tương tự này bảo vệ chống lại việc 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 mỗi 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 hết, tác nhân dừng lại. Không có ngoại lệ. Sự cố 800 euro trên Reddit 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à đến khi con người kiểm tra, thiệt hại đã xảy ra.

Một middleware quản lý ngân sách bao quanh cổng API của bạn có thể theo dõi:

Số token mỗi phiên, giới hạn 50.000
Số lượt gọi API mỗi phút, giới hạn 30
Tổng chi tiêu bằng xu, giới hạn 500
Độ sâu gọi công cụ, giới hạn 10 cuộc gọi lồng nhau

Khi bất kỳ giới hạn nào bị chạm, trả về HTTP 429 với tiêu đề Retry-After có cấu trúc và tiêu đề X-Budget-Exceeded nêu tên giới hạn. Bộ lập kế hoạch của tác nhân sau đó có thể leo thang vấn đề cho con người hoặc hoàn tác 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 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 lại. Kiểm thử hợp đồng bắt được các lỗi lược đồ rõ ràng. Giả lập bắt được các lỗi phá hủy. Tính bất biến bắt được các cơn bão thử lại. Ngân sách bắt được các vòng lặp ngoài tầm kiểm soát. Cùng nhau, chúng biến câu “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ý sự cố và yêu cầu trợ giúp.” Đó là tiêu chuẩn.

Kiểm thử các cuộc gọi API của tác nhân với Apidog

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, lược đồ và ví dụ, sau đó tạo các điểm cuối tương ứng trong dự án. Nếu API của bạn chưa được ghi lại 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 thông tin đáng tin cậy duy nhất mà cả con người và tác nhân AI của bạn đều đọc được. Hướng dẫn quy trình làm việc API thiết kế trước (design-first API workflow guide) 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 điểm cuối có tính phá hủy

Tìm mọi điểm cuối thay đổi dữ liệu: POST, PUT, PATCH, DELETE. Đối với mỗi điểm cuối, 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 giả lập thực tế từ lược đồ 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ử, 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 năm 1970 để mọi rò rỉ đều rõ ràng 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 vào máy chủ giả lập trong quá trình phát triển. Bây giờ, lệnh DELETE /users/{id} của bạn trả về 200 với một tải trọng người dùng giả, và cơ sở dữ liệu thực của bạn an toàn. Xem phát triển theo hợp đồng trước (contract-first development) để biết mô hình 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 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 cuộc gọi API với các xác nhận (assertions), giống như một bộ kiểm thử. Đối với một tác nhân phân loại vé hỗ trợ, kịch bản có thể là:

Gửi POST /auth/token với thông tin đăng nhập kiểm thử, lấy token bearer
Gửi GET /tickets?status=open với token, lấy ID vé đầu tiên
Gửi POST /tickets/{id}/triage với một danh mục, xác nhận 200 và lấy trường người được giao
Gửi POST /notifications với một tin nhắn mẫu, xác nhận nội dung tin nhắn khớp với một regex

Bạn đang thực chất 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 lược đồ vé và regex 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 (API testing for QA engineers) để biết playbook 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. Kết nối 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ụ tác nhân đều kích hoạt một lần phát lại kịch bản đầy đủ.

Bước 5: So sánh hai phiên bản mô hình cạnh nhau

Khi bạn đang đánh giá việc nâng cấp từ mô hình này sang mô hình khác, bạn muốn biết liệu các cuộc gọi công cụ của mô hình mới có hoạt động tương tự trong 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 (diff) các thân yêu cầu (request bodies). Những điều 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 sẽ bắt được sự lệch lạc 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 (GPT-5.5 API integration), 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ông cụ tác nhân của bạn đều được kiểm tra dựa trên cùng một tiêu chuẩn kỳ vọng.

Các kỹ thuật nâng cao và mẹo chuyên nghiệp

Một vài mẫu mà các đội ngũ có kinh nghiệm thường sử dụng sau khi đã thiết lập các kiến thức cơ bản.

Cố định nhiệt độ về 0 trong các bài kiểm tra. Các tác nhân không xác định gây ra các lỗi kiểm thử không xác định. Khi bạn kiểm thử hành vi gọi công cụ, hãy đặt nhiệt độ về 0 và gieo mầm (seed) mọi nguồn ngẫu nhiên. Bạn đang kiểm thử lớp công cụ, không phải lớp sáng tạo.

Chụp nhanh các dấu vết gọi công cụ. Mỗi lần chạy kiểm thử sẽ ghi lại chính xác chuỗi các cuộc 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, chứ 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. Thông tin xác thực sản xuất nằm trong kho bảo mật, 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 điểm cuối sản xuất, nó sẽ đi qua một proxy ký các yêu cầu bằng các token có thời gian sống ngắn.

Tách riêng khóa API đọc và ghi. Hầu hết các tác vụ của tác nhân đều chủ yếu là đọc. Cấp các khóa chỉ đọc cho những tác vụ đó. Khóa ghi được dành cho các tác vụ có cổng phê duyệt của con người. Thay đổi đơn lẻ này giúp 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 điểm cuối cần phê duyệt của con người. Khi một tác nhân cố gắng gọi một điểm cuối yêu cầu xác nhận của con người, trả về 423 với một trường confirmation_url. Bộ lập kế hoạch của tác nhân 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.”

Đóng khi có sai lệch lược đồ (schema drift). 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, bản dựng sẽ thất bại. Đừng chỉ hiển thị cảnh báo. Hãy hiển thị lỗi. Chi phí của một vài bản 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:

Mã hóa cứng URL giả lập vào các câu lệnh của tác nhân. Sử dụng biến môi trường để cùng một câu lệnh chạy trên môi trường giả lập, dàn dựng và sản xuất.
Bỏ qua tính bất biến trên các điểm cuối “nhỏ”. Mọi thao tác ghi đều cần đến nó. Gửi email cũng không ngoại lệ.
Ghi nhật ký toàn bộ thân yêu cầu trong môi trường sản xuất. Thông tin nhận dạng cá nhân (PII) bị rò rỉ vào ngăn xếp quan sát của bạn. Hãy biên tập lại 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 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 vào đ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 điểm cuối.

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 cổng API duy nhất, các mẫu kiểm thử microservices (microservices testing patterns) sẽ trình bày cách phân phối 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à bảng so sánh công bằng về bốn cách tiếp cận phổ biến.

Phương pháp	Thời gian thiết lập	Điểm mạnh	Điểm yếu	Phù hợp nhất cho
Các bài kiểm thử đơn vị tự tạo	Thấp	Kiểm soát hoàn toàn, không bị ràng buộc nhà cung cấp	Bảo trì cao, dễ lệch khỏi API thực	Các dự án nhỏ, đội ngũ một nhà phát triển
Khung đá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 đội AI tập trung vào đá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 đội đã đầu tư vào Postman
Kịch bản + giả lập Apidog	Trung bình	OpenAPI gốc, giả lập miễn phí, CLI kịch bản cho CI	Ít được biết đến hơn Postman	Các đội muốn một công cụ cho thiết kế, giả lập và kiểm thử

Tóm tắt thành thật: nếu bạn đã quen với 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 mới bắt đầu, 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% thời gian kiểm thử tác nhân-API của bạn sẽ dành cho.

Một số đội kết hợp các công cụ này. Họ giữ LangSmith để đánh giá cấp độ câu lệnh 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 đội ngũ chăm sóc 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 vé hỗ trợ. Trước khi ra mắt, họ đã cấu hình mọi điểm cuối ghi để yêu cầu một khóa bất biến và chạy 200 lượt phát lại kịch bản trong Apidog đối với một cơ sở dữ liệu sandbox. Các lượt 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 lược đồ và triển khai mà không có sự cố nào.

Tác nhân gọi API thanh toán. Một đội ngũ fintech 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 cuộc gọi. Họ đã chạy bộ kiểm thử hợp đồng (contract test suite) đố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ó bất kỳ khoản tính phí trùng lặp nào.

Tác nhân phân loại các vấn đề trên GitHub. Một đội ngũ 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 thông qua 50 bài kiểm tra kịch bản bao gồm các trường hợp đặc biệt (vấn đề đã xóa, thiếu nhãn, đầu vào người dùng bị định dạng sai), và phát hiện ba lỗi 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 chỉ học được 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 cần nhớ:

Coi lược đồ công cụ là hợp đồng và chạy kiểm thử hợp đồng trong CI.
Giả lập các điểm cuối có tính phá hủy 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 mỗi tác nhân, lỗi sẽ đóng khi bị chạm.
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ố viral trong năm nay sẽ không phải là cuối cùng. Mọi đội ngũ triển khai tác nhân đều sẽ gặp một trong những chế độ lỗi này ít nhất một lần. Các đội ngũ phục hồi nhanh chóng là những đội đã có sẵn các hàng rào bảo vệ. Tải xuống Apidog và bắt đầu với bước thiết lập máy chủ giả lập; chỉ riêng điều đó sẽ giúp bạn tránh được một đêm mất ngủ trong quý này. Để có góc nhìn của đội QA về vấn đề tương tự, xem công cụ kiểm thử API cho kỹ sư QA (API testing tools for QA engineers). Để có ngữ cảnh rộng hơn về cách viết định nghĩa công cụ mà tác nhân có thể sử dụng an toàn, xem cách viết tệp AGENTS.md (how to write AGENTS.md files).

Câu hỏi thường gặp

Làm cách nào để kiểm thử các cuộc 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 trên một máy chủ giả lập trong quá trình phát triển. URL giả lập của Apidog trả về các phản hồi thực tế miễn phí, vì vậy 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. Cố định nhiệt độ về 0 và sử dụng một bộ câu lệnh cố định nhỏ. Bạn có thể chạy hàng nghìn lần lặp kiểm thử với chi phí máy chủ giả lập là 0. Xem danh sách kiểm tra kiểm thử của kỹ sư QA (the QA engineer’s testing checklist) để 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ố một cách chính xác hay không. Kiểm thử API kiểm tra xem điểm cuối có hoạt động chính xác 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 bị lỗi vẫn tạo ra kết quả sai, và một tác nhân bị 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 điểm cuối không?

Có, trên mọi điểm cuối ghi. Đọc (Reads) là bất biến theo định nghĩa. Ghi (Writes) thì không, và các tác nhân sẽ thử lại. Năm dòng mã middleware để hỗ trợ tiêu đề bất biến sẽ tự đền đáp ngay lần đầu tiên tác nhân thử lại lỗi 500 và bạn không bị trùng lặp hàng.

Làm thế nào để ngăn chặn tấn công chèn câu lệnh (prompt injection) kích hoạt các cuộc gọi API sai?

Đừng chỉ dựa vào lớp câu lệnh. API phải thực thi ủy quyền dựa trên ngữ cảnh người dùng ban đầu, 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 không thể bình thường truy cập /admin/delete-all-users, thì tác nhân hành động thay mặt người dùng đó cũng không nên làm được điều đó, bất kể câu lệnh 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ụ của riêng mình không?

Bạn trỏ định nghĩa công cụ của tác nhân đến URL giả lập 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 chuyển đổi chỉ là một biến môi trường. Khi bạn sẵn sàng kiểm thử với môi trường dàn dựng (staging) hoặc sản xuất, hãy thay đổi biến đó.

Giới hạn ngân sách phù hợp cho một 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 cuộc 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. Tăng các giới hạn mà bạn chạm đến một cách hợp lệ. Giảm các giới hạn mà bạn không bao giờ chạm đến. Xem xét hàng tháng. Mục tiêu không phải là một con số cố định; đó 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 sự có thể diễn ra.

Làm thế nào để tôi phát hiện sự lệch lược đồ (schema drift) giữa các công cụ của tác nhân và API của tôi?

Chạy kiểm tra khác biệt lược đồ (schema diff) trong CI trên mọi PR. So sánh định nghĩa công cụ của tác nhân (lược đồ JSON) với lược đồ thân yêu cầu OpenAPI cho cùng một điểm cuối. Làm thất bại bản dựng nếu chúng khác biệt. Đoạn mã Python 30 dòng trong phần "guardrails" ở trên thực hiện điều này; hãy sao chép nó vào kho lưu trữ của bạn và tích hợp vào GitHub Actions.