Bu seri, Apidog'un API testi ve API yaşam döngüsü yönetimi için komut satırı aracı olan Apidog CLI'ı nasıl geliştirdiğini anlatır. Sırasıyla okuyabilir veya ihtiyacınız olan bölüme doğrudan geçebilirsiniz:
| Başlık | Odak Noktası | |
|---|---|---|
| 1 | 126 MCP Aracı Geliştirdik. Ama Ajan İçin En İyi Çözüm Bu Değil | Problem keşfi |
| 2 | Neden Yepyeni Apidog CLI'ı Geliştirdik | Mimari geliştirme |
| 3 | Altın Kural: CLI Gerçekleri Üretir, Model Gerçekler Üzerinde Hareket Eder | Temel felsefe |
| 4 | agentHints: CLI'lara Ajanlarla Konuşmayı Öğretmek |
Yapılandırılmış çıktı |
| 5 | BECERİ: Operasyonel Deneyimi Kod Olarak Göndermek | Operasyonel deneyim |
| 6 | Sayılar Yalan Söylemez: %30 Daha Az Araç Çağrısı, %25 Daha Az Token | Nicel sonuçlar |
| 7 | PRD'den Test Döngüsüne: Apidog CLI ile Eksiksiz Bir Ajan İş Akışı | Pratik eğitim |
| 8 | CI/CD Uyumluluğu Neden Ajan Araçları İçin Tartışılmazdır | DevOps bakış açısı |
| 9 | Yapay Zeka Dalı: Yapay Zeka Ajanları ile Daha Güvenli Proje Değişiklikleri | Güvenlik katmanı |
| 10 | Önce Şartname Dündü. Yetenek-Önce'ye Hoş Geldiniz. | Vizyon ve gelecek |
Modelin tüm kuralları ezberlemesini sağlamayın; kuralları doğru yerde çalıştırın. cli-schema validate, şemayı ezberlenecek bilgiden yazma öncesi kalite kapısına dönüştürür.
Temel İlke: Kuralları Doğru Yerde Çalıştırın
Ajan tabanlı API iş akışlarında kritik ayrım şudur:
Modelin tüm kuralları ezberlemesini beklemeyin. Deterministik kuralları araçlara taşıyın.
Pratik karşılığı:
| Gösterge Türü | Ait Olduğu Yer |
|---|---|
| Deterministik kontroller | Betikler, CLI komutları, otomatik doğrulama |
| Semantik yargılar | LLM'ler, ajan akıl yürütmesi |
Apidog CLI + BECERİ yaklaşımında bu ayrım şöyle uygulanır:
| Ne | Nerede |
|---|---|
| Yapı doğrulama | CLI (cli-schema) |
| Görev ayrıştırma, içerik üretimi | Ajanlar |
Kısaca:
CLI yapıyı doğrulasın. Ajan içeriği oluştursun.
Sorun: Model Hafızasına Güvenmek Kırılgandır
Bir Yapay Zeka Ajanı Apidog kaynakları oluşturduğunda veya güncellediğinde asıl risk yalnızca içerik üretimi değildir.
Asıl risk şudur:
Üretilen içeriği yeterli yapı doğrulaması olmadan gerçek projeye yazmak.
Bir test senaryosu veya test durumu birçok yapılandırılmış parçadan oluşur:
| Bileşen | Dikkat Edilmesi Gerekenler |
|---|---|
| İstek verisi | Metot, URL, başlıklar, gövde, kimlik doğrulama |
| Onaylar | Karşılaştırıcı, konu, hedef değer, koşullar |
| Değişken çıkarma | Değişken adı, tür, çıkarma yolu |
| Ön işlemciler | İstek öncesi betikler |
| Son işlemciler | Yanıt sonrası betikler |
| Adım sırası | Sıralama, bağımlılıklar |
| Ortam referansları | Ortam Kimliği, değişken geçersiz kılmaları |
Ajan bu yapıyı tahmin etmeye çalışırsa şu hatalar kolayca oluşur:
- Yanlış alan adı → Yazma isteği başarısız olur
- Geçersiz enum değeri → Sunucu isteği reddeder
- Eksik zorunlu alan → Kaynak eksik veya bozuk oluşur
- Yanlış tür → UI veya çalışma zamanı sorunları çıkar
- Yanlış iç içe geçmiş yapı → Test beklenen şekilde çalışmaz
Bu yüzden doğrulama, yazma işleminden önce ve mümkünse yerel olarak yapılmalıdır.
cli-schema validate: Yazma Öncesi Kalite Kapısı
cli-schema validate, ajan tarafından oluşturulan JSON'u Apidog'a yazmadan önce doğrulamak için kullanılır.
Örnek:
apidog cli-schema validate test-scenario-update --file ./scenario-update.json
Bu komut, yazma isteği yapılmadan önce şunları kontrol eder:
- Alan adları doğru mu?
- İç içe geçmiş yapı geçerli mi?
- Enum değerleri destekleniyor mu?
- Tür kısıtlamaları karşılanıyor mu?
- Zorunlu alanlar mevcut mu?
Önerilen akış:
# 1. Ajan JSON dosyasını üretir
# ./scenario-update.json
# 2. CLI dosyayı yerel olarak doğrular
apidog cli-schema validate test-scenario-update --file ./scenario-update.json
# 3. Sadece doğrulama başarılıysa yazma işlemi yapılır
apidog test-scenario update --project <projectId> --file ./scenario-update.json
Buradaki amaç, API çağrısı yapmadan önce hataları yakalamaktır.
cli-schema Hangi Hataları Yakalar?
Ajanların sık yaptığı bazı hatalar:
| Yanlış Değer | Doğru Değer | Bağlam |
|---|---|---|
global |
globals |
Değişken kapsam türü |
contains |
include |
Onay karşılaştırıcısı |
responseBody |
responseJson |
Yanıt gövdesi konusu |
"500" |
500 |
Milisaniye cinsinden gecikme |
equals |
equal |
Onay karşılaştırıcısı |
header |
headers |
İstek başlıkları alanı |
Bu hatalar teorik değildir; gerçek ajan etkileşimlerinde ortaya çıkmıştır.
cli-schema validate olmadan her biri şu sonuçlara yol açabilir:
- Başarısız yazma isteği
- API hata yanıtı
- Ajanın hatayı yanlış yorumlaması
- Gereksiz yeniden denemeler
- Fazladan araç çağrıları ve token tüketimi
Doğrulama yerel çalıştığında hata daha erken ve daha net yakalanır.
Neden Kuralları İsteme Yazmak Yeterli Değil?
Bir seçenek, tüm kuralları ajanın sistem veya görev istemine eklemektir:
- Tüm alan adları
- Tüm enum değerleri
- Tüm tür kısıtlamaları
- Tüm iç içe geçmiş yapı kuralları
Ancak bu yaklaşımın maliyeti yüksektir:
- Bağlam büyür
- Token tüketimi artar
- Model gereksiz kuralları her görevde taşır
- Yine de hatasız üretim garanti edilmez
Kapsamlı bir test senaryosu şeması kolayca binlerce tokenlık açıklama gerektirebilir. Üstelik her görevde bu kuralların yalnızca küçük bir kısmı kullanılır.
Daha iyi yaklaşım:
Ajan taslağı oluştursun. CLI, yazmadan önce taslağı doğrulasın.
Uygulanabilir İş Akışı
Aşağıdaki akış, ajan + CLI kullanımında güvenli yazma için temel kalıptır.
# Ajan uç noktayı okur
apidog endpoint get <endpointId> --project <projectId>
# Ajan test durumu JSON dosyasını oluşturur
# ./test-case-create.json
Yazmadan önce doğrulama çalıştırılır:
apidog cli-schema validate test-case-create --file ./test-case-create.json
Doğrulama başarılıysa:
apidog test-case create --project <projectId> --file ./test-case-create.json
Doğrulama başarısızsa CLI açık hata döndürür:
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.
Bu durumda ajan şu adımları izler:
- Hata mesajlarını okur
- Yanlış alanları belirler
- JSON dosyasını düzeltir
-
cli-schema validatekomutunu tekrar çalıştırır - Yalnızca doğrulama başarılıysa yazma işlemine geçer
Sonuç:
- Başarısız yazma yok
- Belirsiz API hataları yok
- Gereksiz yeniden deneme yok
- Daha az token tüketimi
Şema Ne Anlama Gelmeli?
cli-schema validate, şemanın rolünü değiştirir.
| Önce | Sonra |
|---|---|
| Şema = modelin ezberlemesi gereken bilgi | Şema = geçilmesi gereken kalite kapısı |
| Hatalar yazma isteğinden sonra bulunur | Hatalar yerel doğrulamada bulunur |
| Düzeltme ağ çağrılarıyla denenir | Düzeltme yerel dosya üzerinde yapılır |
| Kurallar bağlama yüklenir | Kurallar yürütme zamanında kontrol edilir |
Bu yaklaşımda şema, açıklama dokümanı olmaktan çıkar ve otomatik kontrol mekanizmasına dönüşür.
Ajan İş Akışlarında Sorumlulukları Ayırın
Bu ilke yalnızca şema doğrulama için geçerli değildir. Ajan sistemlerinde genel bir tasarım kuralıdır:
| Kural Türü | Ait Olduğu Yer |
|---|---|
| Alan adı kuralları | cli-schema |
| Enum değer kuralları | cli-schema |
| Tür kısıtlamaları | cli-schema |
| İş akışı sırası | BECERİ |
| Sonraki adım rehberliği | agentHints |
| Görev ayrıştırması | Ajan |
Özet:
Deterministik kurallar → mühendislik sistemi
Semantik yargı → ajan
Ajanın güçlü olduğu alan; niyeti anlamak, görevleri bölmek ve içerik üretmektir.
CLI'nin güçlü olduğu alan; yapıyı, türleri ve geçerliliği deterministik olarak kontrol etmektir.
Pratik Kontrol Listesi
Ajanla Apidog kaynağı oluşturmadan veya güncellemeden önce şu akışı kullanın:
# 1. Kaynak veya uç nokta bilgisini oku
apidog endpoint get <endpointId> --project <projectId>
# 2. Ajan JSON taslağını oluştursun
# Örnek: ./test-case-create.json
# 3. Yerel doğrulama yap
apidog cli-schema validate test-case-create --file ./test-case-create.json
# 4. Hata varsa JSON'u düzelt ve tekrar doğrula
# 5. Sadece doğrulama başarılıysa yaz
apidog test-case create --project <projectId> --file ./test-case-create.json
Bu kalıp özellikle CI/CD, ajan otomasyonu ve çok adımlı test senaryosu üretimi için kritiktir.
Sırada Ne Var?
Doğrulama kalite kapısını çözdükten sonraki soru şudur:
Doğrulamadan sonra CLI, ajanı bir sonraki adıma nasıl yönlendirir?
- Bölüm'de, agentHints: CLI'lara Ajanlarla Konuşmayı Öğretmek ile yapılandırılmış çıktının CLI'yi yalnızca komut çalıştıran bir araçtan iş akışı rehberine nasıl dönüştürdüğünü inceleyeceğiz.
Temel Çıkarımlar
- Kurallar bağlamda değil, yürütmede olmalıdır.
-
cli-schema validate, yazmadan önce çalışan bir kalite kapısıdır. - Yaygın hatalar: yanlış alan adları, geçersiz enum'lar, yanlış türler.
- Yerel doğrulama, gereksiz ağ çağrılarını ve yeniden denemeleri azaltır.
- Şema, ezberlenecek bilgiden geçilecek kontrole dönüşür.
- Deterministik kurallar CLI'da; semantik kararlar ajanda kalmalıdır.
Tek bir çalışma alanında API'ları tasarlamak, mock'lamak, test etmek ve belgelemek için Apidog'u kullanabilirsiniz. Komut satırı API testi, CI otomasyonu ve AI Ajan iş akışları için Apidog CLI hakkında daha fazla bilgi edinin.
Top comments (0)