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

Bu, 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 paylaşan 10 bölümlük bir seridir. Sırayla okuyun veya ilginizi çeken herhangi bir gönderiye atlayın:

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

CLI Çıktı Açığı

Geleneksel CLI çıktısı **insanlar** için tasarlanmıştır.

Bu, insanlar için işe yarar. İnsanlar şunları yapabilir:

• Belirsiz mesajları yorumlar
• Sırada ne yapacağına karar verir
• Önceki komutlardan gelen bağlamı hatırlar
• Devam etmek için alan bilgisini uygular

**Ancak Ajanlar farklı çalışır.**

Ajanların Gerçekte Neye İhtiyacı Var

Ajanlar sadece sonuçları okumaz. Sonuçları bir sonraki görev zincirine **bağlamaları gerekir.**

Bir insan "Kaynak başarıyla oluşturuldu" ifadesini görür ve şöyle düşünür: "Muhtemelen ne oluşturulduğunu kontrol etmeliyim, sonra belki bazı testler çalıştırmalıyım."

Bir Ajan "Kaynak başarıyla oluşturuldu" ifadesini görür ve... sırada ne yapacağı hakkında hiçbir fikri olmaz.

agentHints: Çözüm

Apidog CLI, çıktısına agentHints 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."
    ]
  }
}

**Üç bileşen:**

Yürütme Ataleti Sorunu

İşte gözlemlediğimiz gerçek bir sorun:

**Bir kaynak başarıyla oluşturulduktan sonra, model genellikle doğrudan bir sonraki yazmayı oluşturmaya devam eder.**

Örnek:

Ajan: Test durumu oluşturur
CLI: Başarı döndürür
Ajan: Hemen test senaryosu oluşturur (geri okumadan)
Ajan: Hemen testleri çalıştırır
Sonuç: Senaryo yanlış yapıya sahip, testler başarısız

Karmaşık iş süreçlerinde, **mekanik sürekli yürütme uygun değildir.**

En doğru yaklaşım genellikle şöyledir:

1. Kaynak oluştur
2. **Önce geri oku**
3. Yapıyı doğrula
4. Sonra devam et

Geri Okumanın Önemi

Geri okumayı atlamak gerçek sorunlara neden olur:

**Gerçek yapı geri okunmazsa, Ajan kolayca kendi tahminine göre yazmaya devam eder; gerçek verilere göre değil.**

agentHints Bir Gezgin Olarak

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

Ajanın **karar vermesi gereken yerde tam olarak görünür.**

Bir test durumu oluşturduktan sonraki örnek:

{
  "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."
    ]
  }
}

Ajan:

1. Çıktıyı okur
2. agentHints'i ayrıştırır
3. nextSteps[0]'ı takip eder: test durumunu geri okur
4. Gerçek yapıyı doğrular
5. Sonra doğru bilgilerle devam eder

CLI Rol Dönüşümü

Bu, CLI'ın Ajan iş akışındaki anlamını değiştirir.

**CLI, hafif bir durum gezgini haline gelir.**

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

Apidog CLI, **binlerce ağaç yapılı iş akışına** sahiptir.

Bunlar sadece sabit kodlanmış öneriler değildir. Şunlardır:

Başarılı test senaryosu güncellemesinden sonraki örnek:

{
  "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."
    ]
  }
}

Doğrulama hatasından sonraki örnek:

{
  "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."
    ]
  }
}

**Hatalar bile gezinilebilir hale gelir.**

agentHints ile Daha Güvenli Döngü

agentHints ile eksiksiz bir iş akışını izleyelim:

Adım 1: Ajan test durumu oluşturur
        ↓
CLI Çıktısı: başarı + agentHints
        ↓
agentHints.nextSteps[0]: "Oluşturulan test durumunu geri oku"
        ↓
Adım 2: Ajan geri okur (gerçek yapıyla)
        ↓
CLI Çıktısı: test durumu yapısı + agentHints
        ↓
agentHints.nextSteps[0]: "Gerekirse iddialar ekle"
        ↓
Adım 3: Ajan iddialar ekler (gerçek yapıya göre)
        ↓
CLI Çıktısı: başarı + agentHints
        ↓
agentHints.nextSteps[0]: "Testleri çalıştır"
        ↓
Adım 4: Ajan testleri çalıştırır
        ↓
CLI Çıktısı: test raporu

**Her adım yönlendirilir. Kör atlamalar yok. Varsayımlar yok.**

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

Sırada Ne Var

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

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

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

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 + sonraki adım önerileri sunar
• Yürütme ataleti, Ajanların geri okumayı atlamasına neden olur; agentHints bunu önler
• CLI, yürütücüden gezgine dönüşür
• Yerleşik iş akışı ağaçları her adımı gezilebilir hale getirir
• Hatalar bile 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.