Blog

Cách kiểm thử lệnh gọi công cụ AI với Apidog: Ngăn chặn sự cố trong môi trường sản xuất

Một tác nhân AI đáng tin cậy là một lớp công cụ đã được kiểm thử, không phải là một lời nhắc thông minh hơn. Hãy xây dựng một tác nhân và sử dụng Apidog để mô phỏng, xác nhận và kiểm thử mọi lệnh gọi công cụ, bao gồm cả các kịch bản lỗi.

Ashley Innocent

Ashley Innocent

12 tháng 6 2026

Cách kiểm thử lệnh gọi công cụ AI với Apidog: Ngăn chặn sự cố trong môi trường sản xuất

Apidog cho doanh nghiệp

Triển khai tại chỗ

SSO & RBAC

Tuân thủ SOC 2

Khám phá Apidog Enterprise

Một tác nhân AI chỉ đáng tin cậy như các API mà nó gọi. Mô hình chọn một công cụ, điền vào các đối số và gửi yêu cầu; nếu yêu cầu đó thất bại, trả về định dạng sai hoặc bị treo, tác nhân của bạn sẽ đưa ra quyết định tự tin dựa trên dữ liệu xấu. Hầu hết các bản demo tác nhân bỏ qua phần này. Các tác nhân sản xuất thành công hay thất bại đều phụ thuộc vào điều này.

Hướng dẫn này chỉ ra cách xây dựng một tác nhân gọi các công cụ thực tế và quan trọng hơn là cách sử dụng Apidog làm cả lớp API và bộ kiểm thử đằng sau nó. Bạn sẽ thiết kế các điểm cuối công cụ, mô phỏng chúng để có thể phát triển ngoại tuyến, và viết các xác nhận để phát hiện lỗi gọi công cụ trước khi nó đến tay người dùng. Mục tiêu là một tác nhân mà bạn có thể tin tưởng vì bạn đã kiểm thử nó, chứ không phải vì luồng hoạt động thành công một lần.

tải ứng dụng tải ứng dụng

Một tác nhân thực sự làm gì ở lớp API

Bỏ qua các yếu tố bên ngoài, một vòng lặp tác nhân rất đơn giản:

  1. Mô hình nhận một mục tiêu của người dùng và danh sách các công cụ.
  2. Nó trả về một lời gọi công cụ: tên công cụ cộng với các đối số JSON.
  3. Mã của bạn thực thi lời gọi đó; thường là một yêu cầu HTTP đến một API nào đó.
  4. Kết quả được gửi lại cho mô hình.
  5. Mô hình hoặc gọi một công cụ khác hoặc trả lời.

Mọi thất bại thú vị đều xảy ra ở bước 3 và bước 4. Mô hình tạo ra một đối số ảo, API trả về mã 422, lược đồ phản hồi bị lệch, cuộc gọi hết thời gian chờ hoặc giới hạn tốc độ được áp dụng giữa vòng lặp. Nếu bạn đã đọc về tác nhân AI như những người tiêu dùng API mới, thì đây là phiên bản cụ thể của ý tưởng đó: tác nhân của bạn là một client truy cập API của bạn, và nó xứng đáng có cùng sự kiểm thử nghiêm ngặt như bất kỳ client nào khác.

Vì vậy, công việc được chia làm hai: định nghĩa các công cụ là các thao tác API thực, có thể kiểm thử được, sau đó xác minh tác nhân gọi chúng một cách chính xác trong cả điều kiện tốt và xấu.

Bước 1: Thiết kế các công cụ dưới dạng các thao tác API thực

Trước khi bạn viết một dòng mã tác nhân nào, hãy định nghĩa mỗi công cụ là một điểm cuối API trong Apidog. Coi lược đồ công cụ và lược đồ API là một, vì chúng là như vậy. Một công cụ get_weather và điểm cuối GET /weather chia sẻ một hợp đồng: cùng các tham số, cùng định dạng phản hồi.

Trong Apidog, hãy tạo một điểm cuối cho mỗi công cụ với lược đồ OpenAPI của nó; các tham số đường dẫn, truy vấn và phần thân, cùng với một phản hồi có kiểu. Điều này mang lại cho bạn ba điều miễn phí:

Thói quen ưu tiên lược đồ này cũng là thói quen đằng sau công việc thiết kế API vững chắc nói chung. Lợi ích cho các tác nhân là cụ thể: khi định nghĩa công cụ và điểm cuối thực tế của bạn đến từ một lược đồ, mô hình không thể gọi một công cụ mà API của bạn không hỗ trợ.

Bước 2: Mô phỏng các công cụ để bạn có thể xây dựng ngoại tuyến

