Altın Kural: CLI Veri Üretir, Model Verilere Göre Hareket Eder

Bu, Apidog'un API testi ve API yaşam döngüsü yönetimi için bir komut satırı aracı olan Apidog CLI'ı nasıl geliştirdiğini anlatan 10 bölümlük bir seridir. Sırasıyla okuyabilir veya ilginizi çeken herhangi bir gönderiye atlayabilirsiniz:

Modelin tüm kuralları ezberlemesini sağlamayın; kuralların doğru yerlerde yürütülmesine izin verin. cli-schema validate, Şemayı bilgiden bir kalite kapısına dönüştürür.

Temel İlke: Kuralların Doğru Yerlerde Yürütülmesine İzin Verin.

Tecrübemizden bir temel ilke damıttık:

Modelin tüm kuralları ezberlemesini sağlamayın. Kuralların doğru yerlerde yürütülmesine izin verin.

Bu, Ajan değerlendirmesinden çıkan bir derse benzer:

Apidog CLI + BECERİ'de:

CLI'nin yapıyı doğrulamasını sağlayın. Ajanların içeriği oluşturmasını sağlayın.

Model Hafızasıyla İlgili Sorun

Bir Yapay Zeka Ajanı, Apidog kaynaklarını oluşturmaya veya güncellemeye yardımcı olduğunda, riskli kısım sadece içerik oluşturmak değildir.

Riskli kısım, oluşturulan içeriği yeterli yapı veya doğrulama olmadan gerçek bir projeye yazmaktır.

Apidog kaynakları yapılandırılmıştır. Bir test senaryosunun veya test durumunun neler içerdiğini düşünün:

Eğer bir Ajan yapıyı tahmin ederse:

• Yanlış alan adı → Başarısız yazma
• Geçersiz enum değeri → Sunucu reddi
• Gerekli alan eksik → Eksik kaynak
• Yanlış tür → Kullanıcı arayüzü görüntüleme sorunları
• Yanlış iç içe geçmişlik → Testler beklendiği gibi davranmaz

cli-schema validate: Kalite Kapısı

İlkemizin en doğrudan somutlaşmış hali cli-schema validate'dir.

apidog cli-schema validate test-scenario-update --file ./scenario-update.json

Bir Ajan bir test senaryosu yazmak veya güncellemek istediğinde, Yapay Zeka'nın karmaşık adım yapıları oluşturması çok hataya açık bir durumdur.

validate komutu:

• Alan adlarını doğrular
• Yapısal geçerliliği kontrol eder
• Enum değerinin etkinliğini doğrular
• Tür kısıtlamalarını doğrular

Tüm bunlar, yazma isteği başlatılmadan önce yapılır.

cli-schema'nın Yakaladığı Yaygın Hatalar

İşte Ajanların sıkça yaptığı ve cli-schema validate'ın yakaladığı hatalara dair gerçek örnekler:

Bunlar teorik değil. Gerçek Ajan etkileşimleri aracılığıyla keşfettik.

Her hata şunlara neden olurdu:

• Başarısız bir yazma isteği
• Bir API hata yanıtı
• Neyin yanlış gittiği konusunda Ajanın kafasının karışması
• Birden fazla yeniden deneme girişimi
• Tekrarlanan çağrılarda token israfı

cli-schema validate ile bu hatalar, ağ çağrısından önce, yerel olarak yakalanır.

Tasarım Felsefesi

Alternatifleri düşünelim:

Alternatif 1: Kuralları İstemlere Yazmak

Eğer tüm alan kurallarını Ajanın istemine yazsaydık:

• Her alan adı belgelendi
• Her enum değeri listelendi
• Her tür kısıtlaması açıklandı
• Her iç içe geçmiş yapı tanımlandı

Sonuç: Büyük bağlam yükü.

Kapsamlı bir test senaryosu şeması, kolayca 5.000'den fazla tokenlik açıklama gerektirebilir. Bu, modelin çoğu kuralın ilgili olmadığı durumlarda bile her görev için taşıması gereken bir bağlamdır.

Alternatif 2: Model Hafızasına Güvenmek

