DEV Community

Cover image for CLI ve Ajan İletişimi: Komut Satırı Arayüzlerini Aktif Hale Getirme
Tobias Hoffmann
Tobias Hoffmann

Posted on • Originally published at apidog.com

CLI ve Ajan İletişimi: Komut Satırı Arayüzlerini Aktif Hale Getirme

Bu seri, Apidog'un API testi ve API yaşam döngüsü yönetimi için bir komut satırı aracı olan Apidog CLI'yi nasıl geliştirdiğini anlatır. Sırayla okuyabilir veya ilginizi çeken bölüme geçebilirsiniz:

Apidog'u bugün deneyin

Başlık Odak
1 126 MCP Aracı İnşa Ettik. Ama Ajan İçin En İyi Çözüm Bu Değil Sorun tespiti
2 Neden Yepyeni Apidog CLI Geliştirdik Mimari geliştirme
3 Altın Kural: CLI Gerçekler Üretir, Model Gerçeklere Göre Hareket Eder Temel felsefe
4 agentHints: CLI'lara Ajanlarla Konuşmayı Öğretmek Yapılandırılmış çıktı
5 BECERİ: Operasyonel Deneyimi Kod Olarak Sunma 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 Ajan Araçları İçin CI/CD Uyumluluğu Neden Tartışılamaz DevOps bakış açısı
9 Yapay Zeka Dalı: Yapay Zeka Ajanları ile Daha Güvenli Proje Değişiklikleri Güvenlik katmanı
10 Önce Spesifikasyon Dündeydi. Yetenek Odaklılığa Hoş Geldiniz. Vizyon & gelecek

Geleneksel CLI çıktısı insanlar içindir. Ajanların ise yapılandırılmış sonuçlara, hata nedenlerine ve sonraki adım önerilerine ihtiyacı vardır. agentHints, ürün deneyimini makine tarafından okunabilir rehberliğe dönüştürür.

CLI Çıktı Açığı

Geleneksel CLI çıktısı genellikle insanın okuyup yorumlayacağı şekilde tasarlanır.

Başarı durumunda Hata durumunda
"Başarılı" veya "Tamamlandı" yazdırılır Hata mesajı yazdırılır
Belki oluşturulan kaynak gösterilir Belki yığın izi gösterilir
İnsan sonraki adımı belirler İnsan hata ayıklar

Bu model insanlar için çalışır çünkü insanlar:

  • Belirsiz mesajları yorumlayabilir
  • Bir sonraki adımı kendisi seçebilir
  • Önceki komutlardan gelen bağlamı hatırlayabilir
  • Alan bilgisini kullanarak eksikleri tamamlayabilir

Ancak ajanlar farklı çalışır.

Ajanların Gerçekte Neye İhtiyacı Var?

Ajanlar sadece sonucu okumaz. Sonucu bir sonraki görev zincirine bağlamaları gerekir.

Ajan ihtiyacı Neden gerekli?
Yapılandırılmış sonuçlar Çıktı programatik olarak ayrıştırılmalıdır
Hata nedenleri Genel hata metni yerine belirli ayrıntılar gerekir
Sonraki adım önerileri Ajanın sıradaki eylemi seçmesi gerekir

Örneğin bir insan şu çıktıyı gördüğünde ne yapacağını tahmin edebilir:

Kaynak başarıyla oluşturuldu.
Enter fullscreen mode Exit fullscreen mode

Muhtemelen kaynağı kontrol eder, yapısını doğrular ve sonra testleri çalıştırır.

Bir ajan için ise bu çıktı yetersizdir. Çünkü şu sorular yanıtsız kalır:

  • Hangi kaynak oluşturuldu?
  • Hangi ID ile oluşturuldu?
  • Geri okunmalı mı?
  • Teste eklenmeli mi?
  • Doğrulama gerekli mi?
  • Sıradaki güvenli adım nedir?

agentHints: Çözüm

Apidog CLI, çıktıya agentHints alanı ekler.

Tipik bir yanıt şöyle görünür:

{
  "success": true,
  "data": {
    "id": "12345",
    "name": "Health Check Test Case"
  },
  "agentHints": {
    "summary": "Test durumu başarıyla oluşturuldu.",
    "nextSteps": [
      "Oluşturulan test durumunu yapısını doğrulamak için geri okuyun.",
      "Test durumu yanıt doğrulama gerektiriyorsa iddialar ekleyin.",
      "Entegrasyon testi için test durumunu bir test senaryosuna ekleyin.",
      "Senaryoya eklendikten sonra ilgili testleri çalıştırın."
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode

Bu yapıda üç kritik parça vardır:

Bileşen Amaç
success + data Komutun gerçek sonucu
summary İnsan tarafından okunabilir kısa özet
nextSteps Ajanın izleyebileceği sonraki adımlar

Bu sayede CLI yalnızca sonucu döndürmez; aynı zamanda ajana güvenli ilerleme yolu da verir.

Yürütme Ataleti Sorunu

Ajan iş akışlarında sık görülen sorunlardan biri şudur:

Bir kaynak başarıyla oluşturulduktan sonra model genellikle doğrudan bir sonraki yazma işlemine geçer.

Örnek akış:

Ajan: Test durumu oluşturur
CLI: Başarı döndürür
Ajan: Geri okumadan test senaryosu oluşturur
Ajan: Hemen testleri çalıştırır
Sonuç: Senaryo yanlış yapıya sahiptir, testler başarısız olur
Enter fullscreen mode Exit fullscreen mode

Karmaşık API test iş akışlarında mekanik şekilde komuttan komuta atlamak güvenli değildir.

Daha güvenli akış şudur:

  1. Kaynak oluştur
  2. Oluşturulan kaynağı geri oku
  3. Gerçek yapıyı doğrula
  4. Sonraki adıma geç

Geri Okuma Neden Önemli?

Geri okuma, ajanın tahmin yerine gerçek veriyle devam etmesini sağlar.

Geri okuma atlanırsa şu sorunlar oluşabilir:

Sorun Neden
Yanlış varsayılan değerler Sunucu, ajanın belirtmediği alanları varsayılanlarla doldurabilir
Eksik ilişkili kimlikler İçe aktarma veya oluşturma işlemi yeni dahili ID'ler üretebilir
Yapısal farklar Ön uç veya API belirli bir veri yapısına bağlı olabilir
Yanlış varsayımlar Ajan gerçek çıktı yerine tahmine göre yazmaya devam eder

Özetle: gerçek yapı geri okunmazsa ajan, gerçek verilere göre değil kendi varsayımına göre ilerler.

agentHints Bir Gezgin Gibi Çalışır

agentHints, ürün deneyimini makine tarafından okunabilir sonraki adım önerilerine dönüştürür.

Örneğin bir test durumu oluşturduktan sonra CLI şu yönlendirmeyi döndürebilir:

{
  "agentHints": {
    "nextSteps": [
      "Oluşturulan test durumunu --with-case-detail bayrağıyla geri okuyun.",
      "Yazmadan önce herhangi bir güncellemeyi cli-schema ile doğrulayın.",
      "Test senaryosunu tamamladıktan sonra testleri çalıştırın."
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode

Ajan bu çıktıyı şu şekilde kullanabilir:

  1. CLI çıktısını okur
  2. agentHints alanını ayrıştırır
  3. nextSteps[0] değerini izler
  4. Test durumunu geri okur
  5. Gerçek yapıyı doğrular
  6. Sonraki adıma doğru bilgilerle geçer

Bu yaklaşım, ajanın kör şekilde yazma işlemlerine devam etmesini engeller.

CLI Rolü Nasıl Değişiyor?

Bu model, CLI'ın ajan iş akışındaki rolünü değiştirir.

Eski rol Yeni rol
Komut yürütücü İş akışı gezgini
Sonuç yazdırır Sonraki adımı yönlendirir
İnsan tarafından okunabilir çıktı üretir Ajan tarafından okunabilir yapı üretir
Tek seferlik yanıt verir Sürekli rehberlik sağlar

CLI artık sadece bir komut aracı değil, hafif bir durum gezgini haline gelir.

Yerleşik İş Akışı Ağaçları

Apidog CLI, binlerce ağaç yapılı iş akışı içerir.

Bu öneriler yalnızca sabit metinler değildir. Şu özelliklere sahiptir:

Özellik Açıklama
Bağlama duyarlı Öneriler yapılan işlemle eşleşir
Kaynağa özel Uç noktalar, test durumları ve senaryolar için farklı ipuçları üretir
İş akışına duyarlı Öneriler tipik işlem sıralarını yansıtır
Hataya dayalı Başarı ve hata durumlarında farklı yönlendirme verir

Başarılı test senaryosu güncellemesinden sonra örnek çıktı:

{
  "agentHints": {
    "summary": "Test senaryosu başarıyla güncellendi.",
    "nextSteps": [
      "Değişiklikleri doğrulamak için test senaryosunu çalıştırın.",
      "Herhangi bir hata için test raporunu kontrol edin.",
      "Hata oluşursa, hata ayıklama için senaryo adımlarını geri okuyun."
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode

Doğrulama hatasından sonra örnek çıktı:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Field 'comparator' has invalid value",
    "details": []
  },
  "agentHints": {
    "summary": "Doğrulama başarısız oldu. Hataları düzeltin ve yeniden doğrulayın.",
    "nextSteps": [
      "Çıktıdaki hata ayrıntılarını inceleyin.",
      "Hata önerilerine göre JSON dosyasını ayarlayın.",
      "Yazmadan önce cli-schema doğrulamasını yeniden çalıştırın."
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode

Bu yapı sayesinde hatalar bile eyleme geçirilebilir hale gelir.

agentHints ile Daha Güvenli Döngü

agentHints kullanıldığında örnek bir test iş akışı şöyle ilerler:

Adım 1: Ajan test durumu oluşturur
        ↓
CLI Çıktısı: success + data + agentHints
        ↓
agentHints.nextSteps[0]: "Oluşturulan test durumunu geri oku"
        ↓
Adım 2: Ajan test durumunu geri okur
        ↓
CLI Çıktısı: gerçek test durumu yapısı + agentHints
        ↓
agentHints.nextSteps[0]: "Gerekirse iddialar ekle"
        ↓
Adım 3: Ajan iddialar ekler
        ↓
CLI Çıktısı: success + agentHints
        ↓
agentHints.nextSteps[0]: "Testleri çalıştır"
        ↓
Adım 4: Ajan testleri çalıştırır
        ↓
CLI Çıktısı: test raporu
Enter fullscreen mode Exit fullscreen mode

Bu döngüde her adım yönlendirilir:

  • Kör atlama yoktur
  • Varsayıma göre yazma yoktur
  • Geri okuma teşvik edilir
  • Hata durumunda düzeltme yolu görünür hale gelir

Karşılaştırma: agentHints ile ve Olmadan

Senaryo agentHints olmadan agentHints ile
Oluşturduktan sonra Ajan bir sonraki yazma işlemine geçer Ajan önce geri okur
Güncelledikten sonra Ajan başarı varsayar Ajan yapıyı doğrular
Doğrulama geçtikten sonra Ajan hemen yazar Ajan yazar, sonra geri okur
Doğrulama başarısız olduktan sonra Ajan hatayı yorumlamakta zorlanır Ajan belirli düzeltme önerileri alır
Test çalıştırmasından sonra Ajan yalnızca başarılı/başarısız sonucunu görür Ajan hata ayıklama rehberliği alır

Uygulama Açısından Çıkarım

Ajanlarla kullanılacak bir CLI tasarlıyorsanız, yalnızca insan okunabilir metin döndürmek yeterli değildir.

Daha güvenli bir çıktı sözleşmesi şu alanları içermelidir:

{
  "success": true,
  "data": {},
  "error": null,
  "agentHints": {
    "summary": "Kısa durum özeti.",
    "nextSteps": [
      "Sonraki güvenli adım.",
      "Gerekirse doğrulama adımı.",
      "Gerekirse test veya raporlama adımı."
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode

Başarısız durumda da aynı yapı korunmalıdır:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Alan doğrulaması başarısız oldu.",
    "details": []
  },
  "agentHints": {
    "summary": "Doğrulama başarısız oldu.",
    "nextSteps": [
      "error.details alanını inceleyin.",
      "Girdi JSON'unu şemaya göre düzeltin.",
      "Yazma işleminden önce doğrulamayı yeniden çalıştırın."
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode

Bu yaklaşım, CLI çıktısını yalnızca raporlama formatı olmaktan çıkarır ve ajan için yürütülebilir iş akışı rehberine dönüştürür.

Sırada Ne Var?

Artık CLI, ajanları sonraki adımlar boyunca yönlendirebildiğine göre sıradaki soru şudur:

Ajanlar ilk etapta hangi iş akışını takip edeceklerini nasıl bilir?

  1. Bölüm'de, BECERİ: Operasyonel Deneyimi Kod Olarak Sunma, SKILL'in iş akışı bilgisini nasıl paketlediğini inceleyeceğiz: hangi komutların ne zaman kullanılacağı, hangi sıranın takip edileceği ve hangi alanların tahmin edilmemesi gerektiği.

Temel Çıkarımlar

  • Geleneksel CLI çıktısı insan odaklıdır; ajanlar yapılandırılmış rehberliğe ihtiyaç duyar.
  • agentHints, JSON çıktısında özet ve sonraki adım önerileri sağlar.
  • Yürütme ataleti, ajanların geri okumayı atlamasına neden olabilir.
  • agentHints, geri okuma ve doğrulama adımlarını görünür hale getirir.
  • CLI, komut yürütücüden iş akışı gezginine dönüşür.
  • Yerleşik iş akışı ağaçları her adımı daha güvenli ve takip edilebilir hale getirir.
  • Hatalar, agentHints ile eyleme geçirilebilir hale gelir.

Apidog'u indirerek API'leri tek bir çalışma alanında tasarlayın, taklit edin, test edin ve belgelendirin. Komut satırı API testi, CI otomasyonu ve Yapay Zeka Ajanı iş akışları için Apidog CLI hakkında daha fazla bilgi edinin.

Top comments (0)