DEV Community

Cover image for CI/CD Uyumluluğu Ajan Araçları İçin Neden Olmazsa Olmazdır
Tobias Hoffmann
Tobias Hoffmann

Posted on • Originally published at apidog.com

CI/CD Uyumluluğu Ajan Araçları İçin Neden Olmazsa Olmazdır

Bu yazı, Apidog'un API testi ve API yaşam döngüsü yönetimi için geliştirdiği komut satırı aracı olan Apidog CLI'ı anlattığımız 10 bölümlük serinin bir parçasıdır. Sırayla okuyabilir veya ihtiyacınız olan bölüme doğrudan geçebilirsiniz:

Apidog'u bugün deneyin

Başlık Odak
1 126 MCP Aracı İnşa Ettik. Ancak 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ç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 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 Tam Bir Ajan İş Akışı Pratik eğitim
8 CI/CD Uyumluluğu Neden Ajan Araçları İçin Tartışılmazdır? DevOps bakış açısı
9 AI Branch: AI Ajanları ile Daha Güvenli Proje Değişiklikleri Güvenlik katmanı
10 Önce Şartname Dündü. Yetenek Odaklıya Hoş Geldiniz. Vizyon ve gelecek

Ajan dostu bir CLI tasarlamak, önce CI/CD dostu bir CLI tasarlamayı gerektirir. Bu yazıda apidog run komutunun hem CI işlem hatlarına hem de Yapay Zeka Ajanlarına nasıl hizmet ettiğini pratik örneklerle ele alacağız.

İkili Kitle: CI/CD ve Yapay Zeka Ajanları

Ajan araçları geliştirirken yalnızca sohbet deneyimine odaklanmak kolaydır. Ancak Apidog CLI'ın temel hedeflerinden biri hâlâ değişmez: CI/CD işlem hatlarıyla uyumlu çalışmak.

Orijinal Kitle Yeni Kitle
CI/CD işlem hatları Yapay Zeka Ajanları
Harici planlama sistemleri Sohbet tabanlı iş akışları
Betikler ve otomasyon Kullanıcı odaklı görevler

Birçok ekip Apidog'u işlem hatlarında şu amaçlarla kullanır:

  • API otomatik testlerini çalıştırmak
  • Test raporları üretmek
  • Kalite geçitlerini uygulamak
  • Dağıtım öncesi API davranışını doğrulamak

Bu kullanım senaryosu CLI'dan net beklentiler doğurur:

Gereksinim Neden Önemli
Kararlı çıktı Betikler çıktıyı öngörülebilir şekilde ayrıştırır
Betiklenebilir komutlar Otomatik yürütme için gerekir
Açık çıkış kodları İşlem hattı geçme/kalma kararını verir
Yapılandırılabilir parametreler Ortama özel çalıştırmalar sağlar

Kural basit: Ajan desteği eklerken mevcut otomasyon davranışı bozulmamalıdır.

Ana İlke

Ajan dostluğu, CI/CD dostluğunun üzerine inşa edilmelidir.

Yalnızca Yapay Zeka Ajanlarının kullanabileceği ayrı bir protokol icat etmek yerine, mühendislik sistemlerinde zaten çalışan CLI davranışının üzerine yapılandırılmış çıktı, şema doğrulama ve sonraki adım rehberliği eklemek daha sürdürülebilir bir yaklaşımdır.

İyi tasarlanmış bir CLI, aynı anda şu tüketicilere hizmet edebilmelidir:

Tüketici İhtiyaçları
İnsanlar Okunabilir çıktı, yardım metni, etkileşimli özellikler
Betikler Kararlı stdout/stderr, betiklenebilir komutlar
CI işlem hatları Çıkış kodları, rapor dosyaları, yapılandırılabilir çalıştırmalar
Yapay Zeka Ajanları Yapılandırılmış sonuçlar, doğrulama, sonraki adım rehberliği

apidog run: Temel Komut

CI, betik, insan kullanıcı ve Ajan için temel çalışma komutu aynıdır:

apidog run --project <projectId> \
  --test-scenario <scenarioId> \
  --environment <environmentId> \
  -r "cli,html,junit" \
  --out-dir ./apidog-reports
Enter fullscreen mode Exit fullscreen mode

Bu komut şunları sağlar:

  • CLI çıktısı: İnsanlar ve betikler için
  • HTML raporu: Manuel inceleme için
  • JUnit raporu: CI test raporu yayınlama için
  • Çıkış kodu: İşlem hattı kararları için
  • Yapılandırılmış sonuçlar: Ajanların yorumlaması için

CI/CD Ne Bekler?

CI sistemleri konuşma tabanlı açıklamalara değil, deterministik sinyallere ihtiyaç duyar.

