Yapay Zeka Ajanlarının Çalışan API'leri Çökertmesini Nasıl Önlersiniz

Bir yapay zeka aracısına API projenizde yazma erişimi vermek, gerçek hasara yol açabilir. Kötü niyetli olduğu için değil; aracılar komutun ima ettiklerini uygular. Örneğin, “kullanıcı uç noktalarını temizle” komutu hâlâ bağımlı olduğunuz aktif bir rotayı silebilir. “Şemayı güncelle” komutu ise başka uç noktaların referans verdiği veri modelinin üzerine yazabilir. Aracının üretimde nelerin kullanıldığını bilmesini bekleyemezsiniz; yalnızca erişebildiği kaynakları görür ve değiştirir.

Apidog'u bugün deneyin

Bu, yeni bir risk sınıfıdır. İnsan geliştirici bir uç noktayı silmeden önce bağımlılıkları kontrol eder. Terminalde döngü içinde çalışan bir aracı ise komutu çalıştırır, başarılı yanıtı alır ve sonraki adıma geçer. Bu değişiklikler main dalına ulaşırsa, tasarım kaynağınızdaki değişiklikler yayına alınmış olabilir.

Çözüm, aracıları tamamen kilitlemek değildir. Çözüm, onlara dışına çıkamayacakları izole bir çalışma alanı vermektir. Apidog’un Yapay Zeka Dalı (AI Branch) özelliği bunu sağlar:

• Aracının yaptığı düzenlemeler izole bir dala yazılır.
• Kaynak dal ve main dokunulmadan kalır.
• Bir insan farkı inceleyip birleştirmeden hiçbir değişiklik ana dala ulaşmaz.

Özelliğin tasarım mantığı için Yapay Zeka Dalı ve daha güvenli aracı odaklı değişiklikler yazısını okuyabilirsiniz. Bu yazı ise CLI ile uygulanabilir iş akışına odaklanır.

Aracı yazma erişimi neden varsayılan olarak tehlikelidir

Çoğu araç aracıya proje düzeyinde tek katmanlı erişim verir. Aracı bir uç nokta oluşturabiliyorsa silebilir; bir şemayı güncelleyebiliyorsa uyumsuz bir sürümle değiştirebilir. “Aracı bir değişiklik önerdi” ile “değişiklik doğruluk kaynağına yazıldı” arasında kontrol noktası yoktur.

Pratikte üç hata modu öne çıkar:

• Üzerine yazma: Aracı API’nin yalnızca bir kısmını anlayarak şemayı yeniden oluşturur ve başka uç noktaların ihtiyaç duyduğu alanları kaldırır.
• Silme: Aracı uç noktaları “birleştirirken”, canlı istemcilerin hâlâ çağırdığı rotaları silebilir.
• Sessiz sapma: Aracı bir oturum boyunca çok sayıda küçük değişiklik yapar. Her değişiklik tek başına makul görünebilir; ancak toplam sonuç yayınlanan API’den sapar.

Bunlar sıra dışı hatalar değildir. Yanlış dalda çalışan bir aracının normal çıktıları olabilir. Hedef, aracının yanlış dala yazmasını imkânsız hâle getirmektir.

Temel çözüm: izole bir Yapay Zeka Dalı

Yapay Zeka Dalı, harici yapay zeka araçları ve CLI işlemleri için tasarlanmış özel bir sprint dalı türüdür. Aracı düzenlemelerini bu dalda yapar; kaynak dalınız ve main, siz birleştirme kararı verene kadar etkilenmez.

1. Apidog CLI'ı kurun ve giriş yapın

Önce Apidog CLI'ı kurun ve erişim belirteciyle oturum açın:

npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>

2. Yapay Zeka Dalını oluşturun

Dal adında tarih, kaynak dal ve görev amacını kullanın. Bu, inceleme ve temizlik süreçlerini kolaylaştırır.

apidog branch create --type ai \
  --name "ai/20260708-from-main-user-register" \
  --from main \
  --project <PROJECT_ID>

Bu komutta iki kritik nokta vardır:

1. Dal main üzerinden oluşturulur, ancak main değişmez.
2. Dal boş başlar. Projenin tamamı otomatik olarak kopyalanmaz.

Bu boş başlangıç kasıtlı bir güvenlik sınırıdır. Aracı yalnızca açıkça içe aktardığınız kaynakları düzenleyebilir. Böylece etki alanı tüm proje yerine seçtiğiniz uç noktalar, şemalar ve belgelerle sınırlı kalır.

Kullanılabilir bayrakları görmek için yardım komutunu çalıştırın:

apidog branch create -h

Kaynakları düzenlemeden önce içe aktarın

Yapay Zeka Dalı boş olduğu için, aracının çalışacağı kaynakları sizin seçmeniz gerekir. Aracının değiştirmesini istediğiniz uç noktaları, şemaları veya belgeleri dal içine alın; diğer kaynakları dışarıda bırakın.

Örneğin main dalındaki iki uç noktayı ve bir veri şemasını AI dalına kopyalamak için:

apidog branch pick-to \
  --type ai \
  --from main \
  --to "ai/20260708-from-main-user-register" \
  --endpoint-ids 1,2 \
  --data-schema-ids 3 \
  --project <PROJECT_ID>

Bu işlemden sonra AI dalı şunları içerir:

• main dalındaki 1 ve 2 numaralı uç noktaların kopyaları
• 3 numaralı veri şemasının kopyası

Aracı yalnızca bu kopyalar üzerinde çalışır. Bir uç noktayı silse bile canlı rotayı değil, AI dalındaki taslak kopyayı siler.

Kodlama aracısı kullanıyorsanız, bu komutları aracı döngüsüne ekleyebilirsiniz. Apidog CLI, agentHints.nextSteps ile yapılandırılmış JSON döndürür. Böylece aracı komut sonucunu okuyup bir sonraki adımı belirleyebilir. Cursor’da apidog-cli rehberi, bu yaklaşımın düzenleyici entegrasyonunu gösterir.

Aracının düzenlemesine izin verin, ardından farkı inceleyin

Kaynakları içe aktardıktan sonra aracı aşağıdaki işlemleri AI dalı içinde yapabilir:

• Uç nokta oluşturma, güncelleme veya silme
• Veri şeması güncelleme
• API belgesi oluşturma veya düzenleme
• Test senaryoları ekleme ya da değiştirme

Bu yazma işlemlerinin tamamı AI dalıyla sınırlıdır.

İş tamamlandığında, birleştirme yapmadan önce farkı inceleyin. AI Branch akışında birleştirme otomatik olmamalıdır. CLI veya Apidog istemcisi üzerinden şu kontrolleri yapın:

• Silinen uç noktalar gerçekten kaldırılmalı mı?
• Şema alanları geriye dönük uyumlu mu?
• İstemcilerin kullandığı rota, parametre veya yanıt alanları değişti mi?
• Aracı görev kapsamı dışındaki bir kaynağa dokundu mu?

Aracı hatalı bir değişiklik yaptıysa üretimi geri almak yerine AI dalını terk edebilirsiniz. İzolasyonun asıl değeri budur.

Değişiklikleri bir birleştirme isteğiyle uygulayın

Birleştirme yöntemi, hedef dalın korunup korunmadığına bağlıdır.

Korunmayan dala doğrudan birleştirme

Hedef dal korunmuyorsa, taşınacak kaynakları açıkça listeleyerek doğrudan birleştirme yapabilirsiniz:

apidog branch merge \
  --type ai \
  --from "ai/20260708-from-main-user-register" \
  --to main \
  --endpoint-ids 1,2 \
  --data-schema-ids 3 \
  --project <PROJECT_ID>

Yine de üretim için kullanılan main dalında bu yaklaşımı tercih etmeyin.

Korunan main dalı için merge request oluşturma

main korunduğunda doğrudan birleştirme engellenir. Bunun yerine incelemeye açık bir birleştirme isteği oluşturun:

apidog merge-request create \
  --from "ai/20260708-from-main-user-register" \
  --to main \
  --endpoint-ids 1,2 \
  --data-schema-ids 3 \
  --reviewer-ids <REVIEWER_USER_IDS> \
  --description "AI branch: user register changes" \
  --project <PROJECT_ID>

Bu yaklaşımda:

1. Aracı değişiklikleri AI dalında üretir.
2. Siz yalnızca taşımak istediğiniz kaynak kimliklerini seçersiniz.
3. Bir inceleyici farkı kontrol eder.
4. Onaylanan değişiklikler main dalına uygulanır.

Aracının gönderilmesini istemediğiniz bir kaynağa dokunması durumunda, ilgili kimliği birleştirme isteğine eklemeyin. Bu kaynak AI dalında kalır.

Bu iş akışı, Git-yerel API iş akışındaki temel disiplini uygular: dal oluştur, değişiklik öner, incele, birleştir. AI Branch, aynı disiplini insan olmayan katkıcılara da uygular.

Birleştirilmiş ve terk edilmiş dalları temizleyin

Birleştirilen veya artık ihtiyaç duyulmayan AI dallarını arşivleyin:

apidog branch archive "ai/20260708-from-main-user-register" \
  --type ai \
  --project <PROJECT_ID>

Önerilen kullanım modeli: görev başına bir AI dalı.

Her dal tek bir aracı iş birimini temsil etmelidir:

1. Dalı oluşturun.
2. Gerekli kaynakları içe aktarın.
3. Aracının değişiklik yapmasına izin verin.
4. İnceleyin ve birleştirin veya reddedin.
5. Dalı arşivleyin.

Bu yaklaşım, birbiriyle ilgisiz birçok aracı oturumunun aynı dalda birikmesini engeller.

Dalın etrafındaki güvenli aracı hijyeni

AI Branch izolasyonu sağlar; ancak güvenli bir aracı iş akışı için aşağıdaki kontrolleri de uygulamalısınız.

• En az ayrıcalıklı erişim belirteçleri kullanın.
  
  apidog login --with-token komutunda kullandığınız belirteç, aracının erişebileceği projeleri sınırlar. Otomasyon belirtecine yalnızca gerekli projeler için izin verin. Kişisel sahip belirtecini aracıya vermeyin.

• main dalını koruyun.
  
  Dal koruması, “birleştirmeden önce inceleme”yi öneri olmaktan çıkarıp zorunlu kılar. Korunan main, aracı değişikliklerinin merge-request create üzerinden ilerlemesini sağlar.

• Her birleştirmeden önce farkı inceleyin.
  
  İzolasyon tek başına yeterli değildir. İnsan incelemesi, aracının yanlış yorumladığı komutları veya beklenmeyen yan etkileri yakalayan kontrol noktasıdır.

• Devredin, ardından doğrulayın.
  
  Aracı uygulama işini yapabilir; kabul kararı sizde kalmalıdır. Aynı yaklaşım test çalıştırmalarında da geçerlidir: aracı testi çalıştırır, siz test donanımı sonuçlarını ve çıkış kodunu doğrularsınız.

API spesifikasyonunuzu Git’te de sürümlüyorsanız, OpenAPI versiyon kontrolü ek bir geçmiş ve karşılaştırma katmanı sağlar.

Uçtan uca akış

Aşağıdaki sıralamayı doğrudan aracı iş akışınıza veya CI otomasyonunuza uyarlayabilirsiniz:

1. main dalından apidog branch create --type ai ile AI dalı oluşturun.
2. Aracının ihtiyaç duyduğu uç noktaları ve şemaları apidog branch pick-to ile içe aktarın.
3. Aracının yalnızca AI dalında düzenleme yapmasına izin verin.
4. CLI veya istemci üzerinden farkı inceleyin.
5. Korunan main dalı için apidog merge-request create ile inceleme isteği açın.
6. Değişiklik birleştirildiğinde veya reddedildiğinde apidog branch archive ile dalı arşivleyin.

Bu akışta aracı, main üzerindeki canlı bir uç noktanın üzerine doğrudan yazamaz veya onu silemez. Yapabileceği en kötü şey, daha sonra reddedeceğiniz izole bir taslakta hatalı değişiklik yapmaktır.

Aracılara anahtarları vermeden çalışma alanı sağlayın

Aracılar, açıkça tarif etmediğiniz ayrıntıları da uygulayabildikleri için verimlidir. Aynı özellik, sınırsız yazma erişimini riskli kılar.

İzole AI dalı, korunan main, en az ayrıcalıklı belirteçler ve zorunlu inceleme birlikte kullanıldığında, “aracı API’mizi yok etti” riski incelenip reddedilebilen bir farka dönüşür.

Apidog, bu akışı yerleşik olarak sunar. Apidog CLI’ı kurun, bir AI dalı oluşturun ve aracılarınızın gerçek kaynak yerine izole bir kopyada çalışmasını sağlayın. Üretim iş akışına bağlamadan önce Apidog’u indirin ve tam komut referansı için Yapay Zeka Dalı belgelerini inceleyin.