Yapay Zeka Ajanları İçin API Hata Tasarımı: Kurtarılabilir Hatalar

Yapay Zeka Ajanlarının Kurtarabileceği API Hataları Tasarlayın

API'niz 400 Bad Request ve {"error": "invalid input"} döndürdüğünde, bir insan dokümanları açıp eksik alanı bulabilir. Bir ajan ise üzerinde işlem yapabileceği veri olmadığı için aynı isteği yeniden gönderebilir, sonra vazgeçip API'nin bozuk olduğunu bildirebilir.

Apidog'u bugün deneyin

İyi bir hata yanıtı üç soruyu açıkça yanıtlamalıdır:

1. Hata istemcide mi, sunucuda mı?
   
   4xx, istek değişmeden tekrarlandığında yine başarısız olur. 5xx, geçici bir sunucu sorununa işaret edebilir.

2. Yeniden denemeli mi, ne zaman?
   
   429 bekledikten sonra tekrar denenebilir; 422, istek düzeltilmeden denenmemelidir.

3. Tam olarak ne değişmeli?
   
   “Doğrulama başarısız” yerine, “country US ise customer.postal_code zorunludur” deyin.

Ajan hata kurtarma istemci tarafındaki yeniden deneme, geri çekilme ve devre kesici stratejilerini kapsar. Bu yazı ise API'nin ajanın hareket edebilmesi için döndürmesi gereken bilgileri ele alır.

Yapılandırılmış hata biçimi kullanın

Yeni bir format icat etmeyin. RFC 9457, HTTP API'leri için standart bir Sorun Detayları biçimi sunar:

{
  "type": "https://api.example.com/errors/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "The field 'customer.postal_code' is required when 'country' is 'US'.",
  "instance": "/v1/orders",
  "errors": [
    {
      "field": "customer.postal_code",
      "code": "required_conditional",
      "message": "Required when country is US. Provide a 5-digit or 9-digit US postal code.",
      "example": "94107"
    }
  ],
  "retryable": false,
  "next_action": "Add customer.postal_code to the request body and send again."
}

Bu biçimdeki kritik alanlar şunlardır:

• detail: Başarısız olan gerçek alanı ve kuralı açıklayın.
• errors: Her sorunu alan yolu, sabit kod ve öneriyle birlikte aynı yanıtta döndürün.
• retryable: Durum kodundan çıkarım yaptırmayın; açık bir boolean gönderin.
• next_action: Ajana bir sonraki adımı doğrudan söyleyin.

Google'ın API hata tasarım kılavuzu da hata ayrıntılarının düz metin yerine yapılandırılmış veri olarak verilmesini önerir.

Geçici hatalarda bekleme süresini bildirin

Geçici bir hata için ajanın ne kadar beklemesi gerektiğini belirtin. Retry-After başlığını kullanın ve değeri gövdede de tekrarlayın:

HTTP/1.1 429 Too Many Requests
Retry-After: 30
Content-Type: application/problem+json

{
  "type": "https://api.example.com/errors/rate-limited",
  "title": "Rate limit exceeded",
  "status": 429,
  "detail": "You have used 1000 of 1000 requests in the current minute window.",
  "retryable": true,
  "retry_after_seconds": 30,
  "next_action": "Wait 30 seconds before sending this request again. Do not retry sooner."
}

Retry-After saniye veya HTTP tarihi kabul eder; saniye biçimi ajanlar için daha pratiktir. Aynı yaklaşımı bakım sırasındaki 503 ve kilitli kaynaklardaki 409 için de uygulayın.

Daha fazlası için:

• Oran sınırı aşıldı kılavuzu
• API oran sınırlamasını uygulama

İç ayrıntıları sızdırmayın; boş hata da döndürmeyin

İki anti-desen vardır:

• Yığın izlemesi döndürmek: Çerçeve sürümlerini, dosya yollarını, sorguları ve hassas ayrıntıları açığa çıkarabilir.
• Boş hata döndürmek: Gövdesiz 500 veya {"error": true} ajana hiçbir eylem seçeneği bırakmaz.

