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 hakkında 10 bölümlük serinin 5. bölümüdür. Sırayla okuyabilir veya doğrudan ilgilendiğiniz bölüme geçebilirsiniz:
| # | Başlık | Odak |
|---|---|---|
| 1 | 126 MCP Aracı Geliştirdik. Ama Ajan iç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çekleri Üretir, Model Gerçekler Üzerinde Hareket Eder | Çekirdek felsefe |
| 4 | agentHints: CLI'lara Ajanlarla Konuşmayı Öğretmek |
Yapılandırılmış çıktı |
| 5 | SKILL: 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 | Ajan Araçları için CI/CD Uyumluluğu Neden Vazgeçilmezdir? | DevOps perspektifi |
| 9 | Yapay Zeka Dalı: Yapay Zeka Ajanları ile Daha Güvenli Proje Değişiklikleri | Güvenlik katmanı |
| 10 | Önce Şartname Dündü. Yetenek Odaklı Yaklaşıma Hoş Geldiniz. | Vizyon ve gelecek |
Bir SKILL sadece komut referansı değildir. Yapay Zeka Ajanları için bir işletim kılavuzudur: hangi komut ne zaman kullanılır, hangi komut önce gelir, hangi alanlar tahmin edilmemelidir, ne zaman doğrulama yapılır ve ne zaman geri okuma gerekir.
Yalnızca CLI Yeterli Değil
CLI komutları bir Ajana yürütme gücü verir. Ancak Ajanın sadece komut çalıştırabilmesi yeterli değildir; doğru sırayı, güvenli sınırları ve doğrulama noktalarını da bilmesi gerekir.
| CLI Gücü | Muhakeme Olmadan Risk |
|---|---|
| Test durumu oluşturma | Yanlış projede oluşturur |
| Test senaryosunu güncelleme | Geri okumadan günceller |
| Adımları içe aktarma | Mevcut yapıyı kontrol etmeden içe aktarır |
| Testleri çalıştırma | Değişiklikleri doğrulamadan çalıştırır |
Sonuç: Ajanlar komutlardan fazlasına ihtiyaç duyar. İşletim muhakemesine ihtiyaç duyarlar.
SKILL Nedir?
Bir SKILL, Yapay Zeka Ajanları için yazılmış bir işletim kılavuzudur.
SKILL şunlardan biri değildir:
- Basit bir komut listesi
- Referans dokümanı
- Yardım sayfası
SKILL şunları tarif eder:
| SKILL İçeriği | Amaç |
|---|---|
| Bir komutun ne zaman kullanılacağı | Görev türü → komut eşlemesi |
| Hangi komutun önce geleceği | Sıra rehberliği |
| Hangi alanların tahmin edilmemesi gerektiği | Güvenlik sınırları |
| Ne zaman doğrulanacağı | Kalite kapısı yerleşimi |
| Ne zaman geri okunacağı | Doğrulama zamanlaması |
| Testlerin ne zaman çalıştırılacağı | Onay iş akışı |
Kısaca: SKILL, Ajanlara işletim muhakemesi verir.
Kurulum
SKILL, Apidog CLI ile birlikte kullanılır.
# Yapay Zeka Ajanınız için SKILL'i yükleyin
apidog skill install
Bu komut, Ajanların aşağıdakileri anlamasına yardımcı olan 8 eşlikçi SKILL yükler:
- CLI komut semantiği
- Kaynak yapıları
- Görev iş akışları
- Hata yönetimi
- Doğrulama kalıpları
SKILL Neden Önemlidir?
Bir Ajan bir komutu çalıştırabilir. Ancak çoğu gerçek görev, tek komuttan ibaret değildir.
Örneğin Ajanın şunları bilmesi gerekir:
- Hangi kaynağı önce okuması gerektiği
- Hangi alanları tahmin etmemesi gerektiği
- Ne zaman
validateçalıştırması gerektiği - Ne zaman güncellemeyi uygulaması gerektiği
- Ne zaman testi çalıştırması gerektiği
Bu bilgiler genellikle ürünün içinde saklı olan iş akışlarıdır.
Bu deneyimi şu yerlere koymak iyi çalışmaz:
- Araç açıklamalarına uzun uzun yazmak: çok fazla bağlam tüketir
- Sohbet bağlamına koymak: oturumlar arasında kaybolur
- Modelin ezberlemesini beklemek: ürüne özgü bilgi genel model bilgisi değildir
Bu yüzden gizli iş akışları ve iş tuzakları açık rehberlik gerektirir.
Örnek: Test Senaryosu Bakımı
Karmaşık bir test senaryosunu güncellemek istediğinizi düşünün.
Yanlış yaklaşım
Ajan senaryoyu sıfırdan elle yazar:
Ajan: "Test senaryosu yapısını manuel olarak oluşturacağım."
Ajan: Onaylar, çıkarıcılar ve işlemcilerle eksiksiz adımlar dizisi yazar.
Sonuç: Alan hataları, yanlış karşılaştırıcılar, eksik gerekli alanlar.
CLI: Yazmayı reddeder veya eksik senaryo oluşturur.
Bu yaklaşım kırılgandır çünkü Ajan gerçek veri yapısını görmeden iç alanları tahmin eder.
Doğru yaklaşım
SKILL bu iş akışını şu sıraya indirger:
| Adım | Neden |
|---|---|
| 1. Mevcut adımları uç noktalardan veya test durumlarından içe aktarın | Karmaşık yapıları elle yazmayın |
| 2. Eksiksiz yapıyı geri okuyun | Gerçek içe aktarılmış biçimi görün |
| 3. Yerel değişiklikler yapın | Doğru tabanla çalışın |
| 4. Güncellemeden önce doğrulayın | Hataları yerel olarak yakalayın |
| 5. Senaryoyu çalıştırın | Davranışı doğrulayın |
SKILL sadece "test-scenario update komutu var" demez. Bunun yerine Ajana şunu öğretir:
Karmaşık senaryolar, sıfırdan eksiksiz yapıları elle yazmak için uygun değildir. Daha kararlı yol, önce mevcut uç nokta veya durum adımlarını içe aktarmak, ardından eksiksiz yapıyı geri okumak ve son olarak yerel değişiklikler yapmaktır.
SKILL Rehberliğinin Arkasındaki Komutlar
Aşağıdaki akış, test senaryosu bakımında SKILL'in Ajana uygulattığı pratik komut sırasıdır.
# Adım 1: Uç noktalardan adımları içe aktarın
apidog test-scenario import-steps <senaryoKimliği> --project <projeKimliği> \
--source endpoint --ids <uçNoktaKimlikleri> --sync manual
# Adım 2: Senaryoyu tam ayrıntıyla geri okuyun
apidog test-scenario get <senaryoKimliği> --project <projeKimliği> \
--with-case-detail
# Adım 3: Belirli kısımları güncelleyin
# Ajan bu aşamada JSON güncelleme dosyasını oluşturur.
# Adım 4: Güncellemeden önce şemaya göre doğrulayın
apidog cli-schema validate test-scenario-update --file ./senaryo-güncellemesi.json
# Adım 5: Güncellemeyi uygulayın
apidog test-scenario update <senaryoKimliği> --project <projeKimliği> \
--file ./senaryo-güncellemesi.json
# Adım 6: Senaryoyu çalıştırarak doğrulayın
apidog run --project <projeKimliği> --test-scenario <senaryoKimliği>
Bu akışta SKILL, Ajana sadece komutları değil, her komutun ne zaman ve neden kullanılacağını söyler.
Anahtar İçgörü: --with-case-detail
SKILL şu kuralı vurgular:
Gerçek yapıyı elde etmek için
--with-case-detailkullanın. Adımların iç durumunu tahmin etmeyin.
Bu özellikle test senaryosu güncellemelerinde önemlidir.
--with-case-detail Olmadan |
--with-case-detail İle |
|---|---|
| Adımlar yalnızca kimlikleri gösterir | Adımlar tam durum yapılarını gösterir |
| Ajan dahili biçimi bilmez | Ajan gerçek onay ve çıkarıcı biçimini görür |
| Ajan alan adlarını tahmin eder | Ajan gerçek örneklerden çalışır |
Pratik kural: Güncellemeden önce gerçek yapıyı okuyun. Tahmin ederek JSON üretmeyin.
Geliştirilebilirlik: SKILL Değişebilir
Apidog SKILL, geliştirilebilir ve sürümlenebilir bir operasyonel deneyimdir.
Bu önemlidir çünkü:
| Zorluk | SKILL Çözümü |
|---|---|
| CLI komutları değişir | SKILL eşleşecek şekilde güncellenebilir |
| Kullanıcıların kişiselleştirilmiş iş akışları vardır | SKILL özelleştirilebilir |
| Yeni ürün özellikleri eklenir | SKILL genişletilebilir |
| İş akışları iyileşir | SKILL geliştirilebilir |
Ajanlara SKILL üzerinde yazma izinleri verilebilir. Böylece SKILL geride kalırsa veya kullanımı zorlaşırsa:
- Ajan onu değiştirebilir
- Ajan iyileştirme önerebilir
- SKILL kullanım yoluyla gelişir
SKILL dondurulmuş dokümantasyon değildir. Yaşayan operasyonel koddur.
Uyumluluk Katmanı
Bu yaklaşım gerçek hatalardan öğrenildi.
Tespit edilen sorun:
Bazı senaryo adımlarında, ikincil güncellemeler sırasında dış adımlar başarıyla güncellendi, ancak dahili HTTP durumları doğru şekilde güncellenmedi.
Temel nedenler:
- Dahili durum güncelleme işaretçileri özel işlem gerektiriyordu
- Ajanlar bu işaretçileri bilmiyordu
- Ürün semantiği belirli bayraklar gerektiriyordu
Çözüm:
- Uyumluluk mantığı CLI'ya yerleştirildi
- CLI dahili işaretçileri otomatik olarak işler
- Kullanıcıların ve Ajanların dahili ayrıntıları bilmesine gerek kalmaz
Burada görev paylaşımı nettir:
- SKILL, Ajana doğru iş akışını ve komut sırasını söyler
- CLI, komutların arkasındaki ürün semantiğini işler
- Ajan, dahili işaretçileri bilmeden güvenli şekilde çalışır
İsteğe Bağlı Yükleme
SKILL, cli-schema ile aynı prensibi izler:
Karmaşıklık, modele tamamen açılmak yerine yürütme ve dokümantasyon katmanları tarafından absorbe edilmelidir.
Alternatif yaklaşımlar verimsizdir:
| Alternatif | Sorun |
|---|---|
| Tüm SKILL'i bağlama yüklemek | Token yükü oluşturur |
Tüm kuralları --help içine koymak |
Dikkat için rekabet eder |
| Kuralları istem içine yazmak | Güncellenemez |
SKILL yaklaşımı:
- Ajan SKILL'i isteğe bağlı olarak hazırlar
- SKILL, görev türü tanımlandığında yüklenir
- Yalnızca ilgili iş akışı rehberliği bağlama girer
Bu, hem bağlam maliyetini düşürür hem de Ajanın doğru anda doğru rehberliği kullanmasını sağlar.
SKILL vs. Dokümantasyon
| Dokümantasyon | SKILL |
|---|---|
| İnsanların okuması için | Ajanların yürütmesi için |
| Komutların ne yaptığını açıklar | Komutların ne zaman kullanılacağını açıklar |
| Statik referans | Dinamik iş akışı |
| Kapsamlı | Görev odaklı |
| Ajandan harici | Ajan ile entegre |
Dokümantasyon insan geliştiriciler için gereklidir. SKILL ise Ajanın görev sırasında doğru operasyonel kararları almasına yardımcı olur.
8 Eşlikçi SKILL
Apidog, 8 eşlikçi SKILL sağlar:
| SKILL | Kapsam |
|---|---|
| Proje yönetimi | Projeler, meta veriler, kaynaklar |
| API tasarımı | Uç noktalar, şemalar, tanımlar |
| Ortam yönetimi | Ortamlar, değişkenler |
| Test durumu oluşturma | Tek uç nokta testleri, onaylar |
| Test senaryosu yönetimi | Çok adımlı testler, içe aktarma, güncelleme |
| Test paketi organizasyonu | Gruplama, yürütme |
| İçe/dışa aktarma iş akışları | Veri taşıma, yedekleme |
| CI/CD entegrasyonu | Pipeline komutları, raporlar |
Her SKILL şunları içerir:
- Görev türü tanımlaması
- Komut dizisi rehberliği
- Alan güvenlik sınırları
- Doğrulama kontrol noktaları
- Doğrulama kalıpları
Uygulanabilir İş Akışı Özeti
Bir Ajanın test senaryosu bakımını daha güvenli yapması için temel akış şu şekilde olmalıdır:
# 1. Mevcut yapıyı içe aktar
apidog test-scenario import-steps <senaryoKimliği> --project <projeKimliği> \
--source endpoint --ids <uçNoktaKimlikleri> --sync manual
# 2. Gerçek yapıyı oku
apidog test-scenario get <senaryoKimliği> --project <projeKimliği> \
--with-case-detail
# 3. Güncelleme JSON'unu hazırla
# ./senaryo-güncellemesi.json
# 4. Güncellemeyi doğrula
apidog cli-schema validate test-scenario-update --file ./senaryo-güncellemesi.json
# 5. Güncellemeyi uygula
apidog test-scenario update <senaryoKimliği> --project <projeKimliği> \
--file ./senaryo-güncellemesi.json
# 6. Sonucu çalıştırarak kontrol et
apidog run --project <projeKimliği> --test-scenario <senaryoKimliği>
Bu akışın amacı basittir:
- Gerçek yapıyı gör
- Tahmin etme
- Yerel değişiklik yap
- Şemaya göre doğrula
- Çalıştırarak davranışı kontrol et
Sırada Ne Var?
Şimdi üç temel bileşen tamamlandı:
-
cli-schema validate— kalite kapısı -
agentHints— sonraki adım navigasyonu - SKILL — iş akışı muhakemesi
Bir sonraki soru şu:
Bu gerçekten işe yarıyor mu? Sayılar ne diyor?
- bölümde, Sayılar Yalan Söylemez: %30 Daha Az Araç Çağrısı, %25 Daha Az Token yazısında, dahili karşılaştırmalardan elde edilen nicel sonuçlar ve tasarrufların nereden geldiği ele alınacak.
Temel Çıkarımlar
- CLI yürütme gücü verir; SKILL işletim muhakemesi verir.
- SKILL bir komut referansı değil, işletim kılavuzudur.
- Gizli iş akışları açık rehberlik gerektirir.
- Adımları içe aktarma → geri okuma → yerel güncelleme akışı, elle yazmaktan daha güvenlidir.
-
--with-case-detail, tahmine dayalı güncellemeleri önler. - SKILL geliştirilebilir; Ajanlar onu değiştirebilir veya iyileştirme önerebilir.
- CLI ürün semantiğini absorbe eder, SKILL iş akışını yönlendirir.
- İsteğe bağlı yükleme, bağlam ve token yükünü azaltır.
Tek bir çalışma alanında API'ları tasarlamak, taklit etmek, test etmek ve belgelemek için Apidog'u kullanabilirsiniz. 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)