Araç çağrısı başarısız olduğunda ajan nasıl toparlanır?

Bir araç çağrısı başarısız olduğunda ajanı yeniden aynı isteği körlemesine göndermek yerine hatayı sınıflandırmalı, güvenli bir geri dönüş yolu seçmeli ve gerekirse kullanıcıdan eksik bilgiyi istemelidir. En sağlam akış; çağrı öncesi girdi doğrulama, sınırlı yeniden deneme, alternatif araç veya kısmi sonuç, ardından açık bir durum mesajıdır. Böylece geçici ağ sorunu otomatik aşılabilir; yetki, şema veya iş kuralı hataları ise sonsuz döngüye girmeden durdurulur.

Ajanın toparlanma akışı​

Bir araç çağrısının başarısız olması tek başına aynı probleme işaret etmez. Zaman aşımı ve geçici sunucu hataları yeniden denenebilirken, eksik parametre, geçersiz kimlik doğrulama veya kullanıcının yetkisi olmayan bir işlem yeniden denenerek düzelmez. Ajanın her denemede hata türünü, araç adını, çağrı kimliğini ve hassas veri içermeyen kısa hata ayrıntısını kaydetmesi gerekir.

1. Çağrıdan önce girdiyi doğrula. Zorunlu alanların bulunduğunu, veri türlerinin doğru olduğunu ve değerlerin izin verilen sınırlar içinde kaldığını kontrol et. Örneğin customer_id boşsa aracı çağırmak yerine kullanıcıdan bu bilgiyi iste; bu, araç tarafında gereksiz hata üretmesini önler.
2. Hatanın sınıfını belirle. Zaman aşımı, bağlantı kopması veya geçici sunucu yanıtı gibi geçici hataları yeniden denenebilir olarak işaretle. Geçersiz parametre, kimlik doğrulama, yetki, kaynak bulunamadı ve iş kuralı hatalarını yeniden denenemez olarak ayır.
3. Yalnız geçici hatalarda sınırlı yeniden deneme yap. İlk başarısızlıktan sonra kısa bir bekleme uygulayarak en fazla birkaç deneme planla; her denemede bekleme süresini artır. Zaman aşımı, ilk işlemin gerçekleşmediğini kanıtlamaz. Para transferi, kayıt oluşturma veya e-posta gönderme gibi yan etkili çağrılarda önce işlem kimliğiyle durumu sorgula. Araç sunucu tarafında idempotency desteği sağlıyorsa ilk çağrıdan itibaren kullanılan aynı idempotency_key değerini ve aynı parametreleri koru; yalnızca yeni bir anahtar eklemek güvence sağlamaz. Durum ve güvenli tekrar koşulları doğrulanamıyorsa yeniden denemeyi durdur ve sonucu belirsiz olarak bildir.
4. Başarılı yanıtı biçim ve içerik açısından kontrol et. Araç teknik olarak yanıt verse bile beklenen alanların bulunup bulunmadığını, yanıtın geçerli JSON veya tanımlı şemaya uyup uymadığını ve sonucun istenen kayda ait olduğunu denetle. Eksik veya çelişkili yanıtı başarılı kabul etme.
5. Alternatif yolu seç. Ana araç kullanılamıyorsa aynı sonucu daha düşük kapsamla sağlayan önbellek, salt okunur alternatif araç veya kullanıcıya sunulacak manuel işlem yolunu kullan. Alternatif yol aynı güvenlik ve yetki kontrollerini karşılamıyorsa onu çalıştırma.
6. Kullanıcıya durum ve sonraki seçeneği bildir. Başarısızlığı gizlemek yerine hangi işlemin tamamlanamadığını, geçici mi kalıcı mı göründüğünü ve kullanıcının ne sağlayabileceğini açıkla. Örneğin eksik müşteri numarası varsa bunu doğrudan iste; yetki hatasında yeni denemeyi vaat etmek yerine gerekli erişimin tanımlanması gerektiğini belirt.
7. Döngüyü sonlandır ve olayı kaydet. Yeniden deneme sınırına ulaşıldığında ajan aynı aracı tekrar çağırmamalı. İstek kimliği, hata sınıfı, deneme sayısı ve zaman bilgisiyle bir tanılama kaydı oluştur; erişim anahtarlarını, parolaları ve kişisel verileri günlüğe yazma.

