Ajanınız bir API çağırır. API 429 döner. Ajanınız hemen tekrar dener, bir 429 daha alır, tekrar dener ve şimdi kısıtlanmış bir hizmeti, çalıştırma ölene veya fatura fırlayana kadar zorlayan bir döngüye sahip olursunuz. Kimse bu döngüyü bilerek yazmadı. Bu, “hatayı hallet”in basit versiyonundan kaynaklanır ve geliştiricilerin Anthropic SDK tartışma panosunda en sık sorduğu şeydir.
Hata kurtarma, ajan oluşturmanın temiz bir demoyu birini aramanız gereken bir şeyden ayıran kısmıdır. Sorun model değil. Sorun, bir araç çağrısı yavaş, kısıtlanmış veya bozuk döndüğünde kodunuzun ne yaptığıdır. Kurtarmayı doğru yaparsanız, güvenilmez bir bağımlılık kullanıcının asla fark etmediği kısa bir duraklamaya dönüşür. Yanlış yaparsanız, bir 500 bir olaya dönüşür. Bu kılavuz, yükün çoğunu taşıyan dört deseni kapsar: geri çekilmeli yeniden denemeler, zaman aşımları, devre kesiciler ve eşdeğerlik anahtarları. Ardından, bir kullanıcı sizin için boşlukları bulmadan önce bunları bir sahte ortamda nasıl test edeceğinizi gösterir. Ajanların nasıl başarısız olduğuna dair daha geniş bir resim için, üretimde yapay zeka ajanları neden bozuluyor ile başlayın.
Sağlıklı bir API'ye karşı kurtarmayı test edemezsiniz
İşte tuzak. Bağımlılığınız geliştirmede sorunsuz çalışır. Ajanınızı yazarsınız, çağrılar başarılı olur, demo temizdir ve yayınlarsınız. Kurtarma kodu hiç çalışmaz, çünkü sağlıklı bir API, halletmesi gereken hataları asla döndürmez. Geri çekilme mantığınızın ilk çalıştığı zaman, gerçek kullanıcıların izlediği gerçek bir kesinti sırasında, üretim ortamındadır. Bu, bir yeniden deneme döngüsündeki bir yazım hatasını keşfetmek için en kötü yerdir.
Kural basit. Kurtarmayı test etmek için hataları bilerek üretirsiniz. Ajanın çağırdığı API'nin bir sahtesini kurun, ona 429, 500, zaman aşımı veya hatalı bir gövde döndürmesini programlayın, ajanı ona yönlendirin ve ne yaptığını izleyin. Hata, sizi sabah 3'te tetikleyen bir şey yerine, bir testte tetiklediğiniz bir şeye dönüşür. Apidog bu sahteyi kurar ve yanıtları betikler, ve sonunda test bölümünde bunun üzerinden geçer.
Üstel geri çekilme ve titreşimle yeniden dene
Yeniden deneme ilk savunma hattıdır ve basit versiyonu bir tuzaktır. Hatayı yakala, hemen tekrar ara. Geçici bir aksaklığa karşı işe yarar. Yük altındaki bir hizmete karşı işleri daha da kötüleştirir, çünkü her başarısız istemci aynı anda yeniden dener ve bu yığılma hizmeti çökertir.
İki düzeltme bir araya gelir. Üstel geri çekilme, denemeleri aralıklı yapar: 1 saniye bekle, sonra 2, sonra 4, sonra 8, bir sınıra kadar ikiye katlayarak. Hizmet, anlık yeniden denemeler duvarı yerine toparlanma alanı bulur. Titreşim, her beklemeye rastgele bir ofset ekler, böylece aynı anda başarısız olan bin istemcinin hepsi aynı anda yeniden denemez. Olmazsa, geri çekilme yine de senkronize dalgalar üretir.
İki şeyi sınırlayın: gecikme, böylece denemeler arasında dakikalarca beklemezsiniz, ve deneme sayısı, böylece kalıcı bir hata sonsuza kadar yeniden denemek yerine vazgeçer. Üç ila beş deneme neredeyse her geçici hatayı kapsar. Bunun ötesinde, genellikle başarılı olmayacak bir şeyi yeniden deniyorsunuzdur. Anthropic SDK, kendi çağrıları için bunun bir kısmını yapar: bağlantı hatalarını ve belirli durum kodlarını üstel geri çekilme ile yeniden dener ve tavanı bir max-retries seçeneğiyle belirlersiniz. Ajanınızın araçlarının kullandığı diğer API'leri kapsamaz, bu yüzden bunları kendiniz sarmalarsınız. Yeniden denemelerinden para kazanan ekipler bunu erken öğrenir ve yüksek riskli API'ler için yeniden deneme mantığı hakkındaki analizimiz, dikkatsiz bir yeniden denemenin gerçek zarara yol açtığı yerleri gösterir.
Her çağrıda bir zaman aşımı ayarlayın
Yeniden deneme yalnızca istek başarısız olursa yardımcı olur. Daha kötü senaryo ise asla geri dönmeyen bir istektir: bir bağımlılık bağlantınızı kabul eder, sonra takılır. Zaman aşımı olmadan, araç çağrısı bloke olur ve tüm çalıştırma tek bir ölü soketin arkasında durur. Hata yok, kurtarma yok, sadece sıkışmış bir ajan duvar saati süresini ve jeton bütçesini hiçbir şey için yakar.
Her giden çağrının bir zaman aşımına ihtiyacı vardır. Bağlantı kurmak için bir bağlantı zaman aşımı ve yanıtı beklemek için bir okuma zaman aşımı ayarlayın, ardından tüm ajan çalıştırması için toplam bir bütçe belirleyin, böylece yavaş ama yasal çağrılar zinciri kullanıcının sabrından daha uzun sürmesin. Bir zaman aşımı tetiklendiğinde, onu diğer yeniden denenebilir hatalar gibi ele alın: geri çekilin ve sınırınıza kadar tekrar deneyin.
Sayıları tahminden değil, gerçek gecikmeden seçin. Her zaman aşımını bağımlılığın p99'unun üzerinde, bir miktar boşlukla ayarlayın. Çok sıkı olursa başarılı olacak çağrıları iptal edersiniz. Çok gevşek olursa, takılı kalmış bir bağımlılık ajanı faydalılık noktasının çok ötesine kadar meşgul eder. Akış yanıtlarına kendi bütçelerini verin, çünkü uzun bir tamamlama meşru olarak yavaştır ve kısa, sabit bir zaman aşımı onu akış ortasında öldürür.
Bir bağımlılık çöktüğünde devre kesiciyi tetikle
Geri çekilme, kısa süreliğine meşgul olan bir hizmeti ele alır. Tamamen çökmüş bir hizmet için yanlış araçtır. Bir bağımlılık bir dakikadır başarısız oluyorsa, bir sonraki istek de neredeyse kesinlikle başarısız olacaktır ve onu yeniden denemek, zaten bozuk olan bir şeyin üzerine daha fazla yük bindirirken, kullanıcı sizin tahmin edebileceğiniz bir hatayı bekler.
Bir devre kesici bunu üç durumla düzeltir. Kapalı normaldir: istekler akar ve kesici başarısızlıkları sayar. Başarısızlıklar bir eşiği aştığında, açık duruma geçer: istek göndermeyi durdurur ve bir bekleme penceresi boyunca hızla başarısız olur, böylece ölü bir hizmete yapılan her çağrıda zaman aşımı ücretini ödememiş olursunuz. Pencereden sonra, yarı açık duruma geçer ve tek bir yoklamanın geçmesine izin verir. Yoklama başarılı olursa, kesici kapanır ve trafik devam eder; başarısız olursa, tekrar açılır ve bekler.
Bir ajan için, kesici "ödeme API'si çalışmıyor" durumunu, jeton bütçesini ve saati tüketen kırk yavaş zaman aşımı yerine, ajanın düşünebileceği hızlı, temiz bir başarısızlığa dönüştürür. Bunu genel olarak değil, bağımlılık bazında yapılandırın, böylece ölü bir arama API'si, ajanın sağlıklı bir faturalandırma API'sini kullanmasını engellemez.
Eşdeğerlik anahtarlarıyla yeniden denemeleri güvenli hale getirin
Şu ana kadarki her desen, yeniden denemenin güvenli olduğunu varsayar. Genellikle öyle değildir. Ajanınız POST /charge gönderir, sunucu onu işler ve yanıt yolda zaman aşımına uğrar. Ajan başarıyı asla görmediği için tekrar dener ve şimdi müşteriden iki kez ücret alınır. Yeniden deneme tam olarak istediğinizi yaptı. Tasarım hataydı.
Bir eşdeğerlik anahtarı bu boşluğu kapatır. İstemci, her mantıksal eylem için benzersiz bir anahtar oluşturur ve bunu istekle birlikte, genellikle Idempotency-Key başlığı olarak gönderir. Sunucu, anahtarı ilk alındığında kaydeder ve aynı anahtarı tekrar görürse, işi iki kez yapmak yerine orijinal sonucu döndürür. Artık yeniden deneme yapı itibarıyla güvenlidir: aynı anahtara sahip ikinci POST /charge işlemi, ilk ücreti geri veren etkisiz bir işlemdir.
Anahtar, aynı eylemin yeniden denemeleri arasında sabit kalmalı ve farklı eylemler arasında değişmelidir. Anahtarı isteği oluştururken bir kez oluşturun, yeniden deneme döngüsünün içinde değil, aksi takdirde her deneme yeni bir anahtar alır ve tekilleştirme asla tetiklenmez. Durum oluşturan veya değiştiren (ücretler, siparişler, e-postalar, kayıtlar) her araç çağrısı bir anahtara ihtiyaç duyar. Eşdeğerlik anahtarları hakkındaki kılavuzumuz, oluşturmayı ve sunucu tarafı işlemeyi tam olarak kapsar.
Oran sınırlarından ve RateLimitError döngüsünden kurtulun
Oran sınırları, talimatlarla birlikte geldikleri için ayrı bir işlem görmeyi hak eder. Bir oran sınırı aşıldı yanıtı genellikle size tam olarak ne kadar beklemeniz gerektiğini, saniye veya tarih olarak bildiren bir 429 ve `Retry-After` başlığıyla gelir. Buna uyun. Sunucu 30 saniye beklemenizi söylerse ve siz 2 saniye içinde tekrar denerseniz, başka bir 429 alırsınız ve SDK tartışma panosunu dolduran RateLimitError döngüsünü oluşturmuş olursunuz: limiti yakalayın, çok erken tekrar deneyin, daha sert sınırlanın, çalıştırma ölene kadar tekrarlayın. Ayrı bir SDK konusu, geliştiricilerin burada karşılaştığı aynı engeli kapsar.
Çözüm, sunucunun hızı belirlemesine izin vermektir. 429 aldığınızda, `Retry-After` başlığını okuyun ve yeniden denemeden önce en az o kadar bekleyin. Başlık eksikse, titreşimli üstel geri çekilmeye geri dönün. Denemeleri sınırlayın, böylece sürekli bir limit sonsuz bir bekleme yerine temiz bir başarısızlıkla sonuçlansın. Anthropic SDK, kendi çağrıları için zaten `Retry-After`'a uyar; yapılması gereken, aynı kuralı ajanınızın dokunduğu diğer oran sınırlı API'lere uygulamaktır.
Proaktif bir yanı da var. Bir sağlayıcı dakikada belirli sayıda isteğe izin veriyorsa, kendi çağrılarınızı bir token kovasıyla ölçün, böylece kısıtlanarak bulmak yerine tavanın altında kalırsınız. Kurtarma, karşılaştığınız limitleri ele alır; hız ayarlaması ise onlara çarpmamanızı sağlar.
Kurtarma yolunu nasıl test edersiniz
Şimdi bir araya getirelim. Yukarıdaki desenler, çalıştıklarına dair kanıtınız kadar iyidir ve bu kanıt, sağlıklı bir API'nin size vermeyeceği hataları zorlayan bir testtir. Şekil her senaryoda yeniden kullanılır:
- Bağımlılığı sahteleyin. Ajanınızın aracının çağırdığı API'nin bir sahtesini kurun, böylece her durum kodunu, başlığı, gövdeyi ve gecikmeyi kontrol edebilirsiniz ve test sırasında gerçek bir ücret veya e-posta tetiklenmez.
- Bir dizi programlayın. Sahteyi, bir dizi çağrıya sırayla yanıt verecek şekilde betikleyin: önce `Retry-After: 2` ile bir 429, sonra bir 500, sonra geçerli bir gövde ile bir 200. Tek bir uç nokta, üç betiklenmiş yanıt, tek bir çalıştırmada tam bir kurtarma döngüsü.
- Ajanı sahteye yönlendirin. Ajanın aracını gerçek hizmet yerine sahte URL'ye yönlendirin ve senaryoyu baştan sona çalıştırın.
- Davranışı doğrulayın. Önemli olanı kontrol edin: ajan 429'dan sonra yeniden denemeden önce en az 2 saniye bekledi mi, 500'den sonra yeniden denedi mi, üçüncü çağrıda başarılı oldu mu ve deneme sınırınızı hiç aşmadı mı.
Bu tek senaryo, tek bir geçişte geri çekilmeyi ve `Retry-After`'ı kanıtlar. Vazgeçme yolu için ikinci bir senaryo ekleyin: sahteyi her zaman başarısız olacak şekilde betikleyin ve ajanın sınıra ulaştığında durduğunu ve döngüye girmek yerine temiz bir hata döndürdüğünü doğrulayın. Devre kesici için üçüncü bir senaryo ekleyin: yeterince çağrıyı arka arkaya başarısız edin ve ajanın takılıp her denemede bir zaman aşımı ödemek yerine hızla başarısız olduğunu doğrulayın.
Eşdeğerlik kontrolü, insanların atladığı ve para kazandıran bir kontrol. Sahteyi, mutasyon yapan bir çağrıyı kabul edecek, yanıtı düşürecek (böylece ajan başarısız olduğunu düşünecek) ve sonra yeniden denemeyi kabul edecek şekilde betikleyin. Şimdi istek şeklini doğrulayın: her iki istek de aynı `Idempotency-Key`'i taşıdı mı ve sahte ortam iki değil, tek bir mantıksal eylem mi gördü? Yeniden denemede yeni bir anahtar veya yinelenen bir çağrı, bir müşteriden önce çift gönderme bulduğunuz anlamına gelir. API'lerinizi çağıran ajanları test etmeye yönelik daha geniş yöntem, test çerçevesini baştan sona kurar.
Hata kurtarma kontrol listesi
Bir ajan üretime geçmeden önce bu listeyi gözden geçirin:
- Her giden çağrının bir bağlantı zaman aşımı, bir okuma zaman aşımı ve toplam çalıştırma bütçesi vardır.
- Yeniden denemeler, gecikme ve deneme sayısında sınırlı, titreşimli üstel geri çekilme kullanır.
- 429 yanıtları `Retry-After` başlığını okur ve buna uyar, geri çekilme yedek olarak kullanılır.
- Her bağımlılık için bir devre kesici tetiklenir, böylece ölü bir hizmet döngüye girmek yerine hızla başarısız olur.
- Durum değiştiren her çağrı, yeniden denemelere dayanıklı sabit bir eşdeğerlik anahtarı taşır.
- Vazgeçme yolu, sonsuz bir bekleme yerine temiz bir hata döndürür.
- Bunların her biri, varsayılan değil, sahte bir ortama karşı hatayı zorlayan bir testle kanıtlanmıştır.
Yedisini de işaretlerseniz, ajanınız şans eseri değil, bilerek kurtarma yapar.
Apidog nereye uyar (ve nereye uymaz)
Aracın işini dürüst tutun. Apidog bir ajan çerçevesi, bir model barındırıcısı veya bir çalışma zamanı değildir. Ajanınızı inşa etmez, çalıştırmaz veya düzenlemez ve modelin çıktısını derecelendirmez. Sahip olduğu şey, ajanınızın çağırdığı API katmanıdır ki kurtarmanın kazanıldığı veya kaybedildiği yer tam olarak burasıdır.
Bu ona üç görev verir. Ajanınızın vurduğu bağımlılıkları sahteler, böylece canlı hizmet yerine kontrol edilebilir bir vekil elde edersiniz. Gerçek bir API'nin komut üzerine üretmeyeceği hata yanıtlarını (429 `Retry-After` ile, 500, zaman aşımı, hatalı gövde) programlar, böylece kurtarmayı prova edebilirsiniz. Ve sahte ortamın aldığı istekleri doğrular (eşdeğerlik anahtarı mevcut ve sabit mi, doğru biçimde mi, beklenen çağrı sayısı mı), böylece çift gönderme veya düşen bir başlık bir müşteriyi değil, bir testi başarısız kılar. Dürüst uyum budur: Apidog, ajanınızın hayatta kalması gereken hataları sahteler ve ne gönderdiğini kontrol eder.
Sıkça sorulan sorular
Anthropic SDK benim için yeniden denemeleri halletmiyor mu? Kendi çağrıları için evet. SDK, belirli hataları üstel geri çekilme ile yeniden dener ve `Retry-After`'a uyar, ve tavanı bir max-retries seçeneğiyle belirlersiniz. Ajanınızın araçlarının çağırdığı diğer API'leri kapsamaz. Bunlara aynı desenleri sizin uygulamanız gerekir.
Eşdeğerlik anahtarına ne zaman ihtiyacım var? Durum oluşturan veya değiştiren her çağrıda: ücretler, siparişler, gönderilen mesajlar, yeni kayıtlar. Sadece okuma çağrıları, anahtar olmadan yeniden denenmesi güvenlidir. Anahtarı eylem başına bir kez oluşturun, böylece yeniden denemeler arasında sabit kalsın.
Bu hafta bir başarısızlığı prova edin
Dört deseni birden oluşturmak zorunda değilsiniz. En çok zarar verecek olanı seçin, genellikle oran sınırlama döngüsü veya eşdeğer olmayan bir yeniden deneme, ve bunu bir sahte ortamda prova edin. 429'u programlayın, bir yanıtı düşürün ve ajanın ne gönderdiğini izleyin. İki kez ücretlendirme korkusu yaşadığınız yerde ilk kez temiz geri çekilme ve tek bir eşdeğerlik anahtarı gördüğünüzde, ajana yeşil bir demodan daha iyi bir nedenle güveneceksiniz.
Hataları sahtelemek, diziyi betiklemek ve API geri tepince ajanınızın ne yaptığını doğrulamak için Apidog'u indirin.