Bạn không muốn mỗi lần phát triển phải truy cập các API trực tiếp tốn kém, áp đặt giới hạn tốc độ hoặc đơn giản là chưa được xây dựng. Apidog tạo ra một máy chủ mô phỏng trực tiếp từ lược đồ bạn vừa định nghĩa. Mỗi điểm cuối công cụ trả về dữ liệu mẫu thực tế, hợp lệ theo lược đồ mà không cần bất kỳ phần phụ trợ nào.

Điều này thay đổi cách bạn xây dựng tác nhân. Bạn có thể:

Trỏ trình thực thi công cụ của tác nhân của bạn đến URL cơ sở mô phỏng trong quá trình phát triển. Mô hình gọi get_weather, mã của bạn truy cập mô phỏng Apidog, và một phản hồi hợp lệ trở lại ngay lập tức. Khi bạn đã sẵn sàng cho thực tế, hãy thay đổi URL cơ sở thông qua một biến môi trường. Mô phỏng là điều giúp phát triển tác nhân nhanh chóng và có tính xác định; cùng một cách tiếp cận đó cung cấp năng lượng cho bất kỳ quy trình làm việc kiểm thử tác nhân AI nghiêm túc nào.

Bước 3: Kết nối tác nhân để gọi các công cụ

Với các điểm cuối và mô phỏng đã có, mã tác nhân vẫn gọn nhẹ. Đây là hình dạng của một vòng lặp gọi công cụ sử dụng Claude Messages API; các định nghĩa công cụ phản ánh các lược đồ bạn đã xây dựng trong Apidog.

import anthropic, requests, os

client = anthropic.Anthropic()
TOOL_BASE = os.environ["TOOL_BASE_URL"]  # Apidog giả lập trong quá trình phát triển, API thật trong sản xuất

tools = [{
    "name": "get_weather",
    "description": "Lấy thời tiết hiện tại cho một thành phố",
    "input_schema": {
        "type": "object",
        "properties": {"city": {"type": "string"}},
        "required": ["city"],
    },
}]

def run_tool(name, args):
    if name == "get_weather":
        r = requests.get(f"{TOOL_BASE}/weather", params={"city": args["city"]}, timeout=10)
        r.raise_for_status()
        return r.json()

messages = [{"role": "user", "content": "Tôi nên mặc gì ở Tokyo hôm nay?"}]
while True:
    resp = client.messages.create(
        model="claude-fable-5", max_tokens=1024, tools=tools, messages=messages
    )
    if resp.stop_reason == "tool_use":
        block = next(b for b in resp.content if b.type == "tool_use")
        result = run_tool(block.name, block.input)
        messages.append({"role": "assistant", "content": resp.content})
        messages.append({"role": "user", "content": [{
            "type": "tool_result", "tool_use_id": block.id,
            "content": str(result),
        }]})
    else:
        print(resp.content[0].text) # In ra nội dung phản hồi
        break

Các dòng timeout=10 và raise_for_status() quan trọng hơn lời gọi mô hình. Chúng là sự khác biệt giữa một tác nhân thất bại rõ ràng và một tác nhân âm thầm đưa một yêu cầu bị treo hoặc lỗi trở lại vòng lặp. Để có cái nhìn rộng hơn về cách các tác nhân phù hợp với quy trình làm việc API, các mẫu trong 5 tác nhân AI cho quy trình làm việc API của bạn là một tài liệu tham khảo hữu ích.

Bước 4: Kiểm thử các lời gọi công cụ, không chỉ dựa vào cảm tính

Đây là phần mà hầu hết các đội bỏ qua. Chạy mỗi điểm cuối công cụ như một yêu cầu đã lưu trong Apidog với các xác nhận, độc lập với mô hình. Độ tin cậy của tác nhân bị giới hạn bởi độ tin cậy của các công cụ của nó, vì vậy hãy kiểm thử các công cụ trước.

Đối với mỗi điểm cuối công cụ, hãy xác nhận:

Sau đó kiểm thử các trường hợp không mong muốn, vì đó là nơi các tác nhân hoạt động sai lệch:

Đây là kiểm thử hợp đồng được áp dụng cho các công cụ tác nhân; cùng một nguyên tắc được đề cập trong kiểm thử hợp đồng API, nhắm vào các điểm cuối mà mô hình của bạn gọi. Khi định dạng phản hồi của một công cụ bị lệch, xác nhận sẽ thất bại trong CI và bạn sẽ khắc phục nó trước khi tác nhân bắt đầu xử lý một tải trọng bị hỏng.

Bước 5: Xử lý thử lại, thời gian chờ và giới hạn tốc độ

