Yapay Zeka Ajanları Üretimde Neden Bozulur ve Her Arıza Modu Nasıl Test Edilir

Ajanınız demoda çalıştı: bileti okudu, üç API çağrısı yaptı ve temiz bir özet yayınladı. Üretimde ise aynı müşteriye iki kez e-posta gönderebilir, bir tekrar döngüsünde token bütçesini tüketebilir veya ön yüzünüzün işleyemeyeceği bir yük üretebilir.

Apidog'u bugün deneyin

Çalışan prototip ile güvenilir ajan arasındaki fark genellikle model değildir. Sorun çoğu zaman araç çağrılarındadır: Ajanın yaptığı her araç çağrısı; yavaşlayabilen, zaman aşımına uğrayabilen, hata döndürebilen veya beklenmeyen veri üretebilen bir HTTP isteğidir. Bu çağrıları üretim API'leri gibi test etmezseniz, tek bir kötü yanıt ajanınızı olay üretmeye yaklaştırır.

İyi haber şu: ajan güvenilirliği test edilebilir. Kullanıcıların hata yollarını keşfetmesini beklemek yerine, bu yolları kontrollü olarak simüle edebilirsiniz. Bu yazı, en yaygın beş ajan hata modunu ve bunları API sınırında nasıl test edeceğinizi açıklar. Sözleşme tasarlamak, bağımlılıkları taklit etmek ve yanıtları doğrulamak için Apidog kullanılabilir.

Ajanlar istemde değil, API sınırında başarısız olur

Ajan üretimde yanlış davrandığında ilk refleks istemi değiştirmek olur. Bu bazen işe yarar, ancak birçok hata istemden kaynaklanmaz.

Tipik akış şöyledir:

1. Model bir araç seçer.
2. Uygulamanız bu seçimi HTTP isteğine dönüştürür.
3. Harici servis yanıt döndürür.
4. Uygulamanız sonucu modele geri verir.
5. Model bu sonuca göre sonraki adımı seçer.

Bu akışın büyük kısmı klasik API entegrasyonudur. Bu nedenle güvenilirlik sorusu şudur:

Ajanın API çağrılarının başarısız olabileceği yolları test ettim mi?

Aşağıdaki beş hata modu, üretimdeki kritik sorunların çoğunu kapsar.

Hata modu 1: Sözleşmeden sapan araç çağrıları

En yaygın hata, ajanın API sözleşmesiyle uyuşmayan araç çağrısı üretmesidir.

Örneğin bir rezervasyon ajanı şunu gönderebilir:

{
  "guests": "two"
}

Oysa API şu veriyi bekliyordur:

{
  "guests": 2
}

Bu durumda API 400 Bad Request dönebilir. Daha riskli senaryoda ise API 200 OK döndürür, fakat hata bilgisi gövdede gizlidir. Ajan yanıtı başarılı kabul edip sonraki adıma geçebilir.

Uygulama adımları

Her araç için açık bir istek sözleşmesi tanımlayın:

{
  "type": "object",
  "required": ["guests", "date"],
  "properties": {
    "guests": {
      "type": "integer",
      "minimum": 1
    },
    "date": {
      "type": "string"
    }
  }
}

Test sırasında şu kontrolleri yapın:

• Zorunlu alanlar gönderiliyor mu?
• Alan türleri doğru mu?
• Enum değerleri geçerli mi?
• Araç doğru endpoint'i çağırıyor mu?
• İstek gövdesinde beklenmeyen alanlar var mı?

Ajanın araç şemalarını Apidog'a yükleyip gerçek araç çağrılarını bu tanımlara göre doğrulayabilirsiniz. Böylece sözleşme ihlali üretimde sessiz kalmak yerine testte görünür olur.

Daha ayrıntılı kurulum için şu kaynaklara bakabilirsiniz:

• Bir yapay zeka ajanının araç çağrılarını test etme
• API'lerinizi çağıran ajanları test etme

Hata modu 2: Yukarı akış hataları ve hız limitleri

Ajanın yaptığı her harici çağrı aşağıdaki sonuçlardan biriyle karşılaşabilir:

• 429 Too Many Requests
• 500 Internal Server Error
• Ağ hatası
• Zaman aşımı
• Eksik veya bozuk yanıt gövdesi

Kırılgan bir ajan ilk hatada durur ya da daha kötüsü sürekli tekrar deneyerek daha fazla hız limiti tetikler. Bu da token, API kotası ve maliyet tüketen bir döngüye dönüşebilir.