CI Gereksinimi CLI Karşılığı
Çıkış kodları Başarı için 0, başarısızlık için 1
Rapor dosyaları --out-dir altında HTML, JUnit, JSON formatları
Kararlı parametreler Sürümler arasında tutarlı seçenekler
Yapılandırılabilir çalıştırmalar İterasyonlar (-n), gecikmeler (--delay-request), ortamlar (-e)

GitHub Actions örneği 

# GitHub Actions
- name: API Testlerini Çalıştır
  run: |
    apidog run --project $PROJECT_ID \
      --test-scenario $SCENARIO_ID \
      --environment $ENV_ID \
      -r "junit" \
      --out-dir ./reports
  env:
    PROJECT_ID: ${{ secrets.APIDOG_PROJECT_ID }}
    SCENARIO_ID: ${{ secrets.APIDOG_SCENARIO_ID }}
    ENV_ID: production

- name: Test Raporunu Yayınla
  uses: mikepenz/action-junit-report@v3
  with:
    report_paths: './reports/junit.xml'
Enter fullscreen mode Exit fullscreen mode

Bu akışta CI sistemi şu sırayı izler:

  1. apidog run komutunu çalıştırır.
  2. Çıkış kodunu okur.
  3. Başarılıysa işlem hattını devam ettirir.
  4. Başarısızsa işlem hattını durdurur.
  5. JUnit raporunu yayınlar.

Bu davranışın kararlı olması, Ajan entegrasyonlarından bağımsız olarak kritik önemdedir.

Ajanlar Ne Bekler?

Yapay Zeka Ajanları için yalnızca geçme/kalma bilgisi yeterli değildir. Ajanın hatayı anlayabilmesi ve bir sonraki eylemi seçebilmesi gerekir.

Ajan Gereksinimi CLI Karşılığı
Yapılandırılmış sonuçlar data nesnesi ile JSON çıktı
Başarısızlık nedenleri error nesnesinde belirli hata detayları
Sonraki adım önerileri agentHints.nextSteps
Doğrulama Yazmadan önce cli-schema validate

Ajanın tüketebileceği örnek çıktı 

{
  "success": true,
  "stats": {
    "total": 10,
    "passed": 8,
    "failed": 2
  },
  "failures": [
    {
      "step": "Ödeme işleme",
      "error": "Onay başarısız: durum != 'başarılı'",
      "response": {}
    }
  ],
  "agentHints": {
    "summary": "2 test başarısız oldu. Hata detaylarını inceleyin.",
    "nextSteps": [
      "Ödeme işleme adımındaki hatayı ayıklayın.",
      "Onayı kontrol edin: beklenen durum 'başarılı'.",
      "Düzeltmeden sonra test durumunu veya uç noktayı güncelleyin."
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode

Ajan bu çıktıyı şu şekilde kullanır:

  1. JSON çıktısını ayrıştırır.
  2. success, stats ve failures alanlarını değerlendirir.
  3. Hangi test adımının başarısız olduğunu belirler.
  4. agentHints.nextSteps içindeki önerileri takip eder.
  5. Gerekirse test senaryosunu veya API uç noktasını düzeltir.
  6. apidog run ile yeniden doğrulama yapar.

Aynı Komut, Farklı Tüketiciler

Aynı apidog run komutu farklı sistemler tarafından farklı sinyaller için kullanılabilir:

apidog run --project <projectId> --out-dir ./apidog-reports
Enter fullscreen mode Exit fullscreen mode
Tüketici Çıkardığı Bilgi
CI işlem hattı Çıkış kodu, rapor dosya konumu
Ajan JSON çıktısı, agentHints, hata detayları
İnsan Konsol çıktısı, HTML rapor bağlantısı
Betik stdout/stderr, yapılandırılabilir format

Bu yaklaşım, araç yüzeyini büyütmeden birden fazla kullanım senaryosunu destekler.

Entegrasyon Noktaları

Apidog CLI aynı temel komut üzerinden farklı CI/CD sistemlerine bağlanabilir:

CI Aracı Entegrasyon Biçimi
Jenkins İşlem hattı adımları, rapor yayınlama
GitLab CI YAML yapılandırması, yapıtlar
GitHub Actions İş akışı adımları, gizli yönetimi
CircleCI Orbs, iş akışı yapılandırması
Azure DevOps İşlem hattı görevleri, test sonuçları

Temel model değişmez:

apidog run \
  --project <projectId> \
  --test-scenario <scenarioId> \
  --environment <environmentId> \
  -r "junit,html" \
  --out-dir ./apidog-reports
Enter fullscreen mode Exit fullscreen mode

CI aracı yalnızca bu komutu ne zaman çalıştıracağını, hangi ortam değişkenlerini sağlayacağını ve raporları nereye yükleyeceğini belirler.

Kalite Geçidi ve Ajan Doğrulaması

apidog run iki farklı bağlamda kullanılabilir:

Kullanım Durumu Anlamı
CI kalite geçidi İşlem hattının devam edip etmeyeceğini belirler
Ajan doğrulaması Ajanın yaptığı değişiklikten sonra doğruluğu teyit eder
Bağlam Ne Zaman Kullanılır Amaç
CI Kod gönderildikten sonra Hatalı kodun dağıtılmasını önlemek
Ajan Test veya API değişikliği üretildikten sonra Ajanın çalışmasının doğru olduğunu doğrulamak

Pratikte aynı komut iki rol üstlenir:

apidog run --project <projectId> \
  --test-scenario <scenarioId> \
  --environment <environmentId> \
  -r "cli,html,junit" \
  --out-dir ./apidog-reports
Enter fullscreen mode Exit fullscreen mode

CI için bu bir kalite geçididir. Ajan için ise geri bildirim döngüsüdür.

Mimari Katmanlama

Bu seride ele aldığımız cli-schema, agentHints ve SKILL gibi özellikler, mevcut CLI temelinin üzerine eklenir:

┌─────────────────────────────────────────┐
│          Ajan Özellikleri               │
│  (cli-schema, agentHints, SKILL)        │
├─────────────────────────────────────────┤
│          CI/CD Temeli                   │
│  (apidog run, çıkış kodları, raporlar)  │
├─────────────────────────────────────────┤
│          Çekirdek CLI                   │
│  (komutlar, parametreler, yürütme)      │
└─────────────────────────────────────────┘
Enter fullscreen mode Exit fullscreen mode

Buradaki önemli ayrım şudur:

Ajan özellikleri, CI özelliklerinin yerini almaz. Onları genişletir.

Bu sayede:

  • Mevcut CI/CD otomasyonları çalışmaya devam eder.
  • İnsan kullanıcılar aynı CLI komutlarını kullanır.
  • Betikler kararlı çıktıya güvenebilir.
  • Ajanlar yapılandırılmış sonuçları tüketebilir.

Uygulama İçin Kontrol Listesi

Ajan dostu bir CLI tasarlarken şu noktaları kontrol edin:

  • [ ] Komutlar CI/CD içinde etkileşimsiz çalışabiliyor mu?
  • [ ] Başarı ve başarısızlık için açık çıkış kodları var mı?
  • [ ] Raporlar dosya olarak üretilebiliyor mu?
  • [ ] Ortam, senaryo ve çıktı formatı parametrelerle kontrol edilebiliyor mu?
  • [ ] JSON gibi yapılandırılmış çıktı destekleniyor mu?
  • [ ] Hatalar makine tarafından ayrıştırılabilir alanlarda veriliyor mu?
  • [ ] Ajan için sonraki adım önerileri sağlanıyor mu?
  • [ ] Şema doğrulamasıyla hatalı çıktı önleniyor mu?

Bu listeyi sağlamadan yalnızca Ajan odaklı bir arayüz eklemek, otomasyon güvenilirliğini zayıflatabilir.

Sırada Ne Var?

Sorun tespitinden pratik iş akışlarına ve temel ilkelere kadar tüm resmi ele aldık. Şimdi kritik bir konu daha var: güvenlik.

Ajanlar proje kaynaklarını değiştirdiğinde, ana dalı doğrudan etkilemelerini nasıl önlersiniz?

  1. Bölüm'de, AI Branch: AI Ajanları ile Daha Güvenli Proje Değişiklikleri, AI Branch'ın izole bir düzenleme ortamı sağlamasını inceleyeceğiz. Bu yaklaşımda değişiklikler insan incelemesine kadar ayrı bir dalda kalır ve Ajan odaklı değişiklikler için ek bir güvenlik katmanı oluşturur.

Temel Çıkarımlar

  • CI/CD uyumluluğu temel gereksinimdir, isteğe bağlı değildir.
  • Ajan dostluğu, CI dostluğunun üzerine inşa edilmelidir.
  • Aynı komut (apidog run) CI'ye, Ajanlara, insanlara ve betiklere hizmet edebilir.
  • CI ihtiyaçları: çıkış kodları, raporlar, kararlı parametreler.
  • Ajan ihtiyaçları: yapılandırılmış çıktı, hata detayları, sonraki adımlar.
  • Kalite geçidi ve Ajan doğrulaması aynı CLI temeliyle uygulanabilir.

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 AI Ajanı iş akışları için Apidog CLI hakkında daha fazla bilgi edinin.

Top comments (0)