Versioning API untuk Agen AI: Saat Perubahan Merusak Terjadi

Mengapa API Drift Lebih Berbahaya bagi Agen AI

Tim API mengubah nama field dari customer_name menjadi customer_full_name. Mereka mengumumkannya, memperbarui dokumentasi, dan mengirim pull request kepada setiap klien yang dikelola manusia.

Agen Anda tidak menerima apa pun karena tidak ada yang menganggapnya sebagai klien. Agen itu terus mengirimkan field lama. API tetap mengembalikan kode 200, mengabaikan key yang tidak dikenal, dan selama dua minggu setiap catatan yang dibuat memiliki nama kosong.

Coba Apidog hari ini

Agen adalah konsumen API yang paling sulit menyadari perubahan dan paling mungkin menutupi masalah. Klien manusia biasanya melempar exception. Agen membaca respons 200, menganggap panggilan berhasil, lalu melanjutkan proses. Saat respons kehilangan nilai, model bahkan dapat mengimprovisasi pengganti yang terlihat masuk akal.

Panduan ini membahas:

• perubahan API yang merusak agen, tetapi mungkin tidak merusak klien biasa;
• cara menyematkan dan mendeteksi versi API;
• cara menangkap API drift di CI sebelum mencapai produksi;
• cara melakukan upgrade tanpa merusak agen.

Baca juga mengapa agen AI rusak dalam produksi untuk melihat mode kegagalan lainnya.

Apidog relevan karena deteksi drift adalah masalah spesifikasi. Jika Anda memiliki versi definisi API sebelumnya dan versi saat ini, perbedaannya dapat dibandingkan secara mekanis.

Mengapa agen kurang menyadari perubahan API

Empat karakteristik berikut menciptakan masalah.

1. Toleransi senyap

Banyak API mengabaikan field yang tidak dikenal dalam request body. Jika field diganti nama, field baru tidak pernah dikirim dan field lama dibuang. API tetap mengembalikan 200.

Tidak ada error yang menghentikan proses.

2. Improvisasi

Ketika respons kehilangan nilai, model sering melanjutkan dengan pengganti yang dianggap masuk akal daripada berhenti. Perilaku ini membantu dalam percakapan, tetapi berbahaya saat berinteraksi dengan API.

3. Deskripsi dalam prompt

Deskripsi tool agen menyimpan asumsi tentang API dalam bentuk teks. Ketika API berubah, deskripsi menjadi sedikit keliru. Deskripsi yang keliru dapat menghasilkan pemilihan tool dan request yang salah tanpa perubahan kode.

Baca desain skema tool untuk agen untuk memahami seberapa besar perilaku agen bergantung pada deskripsi tersebut.

4. Tidak ada compiler

Klien bertipe biasanya gagal saat build ketika sebuah field dihapus atau tipenya berubah. Kontrak agen berada di skema JSON dan prosa, sehingga tidak ada yang memeriksanya sampai request gagal—atau, yang lebih buruk, sampai kegagalan itu tidak pernah diketahui.

Kesimpulan: perubahan yang aman untuk klien biasa belum tentu aman untuk agen. Keduanya perlu diklasifikasikan secara terpisah.

Perubahan yang benar-benar merusak agen

Klasifikasi umum antara perubahan aditif dan breaking change masih berlaku, tetapi agen menambahkan kategori di tengah.

Breaking change untuk semua klien

Perubahan berikut merusak klien biasa maupun agen:

• menghapus endpoint;
• menghapus field;
• mengganti nama field;
• mengubah tipe field;
• menjadikan parameter opsional sebagai wajib;
• mengubah URL.

Agen juga rusak pada kasus ini, tetapi sering kali dengan cara yang lebih senyap.

Berisiko untuk agen, meskipun tampak aman bagi klien bertipe

Field wajib baru

Klien lama akan gagal validasi. Agen mungkin mencoba memperbaikinya dengan menciptakan nilai sendiri. Hasilnya lebih buruk daripada kegagalan keras karena nilai tersebut bisa terlihat valid tetapi salah.

Nilai enum baru

Klien biasa mungkin mengabaikan nilai yang tidak ditangani. Agen dapat menalar tentang nilai baru dan menarik kesimpulan yang tidak pernah dimaksudkan oleh produk Anda.

Validasi yang diperketat

Field yang sebelumnya menerima string apa pun kini mungkin memerlukan pola tertentu. Agen tidak dapat mempelajari pola tersebut kecuali dari kegagalan.

