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

API ekibi customer_name alanını customer_full_name olarak yeniden adlandırdı. Belgeler ve insan tarafından sürdürülen istemciler güncellendi; aracınız ise eski alanı göndermeye devam etti. API bilinmeyen alanı sessizce yok saydı, 200 döndürdü ve iki hafta boyunca oluşturulan kayıtların adı boş kaldı.

Apidog'u bugün deneyin

Aracılar, API değişikliklerini fark etme olasılığı en düşük tüketicilerdir. Klasik bir istemci hata fırlatabilir; bir aracı ise 200 gördüğünde çağrının başarılı olduğunu varsayar, eksik veriyi doğaçlama ile tamamlayabilir ve hatalı sonucu güvenle sunabilir.

Bu rehber; API kaymasının neden aracıları özellikle etkilediğini, hangi “zararsız” değişikliklerin riskli olduğunu, sürüm sabitlemeyi, CI’da kayma tespitini ve güvenli yükseltmeyi anlatır. Üretimde yapay zeka aracılarının neden bozulduğuna dair yazı hata modlarını; bu yazı ise kod tabanınız dışındaki sözleşme değişikliklerini ele alır.

Apidog burada önemlidir: Eski ve güncel API tanımları varsa, farkı mekanik olarak tespit edebilirsiniz.

Aracılar neden değişiklikleri daha az fark eder?

Dört özellik birlikte sorun yaratır:

• Sessiz hoşgörü: Çoğu API bilinmeyen istek alanlarını yok sayar. Yeniden adlandırılmış bir alan eski adıyla gönderildiğinde, yeni alan eksik kalır ama istek yine 200 dönebilir.
• Doğaçlama: Yanıttan bir değer eksikse model durmak yerine makul görünen bir alternatif üretebilir. Sohbette yararlı olan bu davranış, API işlemlerinde tehlikelidir.
• Metinsel araç açıklamaları: Araç açıklamaları API hakkındaki varsayımları düz yazıda saklar. API değiştiğinde açıklama yanlışlaşır ve model yanlış çağrılar üretebilir. Araç şeması tasarımı bu metnin davranışı nasıl etkilediğini açıklar.
• Derleyici yok: Yazılmış istemciler, kaldırılan alanlarda derleme zamanında bozulur. Aracı sözleşmeleri ise JSON şemaları ve açıklamalarda yaşar; çoğu zaman çağrı başarısız olana kadar denetlenmez.

Sonuç: Klasik istemciler için güvenli kabul edilen değişiklikleri, aracı tüketiciler için ayrıca sınıflandırmalısınız.

Aracıları gerçekten hangi değişiklikler bozar?

Klasik “eklemeli / bozucu” ayrımı geçerlidir, ancak aracılar için bir ara kategori vardır.

Herkes için bozucu değişiklikler

• Uç nokta kaldırmak
• Alan kaldırmak veya yeniden adlandırmak
• Alan türünü değiştirmek
• İsteğe bağlı parametreyi zorunlu yapmak
• URL değiştirmek

Aracılar bunlarda da bozulur; fark, hatanın daha sık sessiz kalmasıdır.

Yazılmış istemciler için güvenli, aracılar için riskli değişiklikler

• Yeni zorunlu alan: Aracı doğrulama hatasını eksik bırakmak yerine değer uydurarak çözmeye çalışabilir.
• Yeni enum değeri: Model bilinmeyen değeri yorumlayıp ürünün amaçlamadığı bir sonuca ulaşabilir.
• Sıkılaştırılmış doğrulama: Önceden her metni kabul eden alan artık bir desen gerektiriyorsa, aracı bunu ancak hata alınca öğrenir. Bu nedenle kural hata mesajında yer almalıdır. Bkz. aracılar için API hata tasarımı.
• Değişen varsayılan: Sayfalama varsayılanı 100den 20ye düşerse, limit göndermeyen aracı verinin yalnızca beşte birini tam veri gibi raporlayabilir.
• Belge değişikliği: Davranış aynı kalsa bile araçlar OpenAPI tanımından üretiliyorsa açıklama değişiklikleri araç seçimini etkileyebilir. Bkz. OpenAPI spesifikasyonunu aracı araçlarına dönüştürme.

Aracılar için genellikle güvenli değişiklikler

• İsteğe bağlı alan eklemek
• Yeni uç nokta eklemek
• Varsayılanı değişmeyen isteğe bağlı parametre eklemek
• Doğrulamayı gevşetmek

İzlenmesi gereken liste, bu orta kategoridir.

Her istekte sürümü sabitleyin

İlk savunma hattı, API’nin örtük olarak değişmesini engellemektir.

API’nin sunduğu yönteme göre her istekte açık bir sürüm gönderin: URL yolu, başlık veya hesap düzeyinde sürüm sabitlemesi. GitHub API sürümleme belgeleri tarih tabanlı bir başlık kullanır; Stripe ise hesap başına sürüm sabitler. Amaç aynıdır: Siz yükseltmeye karar vermeden davranış değişmemeli.

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

Tanımlayıcı bir User-Agent da gereklidir. Sağlayıcı kullanımdan kaldırma uyarısı göndereceğinde trafiği tanımlayabilmelidir. Kimliği belli olan aracılar uyarı alır; varsayılan kütüphane dizesi kullananlar almayabilir.

Kendi API’nize sahipseniz sürüm yayınlayın ve sürdürün. En iyi API sürümleme stratejisi seçenekleri, Apidog’da API sürümlemeyi yönetme ise birden fazla sürümü aynı anda yönetmeyi açıklar.

Sürümleme sunmayan üçüncü taraf API’lerde, karşılaştığınız yanıt biçimini kaydedin ve doğrulayın.

Çalıştırmadan önce API kaymasını tespit edin

Sürüm sabitleme zaman kazandırır; yükseltmeleri veya sürümlemesiz API değişikliklerini ortadan kaldırmaz.

1. OpenAPI tanımını düzenli olarak karşılaştırın

Sağlayıcı OpenAPI belgesi yayınlıyorsa bunu günlük alın ve araçları ürettiğiniz sürümle karşılaştırın:

• Kaldırılan alanlar
• Değişen türler
• Yeni zorunluluklar
• Genişletilmiş enum değerleri
• Düzenlenmiş açıklamalar

Apidog’da içe aktarılan tanımı projede tutup sürümler arasındaki farkları inceleyebilirsiniz. Böylece “bir şey değişti mi?” sorusu araştırma yerine rapora dönüşür.

2. Çağrılan her uç noktaya sözleşme testi ekleyin

Aracının kullandığı her araç için bilinen iyi bir istek gönderin ve şunları doğrulayın:

• Zorunlu alanlar mevcut mu?
• Alan türleri doğru mu?
• Enum değerleri beklenen kümede mi?

Bu yaklaşım, spesifikasyon yayınlamayan API’lerdeki kaymayı da tespit eder. Bkz. API sözleşme testi ve çift yönlü sözleşme testi.

3. Çalışma zamanında yanıt biçimini doğrulayın

Araç sarmalayıcısında yanıtı beklenen şemaya göre kontrol edin:

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

Zorunlu alan eksikse hata verin; yeni alan varsa uyarın. Eksik veriyle devam eden bir aracı durdurulmalıdır. Yeni alanlar çoğunlukla eklemelidir; çalıştırmayı durdurmadan görünür olmalıdır. Bu olayları aracı araç çağrılarını izleme kayıtlarına gönderin.

4. Davranışsal metrikleri de izleyin

Şema doğrulama her kaymayı yakalayamaz. Örneğin:

• Değişen varsayılan değer
• Sıkılaştırılmış hız sınırı
• Yavaşlayan yanıt süresi

Şunları uç nokta ve araç bazında izleyin:

• Tamamlanan görev başına çağrı sayısı
• Yeniden deneme oranı
• Ortalama yanıt boyutu

Ani değişimler genellikle yukarı akışta bir değişikliğe işaret eder.

Aracıyı bozmadan sürüm yükseltme

Yeni API sürümüne geçmek, aracı için de bir değişikliktir.

1. Araçları elle düzenlemek yerine yeniden üretin. Şema ve açıklamalar birlikte güncellensin.
2. Üretilen araç tanımlarının farkını inceleyin. Gerçek etki alanı budur.
3. Canlı sisteme bağlamadan önce yeni sürümden üretilen bir makete karşı çalıştırın. Aracıları üretim yerine maketlere karşı çalıştırma yaklaşımı görev takımını risksiz test etmenizi sağlar.
4. Araç seçimi testlerini yeniden çalıştırın. Açıklama değişiklikleri modelin seçtiği aracı değiştirebilir. Bkz. deterministik olmayan aracıları test etme.
5. Eski sürüm hâlâ sabitlenmişken, yeni sürümü bir bayrak arkasında küçük trafik diliminde yayınlayın.
6. Görev başına çağrı, yeniden deneme oranı, yanıt boyutu ve başarı oranını en az bir gün izleyin.

Aracı regresyonları, çoğu zaman kullanıcı şikâyetinden önce daha fazla çağrı ve yeniden deneme olarak görünür.

Üretime ulaşan üç kayma örneği

1. Yeniden adlandırılan alan

customer_name alanı kaldırılıp customer_full_name geldi. Her çağrı 200 döndü, fakat her kaydın adı boş kaldı. Yanıttaki çalışma zamanı biçim kontrolü, beklenen alan bulunamadığı için ilk çağrıda sorunu yakalardı.

2. Sıkılaştırılmış sayfalama varsayılanı

Sağlayıcı varsayılan sayfa boyutunu 100den 20ye düşürdü. Aracı limit göndermediği için yalnızca 20 kaydı eksiksiz küme olarak özetledi. Hata oluşmadı; sonuçlar yalnızca güvenle ifade edilen yanlış bilgilerdi.

Düzeltme tek satırdı: açık bir limit gönderin. Ders daha geniştir: Varsayılanlara güveniyorsanız, başka bir tarafın kararına açıklanmamış bağımlılığınız vardır.

3. Yeni enum değeri

Bir ödeme API’si status: "disputed" ekledi. Yazılmış istemciler bu değeri yok saydı; aracı ise tartışmalı bir ödemeyi iade olarak yorumladı ve yanlış mutabakat raporları üretti.

Açık enum doğrulama, modelin yorumlamasına izin vermek yerine tanınmayan değerlerde hata üretirdi.

Ortak desen şudur: Her değişiklik duyurulmuştu, sağlayıcı tarafından küçük veya eklemeli sayılmıştı ve aracı için bozucuydu.

Kullanımdan kaldırmaları iş öğesine dönüştürün

Sağlayıcılar genellikle sizi bir değişiklik günlüğü, e-posta veya HTTP başlığıyla uyarır. Ancak bu uyarı aracı sahibi kişiye ulaşmayabilir.

Deprecation ve Sunset başlıklarını genel olarak kontrol edin. İlk görüldükleri anda günlüğe yazın ve uyarı oluşturun. Çağrıların yalnızca yüzde 3’ünde görünen bir Sunset başlığı bile, tarihte tam kesinti anlamına gelebilir.

Ayrıca küçük bir envanter tutun:

Aracı	Sağlayıcı	Sabitlenen sürüm	Kullanılan uç noktalar	Sahip
billing-agent	Ödeme API’si	2026-06-01	/charges, /refunds	Ekip adı

Böylece bir kullanımdan kaldırma bildirimi geldiğinde “bizi etkiliyor mu?” sorusu saatlerce grep yapmak yerine dakikalar içinde yanıtlanır.

Kaymaya bir sahip atayın

Tespit mekanizmaları iş üretir:

• Spesifikasyon farkı
• Başarısız sözleşme testi
• İlk kez görülen kullanımdan kaldırma başlığı

Her biri son tarihli küçük bir iş olmalıdır. Sahipsiz uyarılar, kullanım sonu tarihinde üretim sorununa dönüşür.

Ekibinizin zaten kullandığı iş takip sistemine bağlayın. Aracı çalışma zamanlarını yöneten platform, görevi, yürütme izini ve incelemeyi aynı yerde tutmalıdır. Örneğin Sharkly, bir ajana veya ekibe görev atayarak “ödeme API’si bu uç noktayı kaldırıyor” uyarısını izlenebilir bir göreve dönüştürür.

Kural basit: Sahipsiz bir kayma uyarısı, bozulduğu gün tekrar karşılaşacağınız bir kullanımdan kaldırmadır.

Kontrol listesi

• Her istek açık API sürümü ve tanımlayıcı User-Agent gönderiyor.
• Üçüncü taraf spesifikasyonları düzenli olarak alınıp karşılaştırılıyor.
• Aracının kullanabildiği her araç için yanıt biçimini doğrulayan sözleşme testi var.
• Araç sarmalayıcıları çalışma zamanında yanıtları doğruluyor: eksik alanlarda hata, yeni alanlarda uyarı.
• Uç nokta bazlı davranışsal metrikler izleniyor.
• Sürüm yükseltmeleri araçları elle değiştirmek yerine yeniden üretiyor.
• Görev ve seçim testleri önce yeni sürümün maketine karşı çalışıyor.
• Yayınlama bayrakla kontrol ediliyor, geri alınabiliyor ve önceki sürüm sabit kalıyor.

API ekipleri değişiklik göndermeye devam edecek; sorun bu değil. İhtiyacınız olan şey, aracınızın değişikliği fark eden bir istemci olmasıdır: sürüm sabitleme, sözleşme testi ve çalışma zamanı biçim doğrulaması.

Spesifikasyon farklarını incelemek ve sonraki sürümü maketlemek için Apidog’u indirin.

Sıkça sorulan sorular

Üçüncü taraf spesifikasyonunu ne sıklıkla kontrol etmeliyim?

Çoğu API için günlük kontrol yeterlidir ve otomatikleştirmesi ucuzdur. Yayınlanmış spesifikasyonu olmayan API’lerde CI’da çalışan sözleşme testlerine güvenin.

Her zaman en eski çalışan sürüme mi sabitlemeliyim?

Hayır. Yükseltmeleri bilinçli yapmak için sabitleyin, ardından düzenli olarak yükseltin. Eski sürüm kaldırılana kadar beklemek planlı değişikliği acil duruma çevirir.

Değişiklikten sonra aracı düzgün çalışıyorsa ne yapmalıyım?

Varsaymayın, doğrulayın. En tehlikeli sonuçlar hâlâ 200 dönenlerdir; örneğin yeniden adlandırılmış alanın sessizce yok sayılması. Biçim doğrulama, yeşil bir çalıştırmanın gösteremediğini gösterir.

Kendi API’mi aracılar için farklı mı sürümlemeliyim?

Farklı değil, daha katı sürümlemelisiniz. Yeni zorunlu alanları, yeni enum değerlerini ve değişen varsayılanları, yazılmış istemciler için eklemeli görünseler bile aracı tüketiciler için bozucu kabul edin ve açıkça duyurun.

Hangi aracıların hangi uç noktaları çağırdığını nasıl bulurum?

İzlerden. Çalıştırma başına araç adı ve uç nokta, bağımlılık haritasını oluşturur ve kullanımdan kaldırmanın kimleri etkileyeceğini gösterir.

Aracı değişen API’ye kendi başına uyum sağlayabilir mi?

Bazen, ancak buna güvenmeyin. Eksik alan etrafında doğaçlama yapan model, hiçbir hata sinyali olmadan makul görünen yanlış bir çıktı üretebilir. Bunun yerine yüksek sesle hata verin ve araç sözleşmesini düzeltin.