Bu yazı, Apidog’un API testi ve API yaşam döngüsü yönetimi için geliştirdiği komut satırı aracı Apidog CLI üzerine hazırlanan 10 bölümlük serinin bir parçasıdır. Sırayla okuyabilir veya ilgilendiğiniz bölüme doğrudan geçebilirsiniz.
| Başlık | Odak Noktası | |
|---|---|---|
| 1 | 126 MCP Aracı Oluşturduk. Ancak Bu, Temsilci İçin En İyi Çözüm Değil | Sorun keşfi |
| 2 | Neden Yepyeni Apidog CLI Geliştirdik | Mimari geliştirme |
| 3 | Altın Kural: CLI Gerçekleri Üretir, Model Gerçekler Üzerine Hareket Eder | Temel felsefe |
| 4 | agentHints: CLI'lara Temsilcilerle Konuşmayı Öğretmek |
Yapılandırılmış çıktı |
| 5 | YETENEK: Operasyonel Deneyimi Kod Olarak Gönderme | 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 Temsilci İş Akışı | Pratik eğitim |
| 8 | CI/CD Uyumluluğu Neden Temsilci Araçları İçin Tartışılmazdır? | DevOps perspektifi |
| 9 | Yapay Zeka Dalı: Yapay Zeka Temsilcileri ile Daha Güvenli Proje Değişiklikleri | Güvenlik katmanı |
| 10 | Önce Şartname Dündü. Yetenek-Önce'ye Hoş Geldiniz. | Vizyon ve gelecek |
MCP ile CLI + YETENEK yaklaşımını tipik kullanıcı görevlerinde karşılaştırdık. Sonuç: daha az araç çağrısı, daha az token israfı, daha iyi hata kurtarma.
Bu yazıda sayıları nasıl okumamız gerektiğine ve bu farkların pratikte hangi mühendislik kararlarından geldiğine odaklanacağız.
Ölçtüğümüz Görevler
Karşılaştırma üç yaygın API test iş akışı üzerinden yapıldı:
| Görev Türü | Açıklama |
|---|---|
| Test durumu ekle + doğrulama | Bir uç nokta için test durumu oluştur, ardından testleri çalıştır |
| Test senaryolarını sürdür | Çok adımlı karmaşık senaryoları güncelle |
| Proje varlıklarını içe aktar/doğrula | Verileri içe aktar, yapıyı onayla, testleri çalıştır |
Burada önemli olan sadece “daha iyi hissettirmesi” değil. İyileşmeler ölçülebilir seviyedeydi.
Görev 1: Uç Noktaya Göre Test Durumu Ekle
Kullanıcı talebi:
“Bu uç nokta için bir test ekle ve doğrulamayı çalıştır”
MCP Rotasında Ne Olur?
MCP yaklaşımında temsilci önce doğru aracı bulmak, sonra şemayı anlamak, sonra alanları tahmin etmek zorundadır.
| Aşama | Ne Olur |
|---|---|
| Araç keşfi | Temsilci araç listesinde arama yapar |
| Araç seçimi | Doğru aracı seçmek için birden fazla tur gerekir |
| Alan keşfi | Temsilci araç şemasını okur |
| Alan tahmini | Gerekli alanları tahmin eder |
| Yazma denemesi | Oluşturma aracını çağırır |
| Hata yanıtı | Sunucu yanlış veya eksik alanları reddeder |
| Yeniden deneme | Temsilci alanları düzeltip tekrar dener |
| Testleri çalıştır | Ayrı bir çalıştırma aracı bulunur ve yürütülür |
Tipik desen:
Araçları ara
→ Araç seç
→ Şemayı oku
→ Alanları tahmin et
→ Yaz
→ Hata
→ Yeniden dene
→ Yaz
→ Hata
→ Yeniden dene
→ Başarı
→ Çalıştırma aracını bul
→ Çalıştır
CLI + YETENEK Rotasında Ne Değişir?
CLI + YETENEK yaklaşımında temsilciye görev odaklı bir sıra verilir. CLI gerçek uç nokta bilgisini sağlar, yerel doğrulama hataları ağ çağrısından önce yakalar.
| Aşama | Ne Olur |
|---|---|
| YETENEK rehberliği | Görev türü tanımlanır, iş akışı verilir |
| Uç noktayı oku | CLI uç nokta gerçeklerini döndürür |
| Test durumu oluştur | Temsilci gerçek uç nokta verilerine göre üretir |
| Yerel doğrulama |
cli-schema yazmadan önce doğrular |
| Yaz | CLI geçerli test durumunu oluşturur |
| Geri oku | CLI oluşturulan yapıyı ve agentHints bilgisini döndürür |
| Testleri çalıştır |
agentHints çalıştırmayı önerir, temsilci takip eder |
Tipik desen:
YETENEK rehberlik eder
→ Uç noktayı oku
→ Test durumunu oluştur
→ Yerel doğrula
→ Yaz
→ Geri oku
→ Testleri çalıştır
Sonuçlar
| Metrik | MCP Rotası | CLI + YETENEK | İyileşme |
|---|---|---|---|
| Araç çağırma adımları | ~15-20 | ~10-12 | ↓ %30 |
| Açıklamalardan gelen token | ~50.000 yüklendi | ~2.000 yüklendi | ↓ %96 |
| Yeniden denemelerden gelen token | ~5.000+ israf | ~500 israf | ↓ %90 |
| Toplam token israfı | ~55.000 | ~2.500 | ↓ %25 |
Pratik çıkarım: Temsilciye “hangi aracı bulacağını” bırakmak yerine görev sırasını ve doğrulama kapısını CLI tarafına taşımak, çağrı sayısını ve token israfını azaltır.
Görev 2: Yapılandırılmış Yazmalar
Kullanıcı talebi:
“Bu test durumuna işlem sonrası onaylamaları ve değişken çıkarma ekle”
Bu görevde temsilci; işleyici, onaylama ve çıkartıcı gibi yapılandırılmış alanları doğru formatta yazmalıdır.
MCP Rotasında Tipik Hatalar
MCP rotasında temsilci alan adlarını ve enum değerlerini çoğu zaman tahmin eder.
| Aşama | Ne Olur |
|---|---|
| Alan adlarını tahmin et | Temsilci tam alan adlarını bilmez |
| Enum değerlerini tahmin et | Karşılaştırıcı veya tür değeri tahmin edilir |
| Yazma denemesi | Sunucu yanlış değerleri reddeder |
| Ağ yeniden denemesi | Her hata için yeni gidiş-dönüş oluşur |
| Birden fazla deneme | 3-5 yeniden deneme yaygındır |
Yaygın örnekler:
| Yanlış Tahmin | Doğru Değer | Yeniden Deneme Sayısı |
|---|---|---|
comparator: "contains" |
comparator: "include" |
1-2 |
type: "global" |
type: "globals" |
1-2 |
subject: "responseBody" |
subject: "responseJson" |
1-2 |
Her hata şu maliyetleri üretir:
1 ağ çağrısı
+ hata yanıtı
+ temsilcinin hatayı yorumlaması
+ yeni deneme
CLI + YETENEK Rotasında Uygulama Deseni
CLI + YETENEK yaklaşımı alan hatalarını ağdan önce yakalar.
| Aşama | Ne Olur |
|---|---|
| Test durumunu oku | CLI mevcut gerçek yapıyı alır |
| Eklemeleri oluştur | Temsilci gerçek formata göre üretir |
| Yerel doğrula |
cli-schema ağdan önce hataları yakalar |
| Yerel düzelt | Temsilci doğrulama çıktısına göre ayarlar |
| Tekrar doğrula | Düzeltme kontrol edilir |
| Yaz | Yalnızca geçerli veri sunucuya gönderilir |
Uygulanabilir kontrol listesi:
[ ] Önce mevcut test durumunu oku
[ ] Gerçek alan adlarını ve mevcut yapıyı kullan
[ ] Yeni onaylama/çıkarma bloklarını üret
[ ] Yerel şema doğrulaması çalıştır
[ ] Hata varsa ağ çağrısı yapmadan düzelt
[ ] Geçerliyse yaz
[ ] Yazdıktan sonra geri oku
Sonuçlar
| Metrik | MCP Rotası | CLI + YETENEK | İyileşme |
|---|---|---|---|
| Yapısal hatalardan kaynaklanan ağ yeniden denemeleri | 3-5 | 0 | ↓ %100 |
| Hata yanıtlarından gelen token | ~2.000 | ~0 | ↓ %100 |
| Toplam tekrarlanan çağrılar | ~5 | ~1 | ↓ %40 |
Pratik çıkarım: Yapısal doğrulamayı model bağlamından çıkarıp CLI şema doğrulamasına taşımak, hatalı yazma denemelerini azaltır.
Görev 3: Oluşturma Sonrası Sürekli Operasyonlar
Kullanıcı talebi:
“Bu uç noktalarla bir test senaryosu oluştur”
Bu tür görevlerde kritik adım şudur: oluşturma işleminden sonra gerçek yapıyı geri okumak.
MCP Rotasında Sorun: Yürütme Ataleti
| Aşama | Ne Olur |
|---|---|
| Senaryo oluştur | Temsilci oluşturma aracını çağırır |
| Başarılı yanıt | Temsilci “oluşturuldu” bilgisini görür |
| Yazmaya devam et | Hemen güncelleme veya ekleme yapar |
| Geri okumayı atla | Gerçek oluşan yapı okunmaz |
| Varsayıma dayalı yazma | Tahmini kimlikler veya yapı kullanılır |
| Hata veya eksik sonuç | Sonuç beklentiyi karşılamaz |
Sorun şu desendedir:
Oluşturuldu
→ Başarılı sanıldı
→ Gerçek yapı okunmadı
→ Varsayımla devam edildi
→ Hata veya eksik senaryo
Model başarıdan sonra doğrudan devam etme eğilimindedir. Bu da özellikle ID, sıra, varsayılan alanlar veya otomatik oluşturulan yapıların önemli olduğu işlemlerde risk üretir.
CLI + YETENEK Rotasında agentHints
CLI başarılı yanıtta sadece “başarılı” demekle kalmaz; sonraki adımı da önerir.
| Aşama | Ne Olur |
|---|---|
| Senaryo oluştur | CLI senaryo oluşturur |
Başarı + agentHints
|
CLI başarıyı ve sonraki adım önerilerini döndürür |
agentHints: “Önce geri oku” |
Temsilci öneriyi görür |
| Öneriyi takip et | Temsilci gerçek yapıyı geri okur |
| Gerçek yapı ile çalış | Sonraki işlemler doğru veriyle yapılır |
Güvenli desen:
Oluştur
→ agentHints oku
→ Geri oku
→ Gerçek yapıyı doğrula
→ Sonraki yazmaları gerçek yapı üzerinden yap
Sonuçlar
| Metrik | MCP Rotası | CLI + YETENEK | İyileşme |
|---|---|---|---|
| Devam etmeden önce geri okuyanların oranı | ~%20 | ~%85 | ↑ %425 |
| Doğrudan atlamalardan kaynaklanan hata yeniden denemeleri | ~3-5 | ~0-1 | ↓ %21 |
Pratik çıkarım: Yazma işleminden sonra geri okuma adımını açıkça önermek, temsilcinin varsayımla devam etmesini azaltır.
Tasarruf Nereden Geliyor?
| Tasarruf Kaynağı | Açıklama |
|---|---|
| Araç keşfi | CLI komutları açık adlara sahiptir; YETENEK seçim sürecine rehberlik eder |
| Şema doğrulama | Yerel doğrulama, ağ çağrısından önce hataları yakalar |
| Hata kurtarma |
agentHints sadece “başarısız” demek yerine uygulanabilir öneriler sunar |
| Geri okuma rehberliği | Varsayıma dayalı yazmaları önler |
| İş akışı sırası | YETENEK karar noktalarını azaltır |
Kısaca:
Daha az keşif
+ Daha erken doğrulama
+ Daha açık sonraki adım
= Daha az araç çağrısı ve daha az token israfı
Gerçek Maliyet Analizi
Temsilci destekli ürünlerde temel ders şu:
Daha fazla araç her zaman daha iyi değildir.
Modelin gerçekten tükettiği kaynaklar şunlardır:
| Maliyet Türü | MCP Yükü | CLI + YETENEK Yükü |
|---|---|---|
| Bağlam | Araç açıklamaları, şemalar | Yalnızca göreve odaklı YETENEK |
| Dikkat | Birçok araç arasından seçim yapma | Rehberli iş akışını takip etme |
| Yol seçimi | Sıralamaları tahmin etme | YETENEK tarafından tanımlanan sıra |
| Kullanıcı token maliyetleri | Yeniden denemeler, başarısız çağrılar | Doğrulanmış yazmalar, daha az çağrı |
Araç sayısı arttıkça maliyet sadece “API çağrısı” değildir. Asıl maliyet; bağlam, dikkat, yol seçimi ve hata kurtarma yüküdür.
Mühendislik Prensibi
Hedef:
Maliyetleri model bağlamından çıkarıp mühendislik sisteminin karşılayabileceği katmanlara taşımak.
| Maliyet | MCP Konumu | CLI + YETENEK Konumu |
|---|---|---|
| Araç keşfi | Model aramalıdır | YETENEK sağlar |
| Alan doğrulama | Model bilmelidir |
cli-schema doğrular |
| Sonraki adım rehberliği | Model karar vermelidir |
agentHints önerir |
| Ürün semantiği | Model anlamalıdır | CLI ele alır |
Bu yaklaşımda mühendislik sistemi karmaşıklığı emer. Model ise üretim, yorumlama ve karar vermeye odaklanır.
Sayılar Ne Anlama Geliyor?
| İçgörü | Çıkarım |
|---|---|
| %30 daha az araç çağrısı | Karmaşıklık keşiften rehberliğe taşındı |
| %25 daha az israf edilen token | Hatalar ağdan önce yakalandı |
| %40 daha az yapısal yeniden deneme | Doğrulama kapısı çalışıyor |
| %21 daha az atlama hatası |
agentHints kör devamı önlüyor |
CLI + YETENEK sadece daha düzenli bir mimari değil; ölçülebilir bir verimlilik kazancıdır.
Kendi Temsilci İş Akışınız İçin Uygulanabilir Şablon
Benzer bir temsilci + CLI sistemi tasarlıyorsanız şu sırayı kullanabilirsiniz:
1. Görevi sınıflandır
2. İlgili YETENEK rehberini yükle
3. Mevcut gerçek veriyi CLI ile oku
4. Modelden yalnızca gerekli çıktıyı üretmesini iste
5. Yerel şema doğrulaması çalıştır
6. Hata varsa ağ çağrısı yapmadan düzelt
7. Geçerli veriyi yaz
8. Yazdıktan sonra geri oku
9. agentHints veya benzeri ipuçlarıyla sonraki adımı belirle
10. Testleri veya doğrulamayı çalıştır
Bu desen özellikle şu durumlarda işe yarar:
- Çok sayıda araç varsa
- Alan adları ve enum değerleri katıysa
- Yazma işlemleri geri dönüşü zor değişiklikler yapıyorsa
- Oluşturma sonrası otomatik ID veya varsayılan alanlar oluşuyorsa
- Temsilcinin testleri çalıştırması ve sonucu doğrulaması gerekiyorsa
Sırada Ne Var?
Yaklaşımı sayılarla doğruladığımıza göre, şimdi onu uçtan uca bir iş akışında görelim.
Bölüm 7’de, PRD'den Test Döngüsüne: Eksiksiz Bir Temsilci İş Akışı yazısında gerçek bir örneği inceleyeceğiz: bir ekibin “Sipariş İadesi” PRD’si var ve Temsilci; OpenAPI oluşturmak, testleri üretmek, doğrulamak ve onaylamak için CLI + YETENEK kullanıyor.
Temel Çıkarımlar
- Araç çağırma adımları yaklaşık %30 azaldı.
- Açıklamalardan ve yeniden denemelerden kaynaklanan token israfı yaklaşık %25 azaldı.
- Yapısal hata yeniden denemeleri yaklaşık %40 azaldı.
- Geri okumayı atlamadan kaynaklanan hatalar yaklaşık %21 azaldı.
- Tasarrufun ana kaynakları: rehberli keşif, yerel doğrulama, uygulanabilir ipuçları.
- Karmaşıklık model bağlamından mühendislik sistemine taşındı.
Apidog’u tek bir çalışma alanında API’ları tasarlamak, taklit etmek, test etmek ve belgelemek için kullanabilirsiniz. Komut satırı API testi, CI otomasyonu ve Yapay Zeka Temsilcisi iş akışları için Apidog CLI hakkında daha fazla bilgi edinin.
Top comments (0)