Ajan hata kurtarma modelleri hakkındaki SDK tartışmaları, bu sorunun ne kadar yaygın olduğunu gösterir.

Test senaryosu oluşturun

Canlı API'nin rastgele hata üretmesini beklemeyin. Bağımlılığı taklit edin ve kontrollü bir yanıt dizisi tanımlayın:

1. İlk çağrıda 429
2. Retry-After başlığı
3. İkinci çağrıda 500
4. Son çağrıda başarılı yanıt

Örnek yanıt:

HTTP/1.1 429 Too Many Requests
Retry-After: 5
Content-Type: application/json

{
  "error": "rate_limit_exceeded"
}

Ardından ajanınızın davranışını doğrulayın:

• Retry-After değerine uyuyor mu?
• Geri çekilme uyguluyor mu?
• Deneme sayısı sınırlı mı?
• Maksimum deneme sayısından sonra temiz şekilde duruyor mu?
• Devre kesici açılıyor mu?
• Tekrar edilen işlem yan etkisiz mi?

Özellikle e-posta gönderme, ödeme alma veya sipariş oluşturma gibi işlemler için idempotency gereklidir. Idempotency key, tekrar denemelerin çift ücret veya çift gönderim üretmesini engeller.

İlgili kaynaklar:

• Hız limiti aşıldı yanıtı ne anlama gelir?
• Yapay zeka ajan hata kurtarma

Hata modu 3: Deterministik olmayan çıktı

Sıcaklığı sıfıra ayarlasanız bile model çıktısı her zaman bayt düzeyinde aynı olmayabilir. Donanım, toplu işleme, sağlayıcı tarafı değişiklikleri ve yürütme ayrıntıları farklı sonuçlar yaratabilir.

Bu nedenle aşağıdaki gibi testler kırılgandır:

expect(agentResponse).toBe(
  "Müşterinin rezervasyonu 14 Mart için başarıyla oluşturuldu."
);

Bu test, anlam aynı kalsa bile farklı ifade biçiminde başarısız olur.

vLLM tartışmasında da tohum ve sıcaklık ayarlarının tek başına yeniden üretilebilirlik sağlamadığı ele alınıyor.

Tam metin yerine yapı doğrulayın

Aşağıdaki yaklaşımları kullanın:

• JSON şeması doğrulaması
• Zorunlu alan kontrolü
• Alan türü kontrolü
• Sayısal aralık kontrolü
• Araç adı ve endpoint doğrulaması
• Yasaklı alanların olmadığının kontrolü

Örnek:

expect(result).toMatchObject({
  status: "success",
  total: expect.any(Number)
});

expect(result.total).toBeGreaterThanOrEqual(0);
expect(result.total).toBeLessThanOrEqual(cartValue);

Bu test, modelin ifade biçimindeki doğal farklılıkları tolere ederken gerçek regresyonları yakalar.

Daha fazla bilgi:

• Kararsız testlere ne sebep olur?
• Deterministik olmayan yapay zeka ajanlarını test etme
• Ajan belleği nasıl çalışır?

Hata modu 4: Kontrolsüz maliyet

Ajanlar döngüye girer ve döngüler maliyet üretir.

Başarısız bir çağrıyı binlerce kez tekrar eden tek bir ajan:

• Token bütçesini tüketebilir.
• API kotasını doldurabilir.
• Yanıt süresini artırabilir.
• Kullanıcı deneyimini bozabilir.
• Beklenmeyen faturalara neden olabilir.

Maliyet yalnızca finansal bir metrik değildir; aynı zamanda güvenilirlik sinyalidir. Gereksiz çağrılar, fazla büyük bağlamlar ve tekrar döngüleri ajanı yavaş ve tahmin edilemez hale getirir.

Ölçmeniz gereken metrikler

Her çalıştırma için en az şunları kaydedin:

{
  "run_id": "agent-run-123",
  "tool_calls": 8,
  "retries": 3,
  "input_tokens": 4200,
  "output_tokens": 950,
  "duration_ms": 12600,
  "status": "failed"
}

Ardından sınırlar koyun:

• Görev başına maksimum araç çağrısı
• Endpoint başına maksimum tekrar sayısı
• Çalıştırma başına token bütçesi
• Maksimum yürütme süresi
• Maksimum bağlam boyutu

Bir hata kurtarma senaryosu test edilirken çağrı sayısını da doğrulayın. Görev sonunda başarılı görünen fakat bunu başarmak için kırk API çağrısı yapan bir ajan, yaklaşan maliyet sorununun işaretidir.

Komut satırı tarafındaki pratik optimizasyonlar için ajan token maliyetlerini düşürme kılavuzuna bakabilirsiniz.

Hata modu 5: Eksik güvenlik çitleri

En pahalı hatalar bazen ajanın teknik olarak doğru çalıştığı durumlarda ortaya çıkar.

Ajan şu eylemleri başarıyla gerçekleştirebilir:

• E-posta göndermek
• Sipariş oluşturmak
• Kaydı silmek
• Ödeme başlatmak
• Üretim verisini değiştirmek

Sorun, model kararı ile canlı eylem arasında kontrol olmamasıdır.

Güvenlik çiti tasarımı

Yan etkili araçları sınıflandırın:

Araç türü	Örnek	Önerilen kontrol
Salt okunur	Sipariş sorgulama	Doğrudan izin
Düşük riskli yazma	Taslak oluşturma	Kayıt ve sınırlandırma
Yüksek riskli yazma	E-posta gönderme	İnsan onayı
Geri döndürülemez	Ödeme alma, silme	Zorunlu onay ve ek doğrulama

Ayrıca ajana bir deneme modu ekleyin. Bu modda ajan eylemi gerçekleştirmek yerine niyetini döndürür:

{
  "action": "send_email",
  "recipient": "[e-mail]",
  "requires_approval": true,
  "reason": "Rezervasyon değişikliği hakkında bilgilendirme"
}

Test edilmesi gerekenler

Yan etkili endpoint'i taklit edin ve şu davranışları doğrulayın:

• Ajan doğrudan canlı eylem yapmıyor mu?
• Onay akışını tetikliyor mu?
• Yetkisiz araç çağrısı engelleniyor mu?
• Deneme modu gerçekten yan etki üretmiyor mu?
• İzin listesi dışındaki araçlar reddediliyor mu?

OWASP Top 10 for LLM Applications, korunması gereken riskler için iyi bir başlangıç kontrol listesidir.

Ayrıntılı uygulama için yapay zeka ajan güvenlik çitleri rehberini inceleyebilirsiniz.

Bir ajan testi nasıl yapılandırılır?

Bu beş hata modu için tekrar kullanılabilir bir test döngüsü kurabilirsiniz.

1. Araç sözleşmelerini tanımlayın

Ajanın çağırabileceği her endpoint için şunları belgelendirin:

• HTTP metodu
• URL ve path parametreleri
• İstek gövdesi şeması
• Başarılı yanıt şeması
• Hata yanıtları
• Kimlik doğrulama gereksinimleri
• İdempotency davranışı

2. Bağımlılıkları taklit edin

Canlı servisler yerine kontrollü taklitler kullanın. Böylece şunları simüle edebilirsiniz:

• 429 hız limiti
• 500 sunucu hatası
• Zaman aşımı
• Eksik JSON alanları
• Bozuk JSON
• Beklenmeyen içerik türü
• Gecikmeli yanıtlar

3. Negatif senaryoları çalıştırın

Mutlu yol tek başına yeterli değildir. Her araç için en az şu senaryoları ekleyin:

Başarılı yanıt
429 + Retry-After
500 + tekrar denemesi
Zaman aşımı
Geçersiz yanıt gövdesi
Sözleşmeye aykırı araç çağrısı
İnsan onayı gerektiren eylem

4. Davranışı doğrulayın

Her senaryoda şunları ölçün:

• Gönderilen isteğin şekli
• Araç çağrısı sayısı
• Tekrar denemesi sayısı
• Geri çekilme davranışı
• Token kullanımı
• Son durum
• Güvenlik çitinin devreye girip girmediği
• Yan etkinin gerçekleşip gerçekleşmediği

Bir araçla başlayın ve test kapsamını kademeli olarak genişletin. İlk kez bozuk bir araç çağrısını kullanıcıdan önce yakaladığınızda bu kurulum maliyetini karşılar.

Ajan güvenilirlik kontrol listesi

Ajanı üretime almadan önce aşağıdaki maddeleri gözden geçirin:

• [ ] Her araç çağrısı bir şemaya göre doğrulanıyor.
• [ ] Sözleşme ihlalleri testi başarısız kılıyor.
• [ ] 429, 500 ve zaman aşımı yanıtları simüle ediliyor.
• [ ] Ajan geri çekilme ve sınırlı tekrar denemesi uyguluyor.
• [ ] Tekrarlanan eylemler idempotent çalışıyor.
• [ ] Testler tam metin yerine yapı ve anlam doğruluyor.
• [ ] Her çalıştırmadaki token kullanımı ölçülüyor.
• [ ] Araç çağrısı ve token bütçeleri sınırlanıyor.
• [ ] Yıkıcı eylemler izin listesi veya insan onayı gerektiriyor.
• [ ] Güvenlik çiti akışı taklitlerle test ediliyor.

Bu maddelerin tamamı işaretlendiyse, ajanların üretimde bozulduğu en yaygın yolları kapsarsınız.

Apidog'un yeri nedir?

Apidog bir ajan çerçevesi, model barındırma platformu veya değerlendirme altyapısı değildir. Ajanınızı oluşturmaz ya da çalıştırmaz.

Bunun yerine ajanın bağımlı olduğu API katmanında çalışır:

1. Araç sözleşmelerini tasarlamanıza ve saklamanıza yardımcı olur.
2. Giden istekleri bu sözleşmelere göre doğrulamanızı sağlar.
3. API bağımlılıklarını taklit etmenizi sağlar.
4. 429, 500, zaman aşımı veya hatalı gövde gibi hata senaryolarını programlamanıza yardımcı olur.
5. Şema, zorunlu alan, veri türü ve aralık tabanlı doğrulamalar yazmanızı sağlar.

Kısacası, Apidog ajanın çağırdığı API'leri test etmek, hata senaryolarını taklit etmek ve dönen veriyi doğrulamak için kullanılır.

Daha geniş QA perspektifi için ajanik yapay zeka testi genel bakışını inceleyebilirsiniz.

Sıkça sorulan sorular

Ajan güvenilirliği model sorunu mu, mühendislik sorunu mu?

Çoğunlukla mühendislik sorunudur. Model seçimi önemlidir; ancak kötü araç çağrıları, ele alınmayan hız limitleri, tekrar döngüleri ve eksik güvenlik çitleri model değiştirmeden çözülebilecek entegrasyon ve test problemleridir.

Ajanı gerçek API'lere istek atmadan test edebilir miyim?

Evet. Hatta hata kurtarma ve güvenlik çiti senaryoları için bunu yapmalısınız. Bağımlılıkları taklit ederek hata yanıtlarını zorlayabilir, zamanlamayı kontrol edebilir ve gerçek yan etkilerden kaçınabilirsiniz.

Çıktı her çalıştırmada değişiyorsa nasıl test yazmalıyım?

Tam metin eşitliği kullanmayın. Bunun yerine şema, zorunlu alan, araç çağrısı şekli, sayısal aralık ve beklenen eylem gibi yapısal özellikleri doğrulayın. Deterministik olmayan yapay zeka ajanlarını test etme rehberi bu yaklaşımı ayrıntılı olarak açıklar.

Önce hangi alanı test etmeliyim?

Önce yıkıcı eylemler üzerindeki güvenlik çitlerini, ardından hata kurtarma akışlarını test edin. Bu iki alan sizi en maliyetli sorunlardan korur: zararlı eylem gerçekleştiren ajanlar ve bütçeyi tüketen tekrar döngüleri.

Tek bir hata moduyla başlayın

Beş hata modunun tamamını aynı anda ele almak zorunda değilsiniz. En yüksek riskli alanı seçin:

• E-posta veya ödeme gibi yan etkili araçlar varsa güvenlik çitleriyle başlayın.
• Harici servis bağımlılığı yoğunsa 429, 500 ve zaman aşımı kurtarma akışlarıyla başlayın.
• Araç çağrıları sık başarısız oluyorsa sözleşme doğrulamasını önceleyin.

Bu hafta tek bir bağımlılık için taklit oluşturun, hatayı programlayın ve ajanı çalıştırın. Simüle edilmiş bir 429 yanıtında ajanın bütçeyi tüketen bir döngü yerine kontrollü geri çekilme yaptığını görmek, yeşil demodan daha güçlü bir güvenilirlik sinyalidir.

Ajanınızın bağımlı olduğu API'ler için sözleşme tasarlamak, hata senaryolarını taklit etmek ve yanıt doğrulaması yapmak için Apidog'u indirin.