Các tác nhân làm khuếch đại các API không ổn định. Một lần thử lại trong một ứng dụng bình thường là một lần thử lại; trong một vòng lặp tác nhân, một mô hình liên tục gọi lại một công cụ bị lỗi có thể nhanh chóng tiêu tốn giới hạn tốc độ và ngân sách của bạn. Xây dựng các kiểm soát và kiểm thử chúng:

Chạy các kịch bản này dưới dạng các kịch bản có thể lặp lại trong Apidog để một hồi quy trong việc xử lý lỗi của bạn xuất hiện dưới dạng một kiểm thử thất bại, chứ không phải một sự cố sản xuất.

Bước 6: Chạy toàn diện dựa trên các mô phỏng trong CI

Kết nối chúng lại với nhau. Trong CI, khởi động tác nhân của bạn trỏ đến máy chủ mô phỏng Apidog, cấp cho nó một tập hợp mục tiêu người dùng cố định và xác nhận kết quả cuối cùng cũng như trình tự các lời gọi công cụ. Vì các mô phỏng có tính xác định, cùng một đầu vào tạo ra cùng các lời gọi công cụ trong mỗi lần chạy, do đó các kiểm thử tác nhân của bạn không còn không ổn định. Khi bạn tự tin, hãy chuyển URL cơ sở sang các API thực tế để thực hiện một kiểm thử khói trực tiếp nhỏ hơn. Sự phân chia này; các mô phỏng có tính xác định cho phần lớn việc kiểm thử, một kiểm tra trực tiếp mỏng để kiểm tra thực tế; là điều làm cho kiểm thử AI tác nhân trở nên thực tế thay vì chỉ là nguyện vọng.

Danh sách kiểm tra cho một tác nhân đáng tin cậy

Hoàn thành cả sáu mục và bạn sẽ có một tác nhân mà độ tin cậy của nó có thể được mô tả bằng bằng chứng, chứ không phải hy vọng.

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

Tại sao nên sử dụng client API để kiểm thử tác nhân thay vì chỉ chạy tác nhân? Việc chạy tác nhân kiểm thử mô hình và các công cụ cùng nhau, vì vậy một lỗi có thể không rõ ràng. Kiểm thử từng điểm cuối công cụ trong Apidog cách ly lớp API, giúp bạn biết liệu vấn đề là do lý luận của mô hình hay một công cụ bị hỏng.

Tôi có phải xây dựng các API thực trước khi xây dựng tác nhân không? Không. Định nghĩa các hợp đồng công cụ dưới dạng lược đồ trong Apidog, tạo mô phỏng và xây dựng toàn bộ vòng lặp tác nhân dựa trên các mô phỏng đó. Thay thế các điểm cuối thực tế sau này thông qua một biến môi trường.

Làm cách nào để ngăn tác nhân của tôi lặp vô tận khi gặp công cụ bị lỗi? Giới hạn số lần thử lại, thêm khoảng lùi và kích hoạt bộ ngắt mạch sau nhiều lần thất bại để tác nhân báo cáo vấn đề thay vì tiếp tục xoay vòng. Kiểm thử từng kiểm soát với một mô phỏng trả về lỗi.

Tôi có thể kiểm thử tác nhân mà không tốn tiền cho các cuộc gọi mô hình và API không? Phần lớn là có. Mô phỏng các API công cụ trong Apidog cho các kiểm thử tích hợp có tính xác định, miễn phí và giới hạn các cuộc gọi mô hình trực tiếp vào một bộ kiểm thử khói nhỏ.

Điều này có hoạt động với các framework như LangChain hoặc Claude Agent SDK không? Có. Lớp công cụ chỉ là HTTP. Bất kể framework nào điều khiển vòng lặp, hãy trỏ các lời gọi công cụ của nó đến các mô phỏng Apidog để kiểm thử và đến các điểm cuối thực tế để sản xuất. Xem hướng dẫn Claude Code SDK để biết một vòng lặp như vậy.

Tổng kết

Một tác nhân đáng tin cậy không phải là một lời nhắc thông minh hơn; nó là một lớp công cụ đã được kiểm thử. Định nghĩa các công cụ của bạn là các thao tác API thực, mô phỏng chúng để việc phát triển nhanh chóng và có tính xác định, xác nhận mọi định dạng phản hồi và kiểm thử các lỗi một cách có chủ đích. Apidog cung cấp cho bạn một nơi để thiết kế các điểm cuối đó, mô phỏng chúng và chạy chúng như một bộ kiểm thử, để hành vi của tác nhân của bạn là điều bạn có thể chứng minh. Tải xuống Apidog và xây dựng tác nhân mà bạn thực sự có thể tin tưởng trong môi trường sản xuất.

tải ứng dụng

Thực hành thiết kế API trong Apidog

Khám phá cách dễ dàng hơn để xây dựng và sử dụng API

Đăng ký miễn phíTải xuống