Eğer modelin doğru yapıyı "bilmesine" güvenirsek:

• Model bazı API kalıpları üzerinde eğitilmiş
• Ancak özellikle Apidog şemaları üzerinde değil
• Alan adları ürünler arasında farklılık gösterir
• Enum değerleri ürüne özeldir

Sonuç: Yüksek hata oranları.

Model, Apidog'a özgü kuralları mükemmel bir şekilde hatırlamaz. Tahmin edecektir ve tahminler yanlış olacaktır.

Daha İyi Yaklaşım: Yerel Olarak Doğrula

Ajanın taslaklar oluşturmasına izin verin. CLI'nin yazmadan önce doğrulamayı yürütmesini sağlayın.

# Ajan JSON oluşturur
# (Ajanın tüm kuralları ezberlemesine gerek yoktur)

# CLI doğrular
apidog cli-schema validate test-case-create --file ./test-case-create.json

# CLI varsa belirli hataları verir
# Ajan hatalara göre ayar yapar

# Yalnızca geçerli yazma işlemleri devam eder
apidog test-case create --project <projectId> --file ./test-case-create.json

Şema Dönüşümü

cli-schema validate, Şemanın anlamını dönüştürür:

Sorunlar anlamsız ileri geri ağ isteklerinde tüketilmez.

Kalite kontrolleri yerel komutlar aracılığıyla tamamlanır.

Pratik Örnek

Gerçek bir iş akışını inceleyelim:

# Ajan uç noktayı okur
apidog endpoint get <endpointId> --project <projectId>

# Ajan test durumu JSON'u oluşturur
# (./test-case-create.json oluşturur)

# Yazmadan önce doğrula
apidog cli-schema validate test-case-create --file ./test-case-create.json

Doğrulama başarılı olursa:

apidog test-case create --project <projectId> --file ./test-case-create.json

Doğrulama başarısız olursa:

Error: Field "assertions[0].comparator" has invalid value "contains"
Valid values: equal, not_equal, greater, less, include, not_include, exists, not_exists

Error: Field "extractors[0].type" has invalid value "global"
Valid values: globals, environment, collection, local

Suggestion: Fix these fields and re-validate before writing.

Ajan:

1. Belirli hataları okur
2. Neyin yanlış olduğunu tam olarak anlar
3. JSON dosyasını ayarlar
4. Doğrulamayı yeniden çalıştırır
5. Yalnızca geçerli olduğunda devam eder

Başarısız yazma yok. Karışık yeniden denemeler yok. Boşa harcanan tokenler yok.

Daha Geniş Ders

Bu ilke doğrulamanın ötesine geçer.

Deterministik kurallar → Mühendislik sistemi

Semantik yargı → Ajan

Sırada Ne Var

Doğrulama ilkesini belirlediğimize göre, bir sonraki soru şudur:

Doğrulamadan sonra CLI, Ajanı bir sonraki adıma nasıl yönlendirir?

4. Bölüm'de, agentHints: CLI'lara Ajanlarla Konuşmayı Öğretmek, bir sonraki adım önerileriyle yapılandırılmış çıktının CLI'yi bir komut yürütücüsünden bir iş akışı gezginine nasıl dönüştürdüğünü inceleyeceğiz.

Temel Çıkarımlar

• Temel ilke: kurallar bağlamda değil, yürütmede olmalıdır
• cli-schema validate, yazmadan önce kalite kapısıdır
• Yaygın hatalar: yanlış alan adları, geçersiz enum'lar, yanlış türler
• Doğrulama, hataları yerel olarak yakalayarak ağ gidiş-dönüşlerini önler
• Şema, "ezberlenecek bilgi"den "geçilmesi gereken kapıya" dönüşür
• Deterministik kurallar → mühendislik; semantik yargı → Ajan

Tek bir çalışma alanında API'ları tasarlamak, mock'lamak, test etmek ve belgelemek için Apidog'u indirin. Komut satırı API testi, CI otomasyonu ve AI Ajan iş akışları için Apidog CLI hakkında daha fazla bilgi edinin.