Blog

Phiên bản hóa API cho AI Agents: Khi có thay đổi không tương thích

Một trường được đổi tên gây lỗi rõ ràng cho một client có kiểu dữ liệu và gây lỗi âm thầm cho một agent. Tìm hiểu những thay đổi API nào gây lỗi cho các agent, cách ghim phiên bản và cách phát hiện sự sai lệch bằng kiểm thử hợp đồng và kiểm tra cấu trúc dữ liệu trong thời gian chạy.

Ashley Innocent

Ashley Innocent

26 tháng 8 2026

Phiên bản hóa API cho AI Agents: Khi có thay đổi không tương thích

Apidog cho doanh nghiệp

Triển khai tại chỗ

SSO & RBAC

Tuân thủ SOC 2

Khám phá Apidog Enterprise

Nhóm API đã đổi tên một trường từ customer_name thành customer_full_name. Họ đã công bố, cập nhật tài liệu, và mọi client do con người quản lý đều nhận được một pull request. Agent của bạn không nhận được gì, vì không ai coi nó là một client. Nó vẫn gửi trường cũ, API vẫn chấp nhận yêu cầu và bỏ qua khóa không xác định, và trong hai tuần, mọi bản ghi nó tạo ra đều có tên trống.

Agent là những người tiêu dùng API ít có khả năng nhận thấy thay đổi nhất và dễ che đậy chúng nhất. Một client của con người sẽ ném ra một ngoại lệ. Một agent đọc mã 200, quyết định cuộc gọi đã hoạt động và tiếp tục. Đôi khi nó ứng biến quanh vấn đề theo cách trông giống như thành công.

Hướng dẫn này giải thích tại sao agent đặc biệt dễ bị tổn thương trước sự trôi dạt của API, những thay đổi nào làm hỏng chúng mà sẽ không làm hỏng các client thông thường, cách ghim và phát hiện phiên bản, và cách bắt lỗi trôi dạt trong CI trước khi một lần chạy thực sự xảy ra. Bài viết của chúng tôi về tại sao các agent AI thất bại trong môi trường sản xuất bao gồm các chế độ lỗi; đây là lỗi đến từ bên ngoài codebase của bạn.

Apidog quan trọng ở đây vì việc phát hiện là một vấn đề về đặc tả. Nếu bạn có phiên bản trước của định nghĩa API và phiên bản hiện tại, sự khác biệt là cơ học.

nút

Tại sao agent ít nhận thấy hơn client

Bốn đặc tính kết hợp một cách tồi tệ.

Dung thứ thầm lặng. Hầu hết các API bỏ qua các trường không xác định trong phần thân yêu cầu. Một trường được đổi tên có nghĩa là trường mới không có và trường cũ bị loại bỏ, với mã 200 trả về. Không có gì được báo lỗi.

Khả năng ứng biến. Khi một phản hồi thiếu một giá trị, một mô hình thường sẽ tiếp tục với một sự thay thế hợp lý thay vì dừng lại. Đó là hành vi hữu ích trong giao tiếp nhưng là hành vi nguy hiểm đối với một API.

Mô tả trong lời nhắc (prompt). Mô tả công cụ của agent mã hóa các giả định về API trong văn bản. Khi API thay đổi, các mô tả trở nên sai lệch một cách tinh tế, và các mô tả sai tạo ra các cuộc gọi sai mà không cần bất kỳ mã nào tham gia. Bài viết của chúng tôi về thiết kế lược đồ công cụ API bao gồm mức độ hành vi phụ thuộc vào văn bản đó.

Không có trình biên dịch. Một client có kiểu dữ liệu (typed client) sẽ bị lỗi trong quá trình xây dựng khi một trường biến mất. Hợp đồng của agent nằm trong các lược đồ JSON và văn xuôi, và không có gì kiểm tra nó cho đến khi một cuộc gọi thất bại, hoặc tệ hơn, cho đến khi một cuộc gọi lặng lẽ không thất bại.

Kết quả là: những thay đổi an toàn cho các client thông thường không phải lúc nào cũng an toàn cho agent, và bạn nên phân loại chúng riêng biệt.

Những thay đổi nào thực sự làm hỏng agent

Sự phân chia thêm vào-so với-phá vỡ thông thường vẫn áp dụng, và agent thêm một danh mục ở giữa.

An toàn cho các client có kiểu dữ liệu, rủi ro cho agent:

Cũng an toàn cho agent. Thêm một trường tùy chọn, thêm một endpoint, thêm một tham số tùy chọn với giá trị mặc định được giữ nguyên, nới lỏng xác thực.

Danh sách ở giữa đó là điều cần chú ý, bởi vì không có gì trong một đánh giá thay đổi tiêu chuẩn sẽ gắn cờ nó.

Luôn ghim phiên bản

Biện pháp phòng thủ đầu tiên là từ chối di chuyển một cách ngầm định.

Gửi một phiên bản rõ ràng trong mọi yêu cầu, bất kể cơ chế API cung cấp là gì: một phân đoạn đường dẫn, một tiêu đề, hoặc một ghim cấp tài khoản. Tài liệu quản lý phiên bản API của GitHub sử dụng tiêu đề ngày, và Stripe ghim một phiên bản cho mỗi tài khoản với một bước nâng cấp rõ ràng. Cả hai đều mang lại cho bạn cùng một đặc tính: không có gì thay đổi bên dưới bạn cho đến khi bạn quyết định.

DEFAULT_HEADERS = {
    "X-API-Version": "2026-06-01",
    "User-Agent": "billing-agent/1.4 (+https://example.com/agents)",
}

User-Agent cũng quan trọng như việc ghim phiên bản. Khi một nhà cung cấp API cần cảnh báo người gọi về việc ngừng sử dụng, họ sẽ xem xét lưu lượng truy cập. Một agent tự nhận dạng sẽ nhận được email; một agent gửi một chuỗi thư viện mặc định thì không.

Nếu bạn sở hữu API, hãy công bố một phiên bản và giữ nó. Hướng dẫn của chúng tôi về chiến lược quản lý phiên bản API tốt nhất bao gồm các tùy chọn, và quản lý phiên bản API trong Apidog bao gồm việc duy trì nhiều phiên bản hoạt động cùng một lúc.

Đối với các API bên thứ ba hoàn toàn không có quản lý phiên bản, hãy ghim những gì bạn có thể: ghi lại hình dạng phản hồi bạn đã xây dựng và kiểm tra nó, đây là phần tiếp theo.

Phát hiện sự trôi dạt trước khi một lần chạy thực hiện

Việc ghim mua thời gian. Nó không ngăn chặn việc nâng cấp cuối cùng, và nó không làm gì cho các API thay đổi mà không có quản lý phiên bản. Vì vậy, hãy phát hiện.

def check_shape(tool_name, payload, expected):
    missing = [f for f in expected["required"] if f not in payload]
    extra = [f for f in payload if f not in expected["properties"]]
    if missing:
        log.error("api_lệch_phiên_bản", tool=tool_name, missing=missing)
        raise ApiDriftError(f"{tool_name}: thiếu trường {missing}")
    if extra:
        log.warning("api_trường_mới", tool=tool_name, fields=extra)
    return payload

Lỗi nếu thiếu, cảnh báo nếu thừa. Một trường bắt buộc bị thiếu có nghĩa là agent sắp làm việc với dữ liệu không đầy đủ, đó là lỗi đáng dừng lại. Các trường mới thường là bổ sung và đáng được biết mà không làm gián đoạn một lần chạy. Định tuyến cả hai vào bản ghi dấu vết được mô tả trong bài viết của chúng tôi về truy vết các cuộc gọi công cụ của agent AI.

Nâng cấp mà không làm hỏng agent

Khi bạn chuyển sang một phiên bản mới, hãy coi đó là một thay đổi đối với agent, bởi vì nó là vậy.

Tạo lại các công cụ thay vì chỉnh sửa thủ công chúng, để các mô tả và lược đồ di chuyển cùng nhau. Sau đó đọc sự khác biệt của các định nghĩa công cụ được tạo. Sự khác biệt đó là phạm vi ảnh hưởng thực sự, và nó thường nhỏ hơn hoặc lớn hơn những gì nhật ký thay đổi của API ngụ ý.

Chạy agent với một bản giả lập của phiên bản mới trước khi trỏ nó đến bất kỳ thứ gì trực tiếp. Đây là bước có giá trị cao nhất và là bước thường bị bỏ qua nhất: một bản giả lập được xây dựng từ đặc tả mới cho phép bạn chạy toàn bộ bộ tác vụ của mình với các hình dạng mới mà không có rủi ro, theo bài viết của chúng tôi về chạy agent với bản giả lập thay vì môi trường sản xuất.

