Versioning API untuk Agen AI: Saat Perubahan Merusak Terjadi

Tim API mengubah nama sebuah field dari customer_name menjadi customer_full_name. Mereka mengumumkannya, memperbarui dokumen, dan setiap klien yang dikelola manusia menerima permintaan pull. Agen Anda tidak menerima apa pun, karena tidak ada yang menganggapnya sebagai klien. Agen tersebut terus mengirimkan field lama, API terus menerima permintaan dan mengabaikan kunci yang tidak dikenal, dan selama dua minggu setiap catatan yang dibuatnya memiliki nama kosong.

Agen adalah konsumen API yang paling tidak mampu menyadari perubahan dan paling mungkin untuk menutupi masalah tersebut. Klien manusia akan melemparkan pengecualian. Agen membaca kode 200, memutuskan panggilan berhasil, dan melanjutkan. Terkadang agen mengimprovisasi masalah dengan cara yang terlihat seperti keberhasilan.

Panduan ini membahas mengapa agen sangat rapuh terhadap penyimpangan API, perubahan apa yang dapat merusaknya yang tidak akan merusak klien biasa, cara mengunci dan mendeteksi versi, serta cara menangkap penyimpangan dalam CI sebelum dijalankan. Postingan kami tentang mengapa agen AI rusak dalam produksi mencakup mode kegagalannya; ini adalah salah satu yang datang dari luar basis kode Anda.

Apidog penting di sini karena deteksi adalah masalah spesifikasi. Jika Anda memiliki versi definisi API sebelumnya dan versi saat ini, perbedaannya bersifat mekanis.

Mengapa agen kurang menyadari dibandingkan klien

Empat properti ini bersama-sama menimbulkan masalah.

Toleransi senyap. Kebanyakan API mengabaikan field yang tidak dikenal dalam body permintaan. Field yang diubah namanya berarti field baru tidak ada dan field lama dibuang, dengan kode 200 saat keluar. Tidak ada yang menimbulkan masalah.

Improvisasi. Ketika respons kehilangan nilai, model sering kali akan melanjutkan dengan pengganti yang masuk akal daripada berhenti. Itu adalah perilaku yang membantu dalam percakapan dan perilaku yang berbahaya terhadap API.

Deskripsi dalam prompt. Deskripsi alat agen mengkodekan asumsi tentang API dalam teks. Ketika API berubah, deskripsi menjadi sedikit salah, dan deskripsi yang salah menghasilkan panggilan yang salah tanpa melibatkan kode apa pun. Postingan kami tentang desain skema alat membahas seberapa banyak perilaku yang bergantung pada teks tersebut.

Tanpa kompiler. Klien yang bertipe akan rusak pada saat build ketika sebuah field menghilang. Kontrak agen terletak pada skema JSON dan prosa, dan tidak ada yang memeriksanya sampai panggilan gagal, atau lebih buruk lagi, sampai ada yang diam-diam tidak.

Intinya: perubahan yang aman untuk klien biasa tidak selalu aman untuk agen, dan Anda harus mengklasifikasikannya secara terpisah.

Perubahan apa saja yang benar-benar merusak agen

Pembagian biasa antara penambahan-versus-perusakan masih berlaku, dan agen menambahkan kategori tengah.

Benar-benar merusak, untuk semua orang. Menghapus endpoint, menghapus field, mengganti nama field, mengubah tipe, membuat parameter opsional menjadi wajib, mengubah URL. Agen juga rusak di sini, hanya saja lebih senyap.

Aman untuk klien bertipe, berisiko untuk agen:

• Field baru yang wajib. Setiap pemanggil yang ada akan rusak, tetapi agen akan rusak dengan kesalahan validasi yang mungkin akan dicoba diperbaiki dengan menciptakan nilai. Itu lebih buruk daripada kegagalan keras.
• Nilai enum baru. Klien biasa mengabaikan apa yang tidak mereka tangani. Agen dapat bernalar tentang nilai yang tidak dikenal dan menarik kesimpulan yang tidak pernah dimaksudkan oleh produk Anda.
• Aturan validasi yang diperketat. Sebuah field yang dulunya menerima string apa pun kini membutuhkan pola. Agen tidak punya cara untuk mempelajari pola kecuali dengan gagal, itulah sebabnya aturan tersebut harus ada dalam pesan kesalahan, seperti yang dibahas dalam postingan kami tentang desain kesalahan API untuk agen AI.
• Default yang diubah. Default paginasi turun dari 100 menjadi 20 dan agen, yang tidak pernah mengirimkan batas, kini melihat seperlima data dan melaporkannya seolah-olah lengkap.
• Dokumentasi yang diubah kata-katanya. Tidak ada perubahan perilaku sama sekali, tetapi jika alat Anda dihasilkan dari spesifikasi, seperti dalam panduan kami untuk mengubah spesifikasi OpenAPI menjadi alat agen, teks deskripsi berubah dan pemilihan alat dapat bergeser bersamanya.

Aman juga untuk agen. Menambahkan field opsional, menambahkan endpoint, menambahkan parameter opsional dengan default yang dipertahankan, melonggarkan validasi.

Daftar tengah itulah yang perlu diperhatikan, karena tidak ada dalam tinjauan perubahan standar yang menandainya.

Sematkan versi, selalu

Pertahanan pertama adalah menolak untuk berpindah secara implisit.

Kirimkan versi eksplisit pada setiap permintaan, mekanisme apa pun yang ditawarkan API: segmen jalur, header, atau pin tingkat akun. Dokumentasi versi API GitHub menggunakan header tanggal, dan Stripe menyematkan versi per akun dengan langkah upgrade eksplisit. Keduanya memberi Anda properti yang sama: tidak ada yang berubah di bawah Anda sampai Anda memutuskan.

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. Ketika penyedia API perlu memperingatkan pemanggil tentang depresiasi, mereka melihat lalu lintas. Agen yang mengidentifikasi dirinya akan menerima email; agen yang mengirimkan string library default tidak akan.

Jika Anda memiliki API, publikasikan versi dan pertahankan. Panduan kami tentang strategi versi API terbaik mencakup pilihan-pilihan, dan mengelola versi API di Apidog mencakup cara menjaga beberapa versi tetap aktif sekaligus.

Untuk API pihak ketiga yang sama sekali tidak memiliki versi, sematkan apa pun yang Anda bisa: catat bentuk respons yang Anda gunakan untuk membangun dan periksalah, yang merupakan bagian selanjutnya.

Deteksi penyimpangan sebelum dijalankan

Penyematan memberi waktu. Ini tidak menghentikan upgrade yang pada akhirnya akan terjadi, dan tidak berguna untuk API yang berubah tanpa versi. Jadi, deteksi.

Bandingkan spesifikasi sesuai jadwal. Jika penyedia memublikasikan dokumen OpenAPI, ambil setiap hari dan bandingkan dengan salinan yang Anda gunakan untuk menghasilkan alat. Field yang dihapus, tipe yang diubah, persyaratan yang ditambahkan, enum yang diperluas, deskripsi yang diedit. Di Apidog Anda dapat menyimpan definisi yang diimpor dalam proyek dan melihat apa yang berubah antar versi, yang mengubah pertanyaan "apakah ada yang berubah" menjadi laporan daripada penyelidikan.

Uji kontrak endpoint yang Anda panggil. Untuk setiap alat yang dimiliki agen, kirimkan permintaan yang sudah terbukti baik dan lakukan penegasan pada bentuk respons: field wajib ada, tipe benar, nilai enum dalam set yang Anda harapkan. Ini menangkap penyimpangan di API yang sama sekali tidak memublikasikan spesifikasi, yang merupakan sebagian besar di antaranya. Panduan pengujian kontrak API kami mencakup polanya, dan pengujian kontrak dua arah mencakup cara menjalankannya dari kedua sisi.

Tegaskan bentuk pada saat runtime. Validasi respons dalam pembungkus alat terhadap skema yang Anda harapkan, dan log peringatan ketika sesuatu yang tidak terduga muncul. Ini adalah garis pertahanan terakhir, dan ini yang menangkap perubahan yang tidak diumumkan oleh siapa pun.

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

Gagal jika ada yang hilang, peringatkan jika ada yang berlebihan. Field wajib yang hilang berarti agen akan bekerja dengan data yang tidak lengkap, yang merupakan kegagalan yang patut dihentikan. Field baru biasanya bersifat tambahan dan patut diketahui tanpa mengganggu jalannya proses. Arahkan keduanya ke catatan jejak yang dijelaskan dalam postingan kami tentang pelacakan panggilan alat agen AI.

Perhatikan perilaku, bukan hanya skema. Beberapa penyimpangan tidak terlihat oleh pemeriksaan bentuk: default yang berubah, batas tarif yang diperketat, respons yang menjadi lebih lambat. Lacak panggilan per tugas yang selesai, tingkat percobaan ulang per endpoint, dan ukuran respons rata-rata per alat. Perubahan signifikan pada salah satu di antaranya biasanya berarti ada sesuatu yang bergerak di hulu.

Upgrade tanpa merusak agen

Ketika Anda beralih ke versi baru, perlakukan itu sebagai perubahan pada agen, karena memang demikian.

Hasilkan ulang alat daripada mengeditnya secara manual, agar deskripsi dan skema bergerak bersama. Kemudian baca perbedaan definisi alat yang dihasilkan. Perbedaan itulah jangkauan dampak sebenarnya, dan seringkali lebih kecil atau lebih besar dari yang diisyaratkan oleh changelog API.

Jalankan agen terhadap mock versi baru sebelum mengarahkannya ke sesuatu yang live. Ini adalah langkah paling berharga dan yang paling sering dilewatkan: mock yang dibangun dari spesifikasi baru memungkinkan Anda menjalankan seluruh rangkaian tugas Anda terhadap bentuk-bentuk baru tanpa risiko, mengikuti postingan kami tentang menjalankan agen terhadap mock alih-alih produksi.

Jalankan kembali rangkaian pemilihan. Perubahan deskripsi mengubah alat mana yang dipilih model, dan regresi itu tidak terlihat oleh perbedaan skema. Tegaskan pilihan alat untuk sekumpulan prompt tetap, seperti dalam panduan kami untuk menguji agen non-deterministik.

Luncurkan di balik flag, pada sebagian kecil lalu lintas, dengan versi lama yang masih disematkan dan siap. Amati empat angka yang sama selama sehari. Regresi agen muncul sebagai lebih banyak panggilan per tugas dan lebih banyak percobaan ulang jauh sebelum ada yang mengajukan keluhan.

Tiga penyimpangan yang sampai ke produksi

Field yang diganti namanya. Kisah pembuka. Kode 200 pada setiap panggilan, nama kosong pada setiap catatan, ditemukan dua minggu kemudian oleh seorang manusia yang membaca laporan. Pemeriksaan bentuk runtime pada respons akan menangkapnya pada panggilan pertama, karena field yang diharapkan agen untuk dibaca kembali sudah hilang.

Default paginasi yang diperketat. Sebuah penyedia menurunkan ukuran halaman default dari 100 menjadi 20. Agen tidak pernah mengirimkan limit, sehingga mulai melihat 20 catatan dan merangkumnya sebagai set lengkap. Tidak ada yang menimbulkan kesalahan. Rangkuman-rangkuman itu hanya salah, dengan cara yang terlihat meyakinkan. Perbaikannya hanya satu baris, yaitu mengirimkan limit secara eksplisit, dan pelajarannya lebih luas: bergantung pada default berarti Anda memiliki ketergantungan yang tidak dideklarasikan pada keputusan orang lain.

Nilai enum baru. Sebuah API pembayaran menambahkan status: "disputed". Klien bertipe mengabaikannya. Agen bernalar tentang hal itu, memutuskan bahwa biaya yang disengketakan dihitung sebagai pengembalian dana, dan melaporkan buku-buku yang telah direkonsiliasi yang sebenarnya tidak. Validasi enum eksplisit akan menimbulkan masalah pada nilai yang tidak dikenal alih-alih membiarkan model menafsirkannya.

Polanya: setiap perubahan diumumkan, setiap perubahan bersifat aditif atau minor menurut klasifikasi penyedia, dan setiap perubahan merusak bagi agen. Kesenjangan itulah yang harus dirancang.

Perlakukan depresiasi sebagai item pekerjaan

Penyedia biasanya memberi Anda peringatan. Peringatan tersebut tiba dalam changelog, email, atau header Deprecation pada respons, dan mudah bagi tidak satu pun dari itu untuk sampai kepada orang yang memelihara agen.

Hubungkan mereka ke antrean normal Anda. Header Deprecation dan Header Sunset keduanya terstandardisasi, sehingga pemeriksaan generik berfungsi di seluruh penyedia. Catat mereka ketika muncul, dan berikan peringatan pada penampakan pertama daripada yang keseribu. Header yang muncul pada 3 persen panggilan hari ini akan menjadi pemadaman total pada tanggal sunset.

Simpan juga inventaris: agen mana, penyedia mana, versi mana, endpoint mana, dan siapa pemiliknya. Sepuluh baris dalam file sudah cukup. Ketika pemberitahuan depresiasi tiba, pertanyaan "apakah ini memengaruhi kita" seharusnya memakan waktu satu menit, bukan satu sore untuk mencari.

Penyimpangan adalah pekerjaan, jadi berikan pemiliknya

Deteksi menghasilkan antrean: perbedaan spesifikasi, pengujian kontrak yang gagal, header depresiasi yang terlihat untuk pertama kalinya. Masing-masing adalah sedikit pekerjaan dengan tenggat waktu terlampir, dan mode kegagalannya adalah ia hanya duduk di saluran yang tidak dimiliki siapa pun sampai tanggal sunset tiba.

Tempatkan mereka di mana tim Anda sudah melacak pekerjaan. Jika agen Anda berjalan sebagai runtime pengkodean daripada sebagai layanan yang Anda deploy, platform yang mengelolanya dapat menutup lingkaran: Sharkly menetapkan Tugas ke Agen atau Kru dan menjaga tujuan, jejak eksekusi, dan tinjauan di satu tempat, sehingga "API pembayaran mendepresiasi endpoint ini" menjadi tugas yang ditugaskan dengan hasil daripada pesan dalam sebuah thread. Apa pun yang Anda gunakan, aturannya sama. Peringatan penyimpangan tanpa pemilik adalah depresiasi yang akan Anda temui lagi pada hari ketika ia rusak.

Daftar periksa

• Setiap permintaan mengirimkan versi API eksplisit dan User-Agent yang mengidentifikasi.
• Dokumen spesifikasi pihak ketiga diambil dan dibandingkan sesuai jadwal.
• Setiap alat yang dapat dipanggil agen memiliki pengujian kontrak yang menegaskan bentuk respons.
• Pembungkus alat memvalidasi respons pada saat runtime: gagal jika hilang, peringatkan jika baru.
• Metrik perilaku dilacak per endpoint sehingga penyimpangan senyap muncul ke permukaan.
• Upgrade versi meregenerasi alat daripada mengeditnya secara manual.
• Rangkaian tugas dan rangkaian pemilihan keduanya dijalankan terhadap mock versi baru terlebih dahulu.
• Peluncuran ditandai dan dapat dibalik, dengan versi sebelumnya masih disematkan.

Tim API akan terus mengirimkan perubahan, dan itu tidak masalah. Yang Anda butuhkan adalah agen Anda menjadi klien yang menyadari, yang membutuhkan pin versi, pengujian kontrak, dan pemeriksaan 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 untuk perubahan? Setiap hari sudah cukup untuk sebagian besar, dan murah untuk diotomatisasi. Untuk API tanpa spesifikasi yang dipublikasikan, andalkan pengujian kontrak yang berjalan di CI sebagai gantinya, karena mereka mendeteksi penyimpangan yang sama dari luar.

Haruskah saya selalu menyematkan ke versi kerja tertua? Tidak. Sematkan agar upgrade disengaja, lalu upgrade sesuai jadwal. Berdiam diri pada versi lama sampai dihapus mengubah perubahan yang direncanakan menjadi keadaan darurat.

Bagaimana jika agen berfungsi dengan baik setelah perubahan? Verifikasi daripada berasumsi. Hasil berbahaya adalah yang masih mengembalikan kode 200, seperti field yang diganti namanya yang diam-diam dihilangkan. Penegasan bentuk memberi tahu Anda apa yang tidak bisa dilakukan oleh eksekusi yang berhasil.

Apakah saya perlu membuat versi API saya sendiri secara berbeda untuk agen? Tidak berbeda, tetapi lebih ketat. Perlakukan field wajib baru, nilai enum baru, dan default yang diubah sebagai pemecah untuk konsumen agen meskipun bersifat aditif untuk klien bertipe, dan umumkan dengan cara yang sama.

Bagaimana saya tahu agen mana yang memanggil endpoint mana? Dari jejak Anda. Nama alat ditambah endpoint per eksekusi memberi Anda peta dependensi, dan itu memberi tahu Anda dengan tepat siapa yang terpengaruh oleh depresiasi. Postingan kami tentang pelacakan panggilan alat agen AI mencakup bentuk catatan.

Bisakah agen beradaptasi dengan API yang berubah sendiri? Kadang-kadang, dan Anda tidak boleh mengandalkannya. Model yang berimprovisasi di sekitar field yang hilang menghasilkan keluaran yang masuk akal tanpa sinyal bahwa ada yang salah. Gagal dengan keras dan perbaiki alatnya saja.