Sebastian Petrus

Posted on Aug 26 Originally published at apidog.com

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

Ngăn API drift làm hỏng AI agent

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

Dùng thử Apidog ngay hôm nay

Agent là nhóm người tiêu dùng API khó phát hiện thay đổi nhất:

Client có kiểu dữ liệu thường lỗi khi build hoặc ném ngoại lệ.
Agent thấy mã 200, cho rằng lời gọi thành công và tiếp tục.
Khi thiếu dữ liệu, agent có thể tự suy diễn giá trị hợp lý thay vì dừng lại.
Hợp đồng của agent thường nằm trong JSON Schema và mô tả công cụ, không có trình biên dịch kiểm tra.

Bài viết về vì sao AI agent thất bại trong môi trường production trình bày các chế độ lỗi tổng quát; bài này tập trung vào lỗi đến từ bên ngoài codebase: API drift.

Apidog hữu ích vì đây là vấn đề dựa trên đặc tả: khi có phiên bản API trước và hiện tại, bạn có thể đối chiếu khác biệt một cách cơ học.

Những thay đổi gây rủi ro cho agent

Các thay đổi phá vỡ rõ ràng vẫn nguy hiểm với mọi client:

Xóa endpoint hoặc trường.
Đổi tên trường.
Thay đổi kiểu dữ liệu.
Biến tham số tùy chọn thành bắt buộc.
Thay đổi URL.

Tuy nhiên, có một nhóm thay đổi thường được xem là “an toàn” nhưng lại rủi ro với agent:

Thay đổi	Rủi ro với agent
Thêm trường bắt buộc	Agent có thể tự bịa giá trị để vượt qua lỗi xác thực.
Thêm giá trị enum	Agent có thể suy diễn sai ý nghĩa của giá trị mới.
Siết quy tắc xác thực	Agent chỉ học được quy tắc mới bằng cách thất bại.
Đổi giá trị mặc định	Ví dụ phân trang từ `100` xuống `20` khiến agent báo cáo tập dữ liệu không đầy đủ.
Viết lại tài liệu	Nếu công cụ được tạo từ đặc tả, mô tả mới có thể thay đổi cách mô hình chọn công cụ.

Mô tả công cụ đặc biệt quan trọng: thiết kế lược đồ công cụ API cho agent cho thấy hành vi của agent phụ thuộc rất nhiều vào văn bản mô tả.

Các thay đổi thường an toàn hơn gồm:

Thêm trường tùy chọn.
Thêm endpoint.
Thêm tham số tùy chọn nhưng giữ nguyên giá trị mặc định.
Nới lỏng xác thực.

Luôn ghim phiên bản API

Biện pháp đầu tiên là không cho phép API tự dịch chuyển bên dưới agent.

Gửi phiên bản rõ ràng trong mọi yêu cầu, dù API dùng đường dẫn, header hay ghim ở cấp tài khoản:

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

User-Agent cũng cần được nhận diện rõ. Khi nhà cung cấp cần cảnh báo ngừng hỗ trợ, họ thường dựa vào lưu lượng truy cập để xác định người gọi. Agent có tên rõ ràng có thể nhận được cảnh báo; agent dùng chuỗi thư viện mặc định thì không.

Ví dụ, GitHub API versioning dùng header ngày, còn Stripe ghim phiên bản theo tài khoản. Điểm chung là: API không đổi cho đến khi bạn chủ động nâng cấp.

Nếu bạn sở hữu API:

Công bố phiên bản rõ ràng.
Giữ phiên bản cũ trong thời gian hỗ trợ.
Công bố thay đổi phá vỡ trước khi loại bỏ.
Duy trì nhiều phiên bản song song khi cần.

Tham khảo chiến lược quản lý phiên bản API tốt nhất và quản lý phiên bản API trong Apidog.

Với API bên thứ ba không hỗ trợ versioning, hãy ghim thứ bạn kiểm soát được: hình dạng request/response mà agent đã được xây dựng để sử dụng.

Phát hiện drift trước khi agent chạy thật

Ghim phiên bản chỉ giúp bạn có thời gian. Bạn vẫn cần phát hiện drift trong CI và thời gian chạy.

1. Đối chiếu đặc tả theo lịch trình

Nếu nhà cung cấp công bố OpenAPI, hãy tải đặc tả hằng ngày và so sánh với bản đã dùng để tạo công cụ.

Cần phát hiện:

Trường bị xóa.
Kiểu dữ liệu thay đổi.
Thuộc tính bắt buộc mới.
Enum được mở rộng.
Mô tả công cụ bị chỉnh sửa.

Trong Apidog, bạn có thể lưu định nghĩa đã nhập và xem khác biệt giữa các phiên bản thay vì điều tra thủ công.

Nếu công cụ được sinh từ OpenAPI, thay đổi mô tả cũng đáng kiểm tra. Xem thêm hướng dẫn chuyển đổi đặc tả OpenAPI thành công cụ agent.

2. Kiểm tra hợp đồng cho mọi endpoint agent gọi

Với mỗi công cụ agent có thể gọi:

Gửi một request đã biết là hợp lệ.
Xác nhận các trường bắt buộc xuất hiện.
Xác nhận kiểu dữ liệu chính xác.
Xác nhận enum thuộc tập giá trị cho phép.

Cách này phát hiện drift ngay cả với API không công bố đặc tả. Tham khảo API contract testing và bidirectional contract testing.

3. Xác thực hình dạng response trong tool wrapper

Đặt lớp kiểm tra ngay trong wrapper của công cụ:

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

Quy tắc thực tế:

Thiếu trường bắt buộc: báo lỗi và dừng.
Có trường mới: cảnh báo, nhưng không nhất thiết làm gián đoạn lần chạy.

Trường bắt buộc bị thiếu nghĩa là agent đang làm việc với dữ liệu không đầy đủ. Trường mới thường là thay đổi bổ sung, nhưng vẫn cần đưa vào trace. Xem truy vết các cuộc gọi công cụ của AI agent.

4. Quan sát hành vi, không chỉ schema

Một số drift không xuất hiện trong kiểm tra hình dạng:

Giá trị mặc định thay đổi.
Giới hạn tốc độ bị siết.
Response chậm hơn.
Kích thước response giảm.

Theo dõi theo từng endpoint:

Số lần gọi trên mỗi tác vụ hoàn thành.
Tỷ lệ retry.
Thời gian phản hồi.
Kích thước phản hồi trung bình.
Tỷ lệ lỗi xác thực.

Thay đổi đáng kể ở các chỉ số này thường cho thấy upstream đã thay đổi.

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

Hãy coi nâng cấp API là một thay đổi đối với agent.

Tạo lại công cụ thay vì sửa tay.

Schema và mô tả sẽ được cập nhật cùng nhau. Sau đó review diff của định nghĩa công cụ được tạo.
Chạy agent với mock của phiên bản mới.

Mock dựa trên đặc tả mới cho phép chạy toàn bộ bộ tác vụ với response mới mà không chạm production. Xem chạy agent với mock API thay vì production.
Chạy lại bộ kiểm tra lựa chọn công cụ.

Mô tả thay đổi có thể khiến mô hình chọn công cụ khác dù schema không đổi. Kiểm tra một tập prompt cố định theo hướng dẫn kiểm thử AI agent không xác định.
Triển khai bằng feature flag.

Chuyển một phần lưu lượng sang phiên bản mới, vẫn giữ phiên bản cũ được ghim và sẵn sàng rollback.
So sánh chỉ số trong ít nhất một ngày.

Chú ý số lời gọi trên mỗi tác vụ và tỷ lệ retry. Đây thường là tín hiệu hồi quy xuất hiện trước khi người dùng báo lỗi.

Ba tình huống drift đã xảy ra trong production

1. Đổi tên trường

customer_name đổi thành customer_full_name. API vẫn trả 200, nhưng bỏ qua trường cũ. Agent tạo bản ghi tên trống trong hai tuần.

Cách phòng tránh: kiểm tra hình dạng response trong runtime. Nếu agent kỳ vọng đọc lại trường đó mà nó biến mất, lần gọi đầu tiên phải thất bại.

2. Thay đổi mặc định phân trang

Nhà cung cấp giảm kích thước trang mặc định từ 100 xuống 20. Agent không gửi limit, chỉ thấy 20 bản ghi và tóm tắt chúng như toàn bộ tập dữ liệu.

Cách phòng tránh: luôn gửi giá trị phân trang rõ ràng. Đừng để tính đúng đắn của agent phụ thuộc vào mặc định do bên khác kiểm soát.

3. Giá trị enum mới

Một API thanh toán thêm status: "disputed". Client có kiểu dữ liệu bỏ qua giá trị này. Agent lại suy diễn rằng khoản thanh toán tranh chấp là khoản hoàn tiền và báo cáo đối soát sai.

Cách phòng tránh: xác thực enum rõ ràng. Giá trị không quen thuộc phải tạo cảnh báo hoặc lỗi, không được giao cho mô hình tự diễn giải.

Biến cảnh báo ngừng hỗ trợ thành công việc

Nhà cung cấp thường cảnh báo qua changelog, email hoặc HTTP header. Hai header chuẩn cần theo dõi là:

Ghi nhận cảnh báo ngay lần đầu xuất hiện, thay vì đợi đến lần thứ một nghìn. Một header xuất hiện trong 3% request hôm nay có thể là sự cố toàn phần vào ngày endpoint bị loại bỏ.

Duy trì danh mục đơn giản cho mỗi phụ thuộc:

Agent	Nhà cung cấp	Phiên bản	Endpoint	Chủ sở hữu
billing-agent	Payment API	2026-06-01	`POST /charges`	Nhóm thanh toán

Khi có thông báo ngừng hỗ trợ, câu hỏi “chúng ta có bị ảnh hưởng không?” nên mất một phút, không phải cả buổi chiều.

Nếu agent chạy trong coding runtime thay vì một service truyền thống, nền tảng quản lý như Sharkly có thể giúp biến cảnh báo thành tác vụ được giao, có trace thực thi và kết quả rõ ràng.

Checklist triển khai

[ ] Mọi request gửi phiên bản API rõ ràng và User-Agent nhận diện agent.
[ ] Đặc tả API bên thứ ba được tải và đối chiếu theo lịch trình.
[ ] Mỗi tool có contract test xác nhận response shape.
[ ] Tool wrapper lỗi khi thiếu trường bắt buộc và cảnh báo khi xuất hiện trường mới.
[ ] Theo dõi số lời gọi, retry, độ trễ và kích thước response theo endpoint.
[ ] Nâng cấp phiên bản bằng cách tạo lại tool, không chỉnh sửa thủ công.
[ ] Chạy bộ tác vụ và bộ kiểm tra chọn tool với mock của phiên bản mới.
[ ] Triển khai sau feature flag, có rollback về phiên bản cũ được ghim.
[ ] Cảnh báo Deprecation và Sunset được tạo thành công việc có chủ sở hữu.

API sẽ tiếp tục thay đổi. Điều cần thiết là agent phải trở thành một client nhận biết được thay đổi: ghim phiên bản, kiểm tra hợp đồng và xác thực hình dạng response trong runtime.

Tải xuống Apidog để đối chiếu đặc tả và mô phỏng phiên bản API tiếp theo trước khi đưa vào production.

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

Tôi nên kiểm tra thay đổi đặc tả bên thứ ba bao lâu một lần?

Hằng ngày là đủ cho hầu hết API và rẻ để tự động hóa. Với API không công bố đặc tả, hãy dựa vào contract test chạy trong CI.

Tôi có nên luôn ghim vào phiên bản hoạt động cũ nhất không?

Không. Ghim để việc nâng cấp là có chủ ý, sau đó nâng cấp theo lịch trình. Giữ phiên bản cũ đến ngày bị gỡ bỏ sẽ biến thay đổi có kế hoạch thành tình huống khẩn cấp.

Nếu agent vẫn hoạt động sau thay đổi thì sao?

Hãy xác minh, đừng giả định. Những lỗi nguy hiểm nhất vẫn trả về 200, chẳng hạn trường bị đổi tên và bị bỏ qua âm thầm. Kiểm tra hình dạng response cho biết điều mà một lần chạy xanh không thể.

Tôi có cần quản lý versioning API khác đi cho agent không?

Không cần khác hoàn toàn, nhưng cần chặt chẽ hơn. Hãy coi trường bắt buộc mới, enum mới và giá trị mặc định thay đổi là breaking change đối với agent, ngay cả khi chúng chỉ là thay đổi bổ sung với client có kiểu dữ liệu.

Làm sao biết agent nào gọi endpoint nào?

Dùng trace: lưu tên tool, endpoint và kết quả theo từng lần chạy. Bản đồ phụ thuộc này cho biết chính xác agent nào bị ảnh hưởng bởi một thay đổi hoặc thông báo ngừng hỗ trợ.

Agent có thể tự thích ứng với API đã thay đổi không?

Đôi khi có, nhưng không nên dựa vào điều đó. Agent có thể ứng biến quanh trường bị thiếu và tạo ra kết quả hợp lý nhưng sai. Hãy báo lỗi rõ ràng và sửa tool thay vì để mô hình tự suy diễn.

DEV Community