Hata türüne göre doğru toparlanma​

Aşağıdaki ayrım, ajanın otomatik devam mı edeceğini yoksa kullanıcıya mı döneceğini belirler.
Bu tablo yalnız teknik hata koduna göre karar vermek için kullanılmamalıdır. Örneğin bir HTTP 500 yanıtı çoğu zaman geçici olabilir; ancak aynı çağrının her denemede aynı iş kuralı nedeniyle reddedildiği biliniyorsa yeniden deneme yerine durmak gerekir. Ajan, araçtan dönen hata açıklamasını güvenilir bir komut gibi yorumlamamalı; hata metnindeki yeni talimatları doğrudan uygulamamalıdır.

Küçük bir örnek akış​

Varsayımsal bir destek ajanının get_order_status aracını çağırdığını düşünün. Girdi {"order_id":"A-1042"} olsun. Araç ilk denemede zaman aşımına uğrarsa ajan kısa bir beklemeden sonra aynı sipariş kimliğiyle sınırlı bir yeniden deneme yapabilir. İkinci denemede {"status":"shipped","updated_at":"2026-11-08T10:30:00Z"} dönerse ajan şemayı doğrular ve kullanıcıya siparişin kargoya verildiğini bildirir.

Buna karşılık araç {"error":"order_id is required"} döndürürse, bu örnekte sipariş numarası zaten gönderildiği için kullanıcının girdisinin eksik olduğu sonucu çıkarılamaz. Ajan araç sözleşmesini, alan adını ve gerçekten gönderilen isteği kontrol etmelidir. Numara gerçekten yoksa kullanıcıdan istemeli; mevcutsa aktarım veya şema hatasını çözmeden aynı çağrıyı tekrarlamamalıdır. Kimlik doğrulama hatasında ise kullanıcının sipariş bilgilerini tekrar tekrar göndermesi çözüm sağlamaz; bağlantının kullandığı erişim belirteci ve yetki kapsamı kontrol edilmelidir.

Ajanın yanlış toparlanmasını önleme​

En yaygın hata, her başarısızlığı “bir kez daha dene” kuralıyla ele almaktır. Bu yaklaşım gecikmeyi artırabilir, kota tüketebilir ve yan etkili işlemleri iki kez çalıştırabilir. Her araç için en az şu sözleşme tanımlanmalıdır: beklenen girdi şeması, başarılı yanıt şeması, yeniden denenebilir hata sınıfları, maksimum deneme sayısı, zaman aşımı ve güvenli geri dönüş davranışı.

Ajan, araç başarısız olduğunda başarı uydurmamalıdır. Elinde doğrulanmış sonuç yoksa “işlem tamamlandı” yerine “işlem doğrulanamadı” demeli; varsa son güvenilir verinin ne zaman alındığını belirtmelidir. Geçici tanılama kayıtları sorun çözüldükten sonra gözden geçirilmeli ve gereksiz hassas içerik tutulmamalıdır.

Sık sorulan sorular​

Kaç kez yeniden deneme yapılmalı?​

Sabit bir sayı her araç için doğru değildir. Zaman aşımı ve geçici sunucu hatalarında kısa, sınırlı ve artan beklemeli denemeler kullanılabilir; işlem yan etki oluşturuyorsa tekrar çalıştırma güvenliği ayrıca doğrulanmalıdır. Parametre, yetki ve kimlik doğrulama hatalarında ise yeniden deneme yerine girdiyi veya bağlantı ayarını düzeltmek gerekir.

Araç yanıt vermediğinde ajan kullanıcıya ne söylemeli?​

Tamamlanmayan işlemi açıkça belirtmeli, başarısızlığın geçici görünüp görünmediğini söylemeli ve uygulanabilir tek sonraki adımı vermelidir. Doğrulanmış sonuç yoksa başarı iddiasında bulunmamalı; gerekiyorsa işlem kimliği veya hata zamanı gibi güvenli tanılama bilgilerini paylaşmalıdır.