Chạy lại bộ chọn lọc. Các thay đổi trong mô tả làm thay đổi công cụ mà mô hình chọn, và sự hồi quy đó không thể nhìn thấy bằng sự khác biệt lược đồ. Xác nhận lựa chọn công cụ cho một tập hợp cố định các lời nhắc, như trong hướng dẫn của chúng tôi về kiểm thử agent AI không xác định.

Triển khai đằng sau một cờ, trên một phần lưu lượng truy cập, với phiên bản cũ vẫn được ghim và sẵn sàng. Theo dõi bốn con số tương tự trong một ngày. Các sự hồi quy của agent xuất hiện dưới dạng nhiều cuộc gọi hơn cho mỗi tác vụ và nhiều lần thử lại hơn rất lâu trước khi bất kỳ ai gửi khiếu nại.

Ba trường hợp trôi dạt đã xảy ra trong môi trường sản xuất

Mô hình: mỗi thay đổi đều được công bố, mỗi thay đổi đều là bổ sung hoặc nhỏ theo phân loại của nhà cung cấp, và mỗi thay đổi đều gây lỗi cho một agent. Khoảng cách đó là điều cần phải thiết kế để xử lý.

Coi các cảnh báo ngừng sử dụng là một hạng mục công việc

Các nhà cung cấp thường cảnh báo bạn. Cảnh báo đến trong một nhật ký thay đổi, một email, hoặc một tiêu đề Deprecation trên phản hồi, và dễ dàng để không có thông báo nào trong số đó đến được người duy trì agent.

Kết nối chúng vào hàng đợi công việc thông thường của bạn. Tiêu đề Deprecation và Tiêu đề Sunset đều được tiêu chuẩn hóa, vì vậy một kiểm tra chung có thể hoạt động trên các nhà cung cấp. Ghi lại chúng khi chúng xuất hiện, và cảnh báo ngay từ lần nhìn thấy đầu tiên thay vì lần thứ một nghìn. Một tiêu đề xuất hiện trên 3 phần trăm cuộc gọi hôm nay sẽ là một sự cố ngừng hoạt động hoàn toàn vào ngày ngừng hỗ trợ.

Cũng nên giữ một danh mục: agent nào, nhà cung cấp nào, phiên bản nào, endpoint nào và ai sở hữu nó. Mười dòng trong một tệp là đủ. Khi một thông báo ngừng hỗ trợ đến, câu hỏi "điều này có ảnh hưởng đến chúng ta không" nên mất một phút, chứ không phải cả buổi chiều để tìm kiếm.

Sự trôi dạt là công việc, vì vậy hãy giao nó cho một người chủ

Việc phát hiện tạo ra một hàng đợi: sự khác biệt đặc tả, một kiểm tra hợp đồng thất bại, một tiêu đề cảnh báo ngừng sử dụng lần đầu tiên được nhìn thấy. Mỗi thứ là một phần công việc nhỏ với một thời hạn kèm theo, và chế độ lỗi là nó nằm trong một kênh mà không ai sở hữu cho đến khi ngày ngừng hỗ trợ đến.

Đặt chúng ở nơi nhóm của bạn đã theo dõi công việc. Nếu agent của bạn chạy như các môi trường chạy mã (coding runtimes) chứ không phải là một dịch vụ bạn đã triển khai, nền tảng quản lý chúng có thể đóng vòng lặp: Sharkly gán một Tác vụ cho một Agent hoặc một Crew và giữ mục tiêu, dấu vết thực thi và đánh giá ở một nơi, vì vậy "API thanh toán đã ngừng hỗ trợ endpoint này" trở thành một tác vụ được giao với một kết quả chứ không phải là một tin nhắn trong một chủ đề. Bất kể bạn sử dụng gì, quy tắc vẫn giống nhau. Một cảnh báo trôi dạt không có chủ sở hữu là một sự ngừng hỗ trợ bạn sẽ gặp lại vào ngày nó gây lỗi.

Danh sách kiểm tra

Nhóm API sẽ tiếp tục phát hành các thay đổi, và điều đó không sao cả. Điều bạn cần là agent của bạn phải là một client nhận biết được, điều này cần một phiên bản được ghim, một kiểm tra hợp đồng và một kiểm tra hình dạng trong thời gian chạy. Tải xuống Apidog để đối chiếu đặc tả và giả lập phiên bản tiếp theo trước khi nó đi vào hoạt động thực tế.

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

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