Yapay Zeka Ajanları için API Sürümleme: Kırıcı Değişiklikler Vurduğunda

API ekibi bir alanı customer_name'den customer_full_name'e yeniden adlandırdı. Bunu duyurdular, belgeleri güncellediler ve insan tarafından sürdürülen her istemci bir çekme isteği aldı. Aracınız hiçbir şey almadı, çünkü kimse onu bir istemci olarak düşünmedi. Eski alanı göndermeye devam etti, API isteği kabul edip bilinmeyen anahtarı görmezden gelmeye devam etti ve iki hafta boyunca oluşturduğu her kaydın adı boştu.

Aracılar, bir değişikliği fark etme olasılığı en düşük ve onu örtbas etme olasılığı en yüksek API tüketicileridir. İnsan bir istemci istisna fırlatır. Bir aracı 200 okur, çağrının çalıştığına karar verir ve devam eder. Bazen sorunu başarı gibi görünen bir şekilde doğaçlama yapar.

Bu kılavuz, aracıların neden API kaymasına karşı alışılmadık derecede kırılgan olduğunu, sıradan istemcileri bozmayacak hangi değişikliklerin onları bozduğunu, sürümlerin nasıl sabitleneceğini ve tespit edileceğini ve bir çalıştırma gerçekleşmeden önce CI'da kaymanın nasıl yakalanacağını kapsar. Üretimde yapay zeka aracılarının neden bozulduğuna dair yazımız hata modlarını kapsar; bu, kod tabanınızın dışından gelen hatadır.

Apidog burada önemlidir çünkü tespit bir spesifikasyon sorunudur. Bir API tanımının önceki sürümüne ve mevcut sürümüne sahipseniz, fark mekaniktir.

düğme

Aracılar Neden İstemcilerden Daha Az Fark Eder?

Dört özellik kötü bir şekilde birleşiyor.

Sessiz hoşgörü. Çoğu API, istek gövdesindeki bilinmeyen alanları görmezden gelir. Yeniden adlandırılan bir alan, yenisinin eksik olduğu ve eskisinin 200 ile atıldığı anlamına gelir. Hiçbir şey yükselmez.

Doğaçlama. Bir yanıtta bir değer eksik olduğunda, bir model genellikle durmak yerine makul bir ikame ile devam eder. Bu, sohbette faydalı bir davranış, ancak bir API'ye karşı tehlikeli bir davranıştır.

İstemdeki açıklamalar. Aracı aracı açıklamaları, API hakkındaki varsayımları metne kodlar. API değiştiğinde, açıklamalar incelikle yanlış hale gelir ve yanlış açıklamalar, herhangi bir kod dahil olmadan yanlış çağrılar üretir. Araç şeması tasarımı hakkındaki yazımız, o metne ne kadar davranışın bağlı olduğunu kapsar.

Derleyici yok. Yazılmış bir istemci, bir alan kaybolduğunda derleme zamanında bozulur. Bir aracının sözleşmesi JSON şemalarında ve düz yazıda yaşar ve hiçbir şey, bir çağrı başarısız olana kadar veya daha kötüsü, sessizce başarısız olana kadar onu kontrol etmez.

Sonuç olarak: tipik istemciler için güvenli olan değişiklikler, aracılar için her zaman güvenli değildir ve bunları ayrı ayrı sınıflandırmalısınız.

Hangi değişiklikler aslında aracıları bozuyor?

Her zamanki eklemeli-bozucu ayrımı hala geçerlidir ve aracılar orta bir kategori ekler.

Gerçekten bozucu, herkes için. Bir uç noktayı kaldırmak, bir alanı kaldırmak, bir alanı yeniden adlandırmak, bir türü değiştirmek, isteğe bağlı bir parametreyi zorunlu kılmak, URL'yi değiştirmek. Aracılar burada da bozulur, ancak daha sessizce.

Yazılmış istemciler için güvenli, aracılar için riskli:

Yeni bir zorunlu alan. Mevcut her arayan bozulur, ancak bir aracı, bir değer uydurarak düzeltmeye çalışabileceği bir doğrulama hatasıyla bozulur. Bu, tam bir hatadan daha kötüdür.
Yeni bir enum değeri. Sıradan istemciler ele almadıkları şeyleri görmezden gelir. Bir aracı, tanıdık olmayan değeri hakkında akıl yürütebilir ve ürününüzün hiç amaçlamadığı bir sonuca varabilir.
Sıkılaştırılmış bir doğrulama kuralı. Daha önce herhangi bir dizeyi kabul eden bir alan artık bir desen gerektiriyor. Aracının deseni öğrenmesinin tek yolu başarısız olmaktır, bu yüzden kural, aracılar için API hata tasarımı hakkındaki yazımızda belirtildiği gibi hata mesajında yer almalıdır.
Değişen bir varsayılan değer. Sayfalama varsayılanı 100'den 20'ye düşer ve hiçbir zaman bir `limit` göndermeyen aracı, verinin beşte birini görür ve bunu eksiksizmiş gibi raporlar.
Yeniden yazılan belgeler. Hiçbir davranış değişikliği olmasa da, araçlarınız spesifikasyondan oluşturulduysa, bir OpenAPI spesifikasyonunu aracı araçlarına dönüştürme kılavuzumuzda olduğu gibi, açıklama metni değişir ve araç seçimi de bununla birlikte kayabilir.

Aracılar için de güvenli. İsteğe bağlı bir alan eklemek, bir uç nokta eklemek, korunmuş varsayılan değeri olan isteğe bağlı bir parametre eklemek, doğrulamayı gevşetmek.

Bu orta liste izlenmesi gereken listedir, çünkü standart bir değişiklik incelemesinde hiçbir şey onu işaret etmez.

Sürümü her zaman sabitleyin

İlk savunma, örtük olarak hareket etmeyi reddetmektir.

Her istekte açık bir sürüm gönderin, API'nin sunduğu mekanizma ne olursa olsun: bir yol segmenti, bir başlık veya hesap düzeyinde bir sabitleme. GitHub'ın API sürümleme belgeleri bir tarih başlığı kullanır ve Stripe, açık bir yükseltme adımıyla her hesap için bir sürümü sabitler. Her ikisi de size aynı özelliği verir: siz karar verene kadar altınızda hiçbir şey değişmez.

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

User-Agent sürüm sabitlemesi kadar değerlidir. Bir API sağlayıcısı arayanları bir kullanımdan kaldırma hakkında uyarması gerektiğinde trafiğe bakar. Kendini tanımlayan bir aracı e-postayı alır; varsayılan bir kitaplık dizesi gönderen bir aracı almaz.

API'ye sahipseniz, bir sürüm yayınlayın ve sürdürün. En iyi API sürümleme stratejisi kılavuzumuz seçenekleri kapsar ve Apidog'da API sürümlemeyi yönetme, birkaçını aynı anda canlı tutmayı kapsar.

Hiç sürümleme olmayan üçüncü taraf API'ler için yapabildiğiniz kadar sabitleyin: karşılaştığınız yanıt şeklini kaydedin ve kontrol edin, ki bu sonraki bölümdür.

Bir çalıştırma yapmadan önce kaymayı tespit edin:

Sabitleme zaman kazandırır. Nihai yükseltmeyi durdurmaz ve sürümleme olmadan değişen API'ler için hiçbir şey yapmaz. Bu yüzden tespit edin.

Spesifikasyonu düzenli olarak karşılaştırın (diff). Sağlayıcı bir OpenAPI belgesi yayınlıyorsa, günlük olarak alın ve araçları oluşturduğunuz kopyayla karşılaştırın. Kaldırılan alanlar, değişen türler, eklenen gereksinimler, genişletilmiş enum'lar, düzenlenmiş açıklamalar. Apidog'da içe aktarılan tanımı projede tutabilir ve sürümler arasında nelerin değiştiğini görebilirsiniz, bu da "bir şey değişti mi" sorusunu bir araştırmadan ziyade bir rapora dönüştürür.

Çağırdığınız uç noktaları sözleşme testi yapın. Aracının sahip olduğu her araç için bilinen iyi bir istek gönderin ve yanıt şeklini doğrulayın: zorunlu alanların mevcut olması, türlerin doğru olması, enum değerlerinin beklediğiniz kümede olması. Bu, hiç spesifikasyon yayınlamayan API'lerdeki kaymayı yakalar, ki bunların çoğu böyledir. API sözleşme testi kılavuzumuz deseni kapsar ve çift yönlü sözleşme testi her iki taraftan çalıştırmayı kapsar.

Çalışma zamanında şekli doğrulayın. Araç sarmalayıcısında yanıtları beklediğiniz şemaya göre doğrulayın ve beklenmedik bir şey göründüğünde bir uyarı günlüğe kaydedin. Bu son savunma hattıdır ve kimsenin duyurmadığı değişikliği yakalayan budur.

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

Eksikse hata ver, fazlaysa uyar. Eksik zorunlu bir alan, aracının eksik verilerle çalışmak üzere olduğu anlamına gelir ki bu, durmaya değer bir hatadır. Yeni alanlar genellikle eklemelidir ve bir çalıştırmayı kesintiye uğratmadan bilinmeye değerdir. Her ikisini de aracı araç çağrılarını izleme hakkındaki yazımızda açıklanan iz kaydına yönlendirin.

Sadece şemaları değil, davranışı da izleyin. Bazı kaymalar bir şekil kontrolü için görünmezdir: değişen bir varsayılan değer, sıkılaşan bir hız sınırı, yavaşlayan bir yanıt. Tamamlanan görev başına çağrıları, uç nokta başına yeniden deneme oranını ve araç başına ortalama yanıt boyutunu izleyin. Bunlardan herhangi birinde ani bir değişiklik, genellikle yukarı akışta bir şeylerin değiştiği anlamına gelir.

Aracıyı bozmadan yükseltme

Yeni bir sürüme geçtiğinizde, bunu aracıda bir değişiklik olarak ele alın, çünkü öyledir.

Araçları elle düzenlemek yerine yeniden oluşturun, böylece açıklamalar ve şemalar birlikte hareket eder. Ardından oluşturulan araç tanımlarının farkını okuyun. Bu fark, gerçek etki alanıdır ve genellikle API değişiklik günlüğünün ima ettiğinden daha küçük veya daha büyüktür.

Aracıyı canlı bir şeye yönlendirmeden önce yeni sürümün bir maketine karşı çalıştırın. Bu en değerli adımdır ve genellikle atlanan adımdır: yeni spesifikasyondan oluşturulmuş bir maket, aracıları üretim yerine maketlere karşı çalıştırma hakkındaki yazımıza uygun olarak, tüm görev takımınızı yeni şekillere karşı risksiz bir şekilde çalıştırmanıza olanak tanır.

Seçim takımını yeniden çalıştırın. Açıklama değişiklikleri, modelin hangi aracı seçtiğini değiştirir ve bu regresyon bir şema farkına karşı görünmezdir. Deterministik olmayan aracıları test etme kılavuzumuzda olduğu gibi, sabit bir istemler kümesi için araç seçimi üzerinde doğrulama yapın.

Eski sürüm hala sabitlenmiş ve hazır durumdayken, bir bayrağın arkasında, trafiğin bir diliminde kullanıma sunun. Bir gün boyunca aynı dört sayıyı izleyin. Aracı regresyonları, herhangi biri şikayette bulunmadan çok önce görev başına daha fazla çağrı ve daha fazla yeniden deneme olarak ortaya çıkar.

Üretime ulaşan üç kayma:

Yeniden adlandırılan alan. Açılış hikayesi. Her çağrıda 200, her kayıtta boş adlar, iki hafta sonra bir rapor okuyan bir insan tarafından keşfedildi. Yanıtta bir çalışma zamanı şekil kontrolü, aracı beklenen alanı geri okuyamadığı için ilk çağrıda yakalardı.

Sıkılaştırılmış sayfalama varsayılanı. Bir sağlayıcı varsayılan sayfa boyutunu 100'den 20'ye düşürdü. Aracı hiçbir zaman bir `limit` göndermedi, bu yüzden 20 kayıt görmeye ve bunları eksiksiz küme olarak özetlemeye başladı. Hiçbir hata oluşmadı. Özetler, kendinden emin bir şekilde okunan bir şekilde yanlıştı. Düzeltme tek bir satırdı, açık bir `limit` göndermekti ve ders daha geniş: varsayılanlara güvenirseniz, başkasının kararına açıklanmamış bir bağımlılığınız olur.

Yeni enum değeri. Bir ödeme API'si status: "disputed" ekledi. Yazılmış istemciler bunu görmezden geldi. Aracı bu konuda akıl yürüttü, tartışmalı bir ücretin iade sayıldığına karar verdi ve uzlaştırılmış defterleri rapor etti ki bunlar öyle değildi. Açık enum doğrulama, modelin yorumlamasına izin vermek yerine tanıdık olmayan değer üzerinde bir hata fırlatırdı.

Desen: her değişiklik duyuruldu, her biri sağlayıcının kendi sınıflandırmasına göre eklemeli veya küçüktü ve her biri bir aracı için bozucuydu. Bu boşluk, etrafında tasarım yapılması gereken şeydir.

Kullanımdan kaldırmaları bir iş öğesi olarak ele alın:

Sağlayıcılar genellikle sizi uyarır. Uyarı bir değişiklik günlüğünde, bir e-postada veya yanıtta bir Deprecation başlığında gelir ve bunların hiçbiri aracıyı sürdüren kişiye ulaşamayabilir.

Onları normal kuyruğunuza bağlayın. Deprecation başlığı ve Sunset başlığı her ikisi de standartlaştırılmıştır, bu nedenle genel bir kontrol sağlayıcılar arasında çalışır. Göründüklerinde onları günlüğe kaydedin ve binde bir yerine ilk görüşte uyarı verin. Bugün çağrıların yüzde 3'ünde görünen bir başlık, kullanım sonu tarihinde tam bir kesinti anlamına gelir.

Bir envanter de tutun: hangi aracı, hangi sağlayıcı, hangi sürüm, hangi uç noktalar ve kimin sahibi. Bir dosyada on satır yeterlidir. Bir kullanımdan kaldırma bildirimi geldiğinde, "bu bizi etkiliyor mu" sorusu bir öğleden sonralık `grep` araması değil, bir dakika sürmelidir.

Kayma bir iştir, bu yüzden ona bir sahip atayın:

Tespit bir kuyruk üretir: bir spesifikasyon farkı, başarısız bir sözleşme testi, ilk kez görülen bir kullanımdan kaldırma başlığı. Her biri bir son tarihi olan küçük bir iştir ve hata modu, kullanım sonu tarihi gelene kadar kimsenin sahip olmadığı bir kanalda beklemesidir.

Onları ekibinizin zaten işleri takip ettiği yere koyun. Aracılar kodlama çalışma zamanları olarak çalışıyorsa, dağıttığınız bir hizmet olarak değil, onları yöneten platform döngüyü kapatabilir: Sharkly bir Ajan veya Bir Ekibe bir Görev atar ve amacı, yürütme izini ve incelemeyi tek bir yerde tutar, böylece "ödeme API'si bu uç noktayı kullanımdan kaldırdı" bir iş parçacığındaki bir mesaj yerine bir sonuçla atanmış bir görev haline gelir. Ne kullanırsanız kullanın, kural aynıdır. Sahipsiz bir kayma uyarısı, bozulduğu gün tekrar karşılaşacağınız bir kullanımdan kaldırmadır.

Bir kontrol listesi:

Her istek açık bir API sürümü ve tanımlayıcı bir User-Agent gönderir.
Üçüncü taraf spesifikasyon belgeleri düzenli olarak alınır ve karşılaştırılır (diff).
Aracının çağırabileceği her araç, yanıt şeklini doğrulayan bir sözleşme testine sahiptir.
Araç sarmalayıcıları çalışma zamanında yanıtları doğrular: eksikse hata ver, yeniyse uyar.
Uç nokta başına davranışsal metrikler izlenir, böylece sessiz kaymalar ortaya çıkar.
Sürüm yükseltmeleri, araçları elle düzenlemek yerine yeniden oluşturur.
Görev takımı ve seçim takımı önce yeni sürümün bir maketine karşı çalıştırılır.
Kullanıma sunum işaretlenir ve geri alınabilir, önceki sürüm hala sabitlenmiş durumdadır.

API ekibi değişiklikleri göndermeye devam edecek ve bu sorun değil. İhtiyacınız olan şey, aracınızın fark eden bir istemci olmasıdır, bu da bir sürüm sabitlemesi, bir sözleşme testi ve bir çalışma zamanı şekil kontrolü gerektirir. Canlı bir çalıştırmaya ulaşmadan önce spesifikasyonu karşılaştırmak ve bir sonraki sürümü maketlemek için Apidog'u indirin.

Sıkça sorulan sorular:

Üçüncü taraf bir spesifikasyonu değişiklikler için ne sıklıkla kontrol etmeliyim? Çoğu için günlük yeterlidir ve otomatikleştirmesi ucuzdur. Yayınlanmış spesifikasyonu olmayan API'ler için bunun yerine CI'da çalışan sözleşme testlerine güvenin, çünkü aynı kaymayı dışarıdan tespit ederler.

Her zaman en eski çalışan sürüme mi sabitlemeliyim? Hayır. Yükseltmelerin kasıtlı olması için sabitleyin, sonra düzenli bir şekilde yükseltin. Eski bir sürümde kaldırılana kadar beklemek, planlanmış bir değişikliği acil duruma dönüştürür.

Değişiklikten sonra aracı düzgün çalışırsa ne olur? Varsaymak yerine doğrulayın. Tehlikeli sonuçlar, yeniden adlandırılmış bir alanın sessizce bırakılması gibi hala 200 döndürenlerdir. Bir şekil doğrulama, yeşil bir çalıştırmanın yapamayacağı şeyi size söyler.

Kendi API'mi aracılar için farklı bir şekilde sürümlemem gerekiyor mu? Farklı değil, daha katı bir şekilde. Yeni zorunlu alanları, yeni enum değerlerini ve değişen varsayılanları, yazılmış istemciler için eklemeli olsalar bile aracı tüketiciler için bozucu olarak ele alın ve bunları aynı şekilde duyurun.

Hangi aracıların hangi uç noktaları çağırdığını nasıl bilebilirim? İzlemelerinizden. Çalıştırma başına araç adı artı uç nokta size bağımlılık haritasını verir ve bir kullanımdan kaldırmadan tam olarak kimin etkilendiğini söyler. Aracı araç çağrılarını izleme hakkındaki yazımız kayıt şeklini kapsar.

Aracı değişen bir API'ye kendi başına uyum sağlayabilir mi? Bazen, ancak buna güvenmemelisiniz. Eksik bir alan etrafında doğaçlama yapan bir model, hiçbir şeyin yanlış gittiğine dair bir sinyal vermeden makul bir çıktı üretir. Bunun yerine yüksek sesle hata verin ve araçları düzeltin.