AI Ajanları Arasında API Kontratı Kayması Nasıl Yönetilir?

Birden fazla AI ajanı aynı projede çalışırken ortaya çıkan en sinsi sorun şu: arka uçtaki bir ajan bir endpoint'in yanıt yapısını değiştiriyor, ön uçtaki ajan ise hiçbir şeyden habersiz eski kontrata karşı kod yazıyor. Derleme başarılı geçiyor, tipler kontrol ediliyor, ama gerçek çalışma zamanında her şey çöküyor. Sorun şu ki her ajan ayrı bir chat oturumunda yaşıyor; biri diğerinin ne değiştirdiğini bilmiyor.

Bu sorunu çözmek için üç pratik yaklaşım vardır. İlki ve en etkili olanı, API kontratını merkezi bir yerde tutmak. OpenAPI/Swagger şeması veya JSON Schema dosyasını projenin kökünde sakla ve her ajan başlamadan önce bu dosyayı oku. Ajanı şu şekilde yönlendir: "Başlamadan önce `api-contract.json` dosyasını incele ve bu kontrata kesinlikle uy. Hiçbir değişiklik yapmadan önce bu dosyayı güncelle." Böylece kontrat tek kaynak haline gelir.

İkinci yöntem, ajanların her değişikliği bir kontrol listesine kaydetmesi. Ajanı şu şekilde talimat ver: "Bir endpoint değiştirirsen, `CHANGES.md` dosyasına tarih, endpoint adı, eski ve yeni yapıyı ekle." Bu basit ama etkili bir yöntem; insan gözü hızlıca farkı görebilir.

Üçüncü seçenek, build sürecine kontrat doğrulama eklemek. Örneğin, frontend ve backend kodlarını derlemeden önce, API şemasını kontrol eden bir script çalıştır. TypeScript ile çalışıyorsan, generated types'lar her zaman kontratla senkron kalır.

Gerçekçi olursak, çoğu ekip bu üç yöntemi birleştiriyor. Merkezi şema + otomatik doğrulama + insan kontrol. Sessiz başarısızlıklar bulunması zor olduğundan, kontratı projenin yapısının merkezine koy ve ajanları buna bağlı tut. Aksi takdirde her değişiklik potansiyel bir zaman bombası.