Bunun yerine, korelasyon kimliği içeren kararlı ve güvenli bir hata döndürün:

{
  "type": "https://api.example.com/errors/internal",
  "title": "Internal error",
  "status": 500,
  "detail": "The order could not be created due to an internal error. No order was created.",
  "retryable": true,
  "retry_after_seconds": 5,
  "request_id": "req_01J8ZK3M2Q",
  "next_action": "Retry once after 5 seconds. If it fails again, stop and report request_id req_01J8ZK3M2Q."
}

"No order was created" bilgisi özellikle önemlidir. Ajana, yeniden denemenin yinelenen kayıt oluşturma riski taşıyıp taşımadığını söylemiş olursunuz. Bunu garanti edemiyorsanız işlemi eşdeğer yapın; bunun için yapay zeka ajanları için eşdeğerlik anahtarları desenini kullanın.

request_id, destek veya hata ayıklama sırasında günlüklerde doğrudan ilgili kayda ulaşmanızı sağlar. Bunu API gözlemlenebilirliği uygulamalarıyla birlikte kullanın.

Güvenilmeyen girişlere karşı API'leri test etme rehberi, kullanıcı girdisini hata mesajlarına yansıtmanın güvenlik risklerini ayrıntılandırır.

Hataları OpenAPI spesifikasyonunda tanımlayın

Hata yanıtı OpenAPI belgenizde yer almıyorsa, oluşturulmuş istemciler, sahte sunucular ve ajan araçları onu tanımaz.

responses:
  '201':
    description: Order created
    content:
      application/json:
        schema: { $ref: '#/components/schemas/Order' }
  '422':
    description: >
      Validation failed. Not retryable without changing the request body.
      The errors array names each invalid field.
    content:
      application/problem+json:
        schema: { $ref: '#/components/schemas/Problem' }
  '429':
    description: >
      Rate limited. Retryable. Wait for retry_after_seconds before sending again.
    content:
      application/problem+json:
        schema: { $ref: '#/components/schemas/Problem' }

Açıklamalar dekorasyon değildir. OpenAPI spesifikasyonunu ajan araçlarına dönüştürürken, model hata durumunu bu açıklamalardan öğrenir. “Yeniden denenebilir; önce bekle” açıklaması, yalnızca “Too Many Requests” ifadesinden daha iyi davranış üretir.

Başarıları değil, hata yollarını da test edin

Hata senaryolarını Apidog içinde uç noktaya ekleyin ve sahte yanıtlar olarak kaydedin. Böylece gerçek sistemleri bozmadan ajanın 422, 429 ve 500 davranışlarını test edebilirsiniz.

CI'da çalıştırılacak temel senaryolar:

• Birden fazla doğrulama hatası: Tüm alan sorunlarının tek yanıtta döndüğünü doğrulayın.
• Oran sınırı: Ajanın retry_after_seconds kadar beklediğini doğrulayın.
• Yazma işleminde sunucu hatası: Yeniden denemenin yinelenen kayıt üretmediğini doğrulayın.
• Kimlik doğrulama hatası: Ajanın beklemek yerine durduğunu doğrulayın.
• Bozuk hata gövdesi: Geçerli JSON olmayan yanıt karşısında ajanın kontrollü biçimde başarısız olduğunu doğrulayın.

Ajanları üretim yerine sahte API'lere karşı çalıştırma yaklaşımı, bu testlerin neden üretim erişiminden daha güvenli olduğunu açıklar. Kimlik doğrulama tarafı için ajanlarda en az ayrıcalıklı API anahtarları rehberini uygulayın.

Ajana düz metin ayrıştırmayın

Şu yanıt ajanın tahmin yürütmesine neden olur:

{ "message": "Sorry, that didn't work. Please check your details and try again." }

Her başarısızlık için sabit, makine tarafından okunabilir bir kod verin:

{
  "code": "insufficient_funds",
  "retryable": false,
  "next_action": "Use a payment method with sufficient available balance."
}

Ayrıca, başarısızlığı asla 200 OK ile dönmeyin. Hata içeren bir 200, yeniden deneme politikaları, metrikler ve uyarılar için görünmezdir.

Eskalasyonu da tasarlayın

Bazı sorunlar ajan tarafından çözülemez: eksik yetki, kapatılmış hesap veya insan kararı gerektiren kural. Bu durumda hata:

• Ne olduğunu,
• Bir insanın ne yapması gerektiğini,
• Günlüklerde aranabilecek request_id değerini

açıkça içermelidir.

Örneğin Sharkly, ajan sonuçlarını ve yürütme izlerini Görev üzerinde tutarak insan incelemesi gereken işleri Gelen Kutusu'na yönlendirir. Ancak bu devir ancak hata metni somut ve uygulanabilir olduğunda faydalıdır.

Kontrol listesi

• Her uç noktada tek ve tutarlı bir hata biçimi kullanın.
• detail içinde kategori değil, gerçek alan veya koşulu belirtin.
• Doğrulama hatalarında tüm sorunları alan yollarıyla birlikte tek yanıtta döndürün.
• Her hatada retryable boolean alanını gönderin.
• Yeniden denenebilir hatalarda başlıkta ve gövdede bekleme süresini verin.
• Yazma işlemlerinde verinin oluşturulup oluşturulmadığını veya değişip değişmediğini belirtin.
• Her hataya günlüklerde çözümlenen bir korelasyon kimliği ekleyin.
• Yığın izleri, SQL sorguları ve çerçeve ayrıntıları döndürmeyin.
• Hata yanıtlarını OpenAPI spesifikasyonunda belgeleyin.
• Her hata için sahte yanıt ve CI senaryosu oluşturun.

Sıkça sorulan sorular

RFC 9457 mi, özel hata biçimi mi?

Üretimde tutarlı bir biçiminiz yoksa RFC 9457 kullanın. Tutarlılık, standardizasyondan daha önemlidir. Mevcut biçiminizi kullanıyorsanız retryable ve next_action uzantılarını ekleyin.

next_action alanı güvenli mi?

Evet; yalnızca sunucunun sabit şablonlardan ürettiği metni kullanırsanız. Kullanıcı tarafından sağlanan içeriği bu alana yansıtmayın; ajan bunu talimat olarak yorumlayabilir.

Doğrulama hataları için 400 mü, 422 mi?

Bozuk JSON gibi ayrıştırılamayan isteklerde 400, ayrıştırılabilir ancak iş kurallarına uymayan isteklerde 422 kullanın. Tek bir kod kullanıyorsanız davranışı açıkça belgeleyin.

Ne kadar ayrıntı yeterlidir?

Alan adı, kural ve örnek değer genellikle yeterlidir. Dahili tanımlayıcılar, sorgu metni ve yığın çerçeveleri gereksizdir.

Hata mesajları bağlam penceresine dahil edilir mi?

Evet. Hata mesajlarını birkaç yüz jetonun altında tutun; ayrıntılı hata yanıtları yeniden denemelerde hızla birikir. Ajanlar için API yanıtlarını kırpma ilkeleri hata yanıtları için de geçerlidir.

Ajanın yeniden denenemeyen hatayı tekrar denemesini nasıl engellerim?

retryable: false gönderin, next_action içinde durmasını söyleyin ve bunu araç sarmalayıcısında da uygulayın. Modelin muhakemesi tek koruma katmanı olmamalıdır.

Hatalar bir arayüzdür. Onları hem insan geliştiricilerin hem de yanıt gövdenizdeki talimatlarla hareket eden ajanların kullanacağı şekilde tasarlayın. Hata biçimlerini tanımlamak, sahtelerini oluşturmak ve CI'da test etmek için Apidog'u indirin.