Karena itu, aturan validasi harus dijelaskan dalam pesan error. Lihat desain pesan error API untuk agen AI.

Default yang berubah

Misalnya, default paginasi turun dari 100 menjadi 20. Agen yang tidak pernah mengirimkan limit hanya melihat seperlima data, tetapi melaporkannya seolah-olah lengkap.

Dokumentasi yang diubah

Tidak ada perubahan perilaku API, tetapi deskripsi tool dapat berubah jika tool dibuat dari spesifikasi. Perubahan teks ini dapat memengaruhi pemilihan tool.

Baca mengubah spesifikasi OpenAPI menjadi tool agen.

Aman juga untuk agen

Biasanya perubahan berikut aman:

• menambahkan field opsional;
• menambahkan endpoint;
• menambahkan parameter opsional dengan default yang sama;
• melonggarkan validasi.

Kategori tengah—perubahan yang aditif menurut penyedia, tetapi berisiko bagi agen—itulah yang sering lolos dari tinjauan perubahan standar.

Sematkan versi API secara eksplisit

Pertahanan pertama adalah menolak perubahan implisit.

Kirim versi eksplisit pada setiap request menggunakan mekanisme yang disediakan API: segmen path, header, atau pin tingkat akun. Dokumentasi versi API GitHub menggunakan header berbasis tanggal, sementara Stripe menyematkan versi per akun dengan proses upgrade eksplisit.

Keduanya memberikan properti yang sama: tidak ada perubahan di bawah Anda sampai Anda memilih untuk melakukan upgrade.

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

User-Agent sama pentingnya dengan pin versi. Saat penyedia API perlu memperingatkan pemanggil tentang depresiasi, mereka dapat menelusuri traffic. Agen yang mengidentifikasi dirinya dapat menerima peringatan; agen yang hanya mengirim string library default mungkin tidak.

Jika Anda memiliki API sendiri, publikasikan versi dan pertahankan versinya. Lihat strategi versioning API terbaik dan cara mengelola versi API di Apidog.

Untuk API pihak ketiga yang tidak memiliki versioning, sematkan apa pun yang bisa Anda kontrol: catat bentuk respons yang digunakan saat pengembangan dan validasi bentuk tersebut secara rutin.

Deteksi API drift sebelum produksi

Pin versi memberi Anda waktu, tetapi tidak menghentikan upgrade selamanya dan tidak membantu jika API berubah tanpa versi. Karena itu, tambahkan deteksi.

Bandingkan spesifikasi secara terjadwal

Jika penyedia menerbitkan dokumen OpenAPI, ambil dokumen tersebut setiap hari dan bandingkan dengan salinan yang digunakan untuk menghasilkan tool.

Cari perubahan berikut:

• field yang dihapus;
• tipe yang berubah;
• field wajib baru;
• enum yang diperluas;
• deskripsi yang diedit.

Di Apidog, Anda dapat menyimpan definisi yang diimpor dalam satu proyek dan membandingkan perubahan antarversi. Pertanyaan “apakah ada yang berubah?” menjadi laporan yang dapat ditinjau, bukan investigasi manual.

Uji kontrak endpoint

Untuk setiap tool agen, kirim request yang sudah terbukti valid dan tegaskan bentuk responsnya:

• field wajib harus ada;
• tipe data harus benar;
• nilai enum harus berada dalam set yang diharapkan.

Teknik ini juga menangkap drift pada API yang tidak menerbitkan spesifikasi. Lihat pengujian kontrak API dan pengujian kontrak dua arah.

Validasi bentuk saat runtime

Validasi respons di dalam wrapper tool terhadap skema yang diharapkan. Gagal jika field wajib hilang, tetapi cukup beri peringatan jika muncul field baru.

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_drift", tool=tool_name, missing=missing)
        raise ApiDriftError(f"{tool_name}: missing fields {missing}")
    if extra:
        log.warning("api_new_fields", tool=tool_name, fields=extra)
    return payload

Aturannya sederhana:

• Field wajib hilang: hentikan proses. Agen akan bekerja dengan data yang tidak lengkap.
• Field baru muncul: catat dan beri peringatan. Field tersebut biasanya bersifat tambahan.

Arahkan kedua jenis sinyal ini ke trace. Pelacakan panggilan tool agen AI membahas struktur catatan yang diperlukan.

Pantau perilaku, bukan hanya skema

Sebagian drift tidak terlihat dari pemeriksaan bentuk:

• default yang berubah;
• rate limit yang diperketat;
• respons yang menjadi lebih lambat.

Lacak metrik berikut per task dan endpoint:

• jumlah panggilan per task yang selesai;
• tingkat retry per endpoint;
• ukuran rata-rata respons per tool.

Perubahan signifikan pada metrik tersebut biasanya menunjukkan ada sesuatu yang bergerak di hulu.

Upgrade tanpa merusak agen

Perlakukan perpindahan versi API sebagai perubahan pada agen, karena memang demikian.

Regenerasi tool

Buat ulang tool dari spesifikasi terbaru, bukan mengeditnya secara manual. Dengan begitu, deskripsi dan skema bergerak bersama. Setelah itu, tinjau diff definisi tool yang dihasilkan.

Diff tersebut menunjukkan cakupan dampak sebenarnya—yang bisa lebih kecil atau lebih besar daripada yang terlihat dari changelog API.

Jalankan agen terhadap mock

Sebelum mengarahkannya ke API live, jalankan agen terhadap mock versi baru. Mock yang dibuat dari spesifikasi terbaru memungkinkan seluruh rangkaian task diuji terhadap bentuk baru tanpa risiko produksi.

Lihat cara menjalankan agen terhadap mock, bukan produksi.

Uji ulang pemilihan tool

Perubahan deskripsi dapat mengubah tool yang dipilih model. Regresi ini tidak selalu terlihat dari diff skema.

Gunakan sekumpulan prompt tetap dan tegaskan pilihan tool untuk setiap prompt. Pengujian agen non-deterministik membahas cara menguji perilaku tersebut.

Rilis bertahap

Luncurkan versi baru di balik feature flag dan arahkan hanya sebagian kecil traffic ke sana. Pertahankan versi lama yang masih disematkan dan siap digunakan kembali.

Amati metrik selama setidaknya satu hari. Regresi agen biasanya terlihat sebagai peningkatan jumlah panggilan per task dan retry sebelum pengguna mengajukan keluhan.

Tiga API drift yang bisa mencapai produksi

1. Field diganti nama

Pada kasus pembuka, semua request mengembalikan 200, tetapi setiap nama catatan kosong. Masalah baru ditemukan dua minggu kemudian ketika seseorang membaca laporan.

Validasi bentuk runtime akan menangkapnya pada request pertama karena field yang diharapkan agen untuk dibaca kembali sudah hilang.

2. Default paginasi diperketat

Penyedia menurunkan default ukuran halaman dari 100 menjadi 20. Agen tidak pernah mengirim limit, lalu mulai melihat 20 catatan dan merangkumnya sebagai keseluruhan data.

Tidak ada error. Ringkasannya hanya salah dengan cara yang meyakinkan.

Perbaikannya sederhana: kirim limit secara eksplisit. Pelajarannya lebih luas: bergantung pada default berarti Anda memiliki ketergantungan yang tidak dideklarasikan pada keputusan penyedia API.

3. Nilai enum baru

API pembayaran menambahkan status disputed. Klien bertipe mengabaikannya. Agen justru menalar tentang status tersebut, memutuskan bahwa biaya yang disengketakan adalah refund, lalu melaporkan buku yang tampak sudah direkonsiliasi padahal tidak.

Validasi enum eksplisit akan menghentikan proses saat menemukan nilai yang tidak dikenal, alih-alih membiarkan model menafsirkannya.

Polanya jelas: perubahan yang diumumkan, aditif, atau minor bagi penyedia tetap dapat menjadi breaking change bagi agen. Kesenjangan inilah yang perlu dirancang.

Jadikan depresiasi sebagai item pekerjaan

Penyedia biasanya mengirim peringatan melalui changelog, email, atau header Deprecation pada respons. Namun, peringatan tersebut mudah tidak sampai kepada orang yang memelihara agen.

Hubungkan peringatan itu ke antrean kerja normal Anda. Header Deprecation dan Sunset sudah distandardisasi, sehingga pemeriksaan generik dapat digunakan lintas penyedia:

• catat ketika header muncul;
• beri peringatan pada kemunculan pertama;
• buat task dengan endpoint, versi, dan tanggal sunset.

Header yang muncul pada 3% request hari ini dapat berubah menjadi pemadaman total pada tanggal sunset.

Gunakan referensi Header Deprecation dan Header Sunset.

Simpan juga inventaris sederhana:

Agen	Penyedia	Versi	Endpoint	Pemilik
billing-agent	Payment API	2026-06-01	/charges	Tim Billing

Ketika peringatan depresiasi tiba, pertanyaan “apakah ini memengaruhi kita?” seharusnya terjawab dalam satu menit, bukan setelah seharian mencari dependensi.

Beri pemilik pada setiap penyimpangan

Deteksi menghasilkan antrean pekerjaan:

• diff spesifikasi;
• pengujian kontrak yang gagal;
• header depresiasi yang baru terlihat.

Tanpa pemilik, semuanya hanya akan duduk di channel yang tidak dipantau sampai tanggal sunset tiba.

Tempatkan temuan tersebut di sistem yang sudah digunakan tim. Jika agen berjalan sebagai runtime coding, bukan layanan yang Anda deploy sendiri, platform pengelolanya dapat menutup lingkaran ini. Sharkly dapat menetapkan task kepada Agen atau Kru dan menyimpan tujuan, execution trace, serta review dalam satu tempat.

Apa pun platformnya, aturannya sama:

Peringatan drift tanpa pemilik adalah depresiasi yang akan Anda temui lagi saat sistem sudah rusak.

Checklist kesiapan agen terhadap API drift

• [ ] Setiap request mengirim versi API eksplisit dan User-Agent yang mengidentifikasi agen.
• [ ] Spesifikasi pihak ketiga diambil dan dibandingkan secara terjadwal.
• [ ] Setiap tool yang dapat dipanggil agen memiliki contract test untuk bentuk respons.
• [ ] Wrapper tool memvalidasi respons saat runtime: gagal jika field hilang, peringatkan jika field baru muncul.
• [ ] Metrik perilaku dilacak per endpoint.
• [ ] Upgrade versi meregenerasi tool, bukan mengeditnya secara manual.
• [ ] Rangkaian task dan pemilihan tool dijalankan terhadap mock versi baru.
• [ ] Rilis menggunakan feature flag dan dapat dibalik.
• [ ] Versi sebelumnya tetap disematkan selama rollout.

Tim API akan terus mengirimkan perubahan, dan itu tidak masalah. Yang Anda butuhkan adalah agen yang menjadi klien API yang sadar versi: menggunakan pin versi, contract test, serta validasi bentuk runtime.

Unduh Apidog untuk membandingkan spesifikasi dan membuat mock versi berikutnya sebelum mencapai produksi.

Pertanyaan yang sering diajukan

Seberapa sering saya harus memeriksa spesifikasi pihak ketiga?

Pemeriksaan harian sudah cukup untuk sebagian besar API dan mudah diotomatisasi. Untuk API tanpa spesifikasi publik, gunakan contract test di CI agar drift tetap terdeteksi.

Haruskah saya selalu menggunakan versi kerja tertua?

Tidak. Sematkan versi agar upgrade menjadi keputusan yang disengaja, lalu upgrade sesuai jadwal. Bertahan pada versi lama sampai dihapus hanya mengubah perubahan terencana menjadi keadaan darurat.

Bagaimana jika agen tetap berfungsi setelah perubahan?

Verifikasi, jangan berasumsi. Hasil paling berbahaya adalah respons yang tetap mengembalikan 200, seperti field yang diam-diam diabaikan setelah diganti nama.

Validasi bentuk memberi sinyal yang tidak bisa diberikan oleh eksekusi yang “berhasil”.

Apakah saya perlu membuat versioning API yang berbeda untuk agen?

Tidak perlu berbeda, tetapi harus lebih ketat. Perlakukan field wajib baru, nilai enum baru, dan default yang berubah sebagai breaking change untuk konsumen agen, meskipun perubahan tersebut aditif bagi klien bertipe.

Bagaimana saya tahu agen mana yang memanggil endpoint tertentu?

Gunakan trace. Nama tool dan endpoint pada setiap eksekusi akan membentuk peta dependensi dan menunjukkan agen yang terdampak oleh depresiasi.

Lihat kembali pelacakan panggilan tool agen AI.

Bisakah agen beradaptasi sendiri terhadap API yang berubah?

Kadang-kadang, tetapi jangan mengandalkannya. Model dapat mengimprovisasi di sekitar field yang hilang dan menghasilkan output yang masuk akal tanpa sinyal bahwa ada yang salah.

Lebih aman untuk gagal dengan keras, memperbaiki tool, lalu melakukan upgrade secara terkontrol.