Agen Anda memanggil API. API mengembalikan kode 429. Agen Anda segera mencoba lagi, mendapatkan 429 lagi, mencoba lagi, dan sekarang Anda memiliki loop yang menghantam layanan yang dibatasi hingga prosesnya mati atau tagihan membengkak. Tidak ada yang menulis loop itu dengan sengaja. Itu muncul dari versi naif dari “menangani kesalahan,” dan itu adalah hal paling umum yang ditanyakan pengembang di papan diskusi Anthropic SDK.
Pemulihan kesalahan adalah bagian dari pembangunan agen yang membedakan demo yang bersih dari sesuatu yang mengharuskan Anda memanggil seseorang. Model bukanlah masalahnya. Masalahnya adalah apa yang kode Anda lakukan ketika panggilan alat kembali lambat, dibatasi, atau rusak. Lakukan pemulihan dengan benar dan ketergantungan yang tidak stabil menjadi jeda singkat yang tidak pernah disadari pengguna. Lakukan kesalahan dan satu kode 500 berubah menjadi insiden. Panduan ini mencakup empat pola yang menanggung sebagian besar beban: percobaan ulang dengan backoff, timeout, circuit breaker, dan kunci idempoten. Kemudian, ini menunjukkan cara mengujinya terhadap mock, sebelum pengguna menemukan celah untuk Anda. Untuk gambaran yang lebih luas tentang bagaimana agen gagal, mulailah dengan mengapa agen AI rusak dalam produksi.
Anda tidak bisa menguji pemulihan terhadap API yang sehat
Inilah jebakannya. Ketergantungan Anda berfungsi dengan baik dalam pengembangan. Anda menulis agen Anda, panggilan berhasil, demo bersih, dan Anda meluncurkannya. Kode pemulihan tidak pernah berjalan sekali pun, karena API yang sehat tidak pernah mengembalikan kesalahan yang seharusnya ditangani. Pertama kali logika backoff Anda berjalan adalah dalam produksi, saat terjadi pemadaman nyata, dengan pengguna nyata yang mengawasi. Itu adalah tempat terburuk untuk menemukan salah ketik dalam loop percobaan ulang.
Jadi aturannya sederhana. Untuk menguji pemulihan, Anda sengaja menghasilkan kegagalan. Buat mock dari API yang dipanggil agen, program untuk mengembalikan 429, 500, timeout, atau body yang salah format, arahkan agen ke sana, dan lihat apa yang dilakukannya. Kegagalan menjadi sesuatu yang Anda picu dalam pengujian, bukan sesuatu yang memicu Anda pada jam 3 pagi. Apidog menyiapkan mock tersebut dan membuat skrip responsnya, dan ini akan dibahas di bagian pengujian di akhir.
Coba lagi dengan exponential backoff dan jitter
Percobaan ulang adalah garis pertahanan pertama, dan versi naif adalah jebakannya. Tangkap kesalahannya, panggil lagi segera. Terhadap gangguan sementara itu berhasil. Terhadap layanan di bawah beban itu memperburuk keadaan, karena setiap klien yang gagal mencoba lagi pada saat yang sama dan serbuan itu membuat layanan tetap tidak berfungsi.
Dua perbaikan dapat digabungkan. Exponential backoff memperlambat upaya: tunggu 1 detik, lalu 2, lalu 4, lalu 8, berlipat ganda hingga batas atas. Layanan mendapatkan ruang untuk pulih alih-alih menghadapi rentetan percobaan ulang langsung. Jitter menambahkan offset acak ke setiap penantian sehingga seribu klien yang semuanya gagal pada saat yang sama tidak semuanya mencoba lagi pada saat yang sama. Tanpa itu, backoff masih menghasilkan gelombang yang sinkron.
Batasi dua hal: penundaan, agar Anda tidak menunggu berjam-jam di antara percobaan, dan jumlah percobaan, agar kegagalan permanen menyerah daripada mencoba lagi selamanya. Tiga hingga lima percobaan mencakup hampir setiap kesalahan sementara. Lebih dari itu Anda biasanya mencoba lagi sesuatu yang tidak akan berhasil. Anthropic SDK melakukan sebagian dari ini untuk panggilannya sendiri: ia mencoba lagi kesalahan koneksi dan kode status tertentu dengan exponential backoff, dan Anda menetapkan batas atas dengan opsi max-retries. Ini tidak mencakup API lain yang digunakan oleh alat agen Anda, jadi Anda harus menanganinya sendiri. Tim yang mengelola uang melalui percobaan ulangnya mempelajari ini sejak dini, dan analisis kami tentang logika percobaan ulang untuk API berisiko tinggi menunjukkan di mana percobaan ulang yang ceroboh menyebabkan kerusakan nyata.
Tetapkan timeout pada setiap panggilan
Percobaan ulang hanya membantu jika permintaan gagal. Kasus yang lebih buruk adalah permintaan yang tidak pernah kembali: sebuah dependensi menerima koneksi Anda, lalu menggantung. Tanpa timeout, panggilan alat akan terblokir dan seluruh proses akan macet di belakang satu soket yang mati. Tidak ada kesalahan, tidak ada pemulihan, hanya agen yang macet yang membuang waktu jam dinding dan anggaran token untuk hal yang sia-sia.
Setiap panggilan keluar memerlukan timeout. Tetapkan timeout koneksi untuk membangun koneksi dan timeout baca untuk menunggu respons, lalu anggaran total untuk seluruh eksekusi agen sehingga serangkaian panggilan yang lambat namun sah tidak dapat melebihi kesabaran pengguna. Ketika timeout terjadi, perlakukan seperti kesalahan lain yang dapat dicoba ulang: mundur dan coba lagi, hingga batas Anda.
Pilih angka dari latensi nyata, bukan tebakan. Atur setiap timeout di atas p99 dependensi dengan ruang cadangan. Terlalu ketat dan Anda membatalkan panggilan yang seharusnya berhasil. Terlalu longgar dan dependensi yang menggantung mengikat agen jauh melewati titik kegunaan. Berikan respons streaming anggaran sendiri, karena penyelesaian yang panjang memang lambat dan timeout tetap yang singkat akan menghentikannya di tengah jalan.
Picu circuit breaker saat dependensi tidak berfungsi
Backoff menangani layanan yang sesaat sibuk. Ini adalah alat yang salah untuk layanan yang benar-benar mati. Jika sebuah dependensi telah gagal selama satu menit, permintaan berikutnya hampir pasti juga akan gagal, dan mencoba lagi akan menumpuk lebih banyak beban pada sesuatu yang sudah rusak sementara pengguna menunggu kegagalan yang bisa Anda prediksi.
Circuit breaker memperbaikinya dengan tiga status. Closed adalah normal: permintaan mengalir dan breaker menghitung kegagalan. Ketika kegagalan melewati ambang batas, itu akan trip ke open: ia berhenti mengirim permintaan dan gagal dengan cepat untuk jendela pendinginan, sehingga Anda tidak membayar timeout pada setiap panggilan ke layanan yang mati. Setelah jendela tersebut, ia menjadi half-open dan membiarkan satu probe lewat. Jika probe berhasil, breaker menutup dan lalu lintas dilanjutkan; jika gagal, ia membuka lagi dan menunggu.
Untuk agen, breaker mengubah “API pembayaran tidak berfungsi” menjadi satu kegagalan cepat dan bersih yang dapat dipahami agen, alih-alih empat puluh timeout lambat yang menguras anggaran token dan waktu. Hubungkan per dependensi, bukan secara global, sehingga API pencarian yang mati tidak menghentikan agen untuk menggunakan API penagihan yang sehat.
Amankan percobaan ulang dengan kunci idempoten
Setiap pola sejauh ini mengasumsikan percobaan ulang aman. Seringkali tidak. Agen Anda mengirim POST /charge, server memprosesnya, dan respons mengalami timeout saat kembali. Agen tidak pernah melihat keberhasilan, jadi ia mencoba lagi, dan sekarang pelanggan ditagih dua kali. Percobaan ulang melakukan persis seperti yang Anda minta. Desainnya adalah bug.
Kunci idempoten menutup celah ini. Klien menghasilkan kunci unik per tindakan logis dan mengirimkannya dengan permintaan, biasanya sebagai header Idempotency-Key. Server mencatat kunci pada penerimaan pertama dan, jika melihat kunci yang sama lagi, mengembalikan hasil asli alih-alih melakukan pekerjaan dua kali. Sekarang percobaan ulang aman secara konstruksi: POST /charge kedua dengan kunci yang sama adalah operasi tanpa efek yang mengembalikan tagihan pertama.
Kunci harus tetap stabil di seluruh percobaan ulang tindakan yang sama dan berubah antara tindakan yang berbeda. Hasilkan sekali saat Anda membangun permintaan, bukan di dalam loop percobaan ulang, atau setiap percobaan akan mendapatkan kunci baru dan deduplikasi tidak akan pernah terjadi. Setiap panggilan alat yang membuat atau mengubah status (tagihan, pesanan, email, catatan) memerlukannya. Panduan kami tentang kunci idempoten mencakup pembuatan dan penanganan sisi server secara lengkap.
Bertahan dari pembatasan laju dan loop RateLimitError
Pembatasan laju memerlukan penanganan tersendiri karena mereka datang dengan instruksi. Respons melebihi batas laju biasanya datang sebagai 429 yang membawa header Retry-After yang memberi tahu Anda persis berapa lama harus menunggu, dalam detik atau sebagai tanggal. Hormati itu. Jika server mengatakan tunggu 30 detik dan Anda mencoba lagi dalam 2 detik, Anda akan mendapatkan 429 lagi, dan Anda telah membangun loop RateLimitError yang memenuhi papan diskusi SDK: tangkap batasnya, coba lagi terlalu cepat, dibatasi lebih keras, ulangi sampai prosesnya mati. Thread SDK terpisah membahas masalah yang sama yang dihadapi pengembang di sini.
Solusinya adalah membiarkan server mengatur kecepatan. Ketika Anda mendapatkan 429, baca Retry-After dan tunggu setidaknya selama itu sebelum mencoba lagi. Jika header tidak ada, kembali ke exponential backoff dengan jitter. Batasi percobaan agar batas yang berkelanjutan berakhir dengan kegagalan yang bersih alih-alih menunggu tanpa henti. Anthropic SDK sudah menghormati Retry-After untuk panggilannya sendiri; tugasnya adalah menerapkan aturan yang sama ke API terbatas laju lainnya yang disentuh agen Anda.
Ada sisi proaktif juga. Jika penyedia mengizinkan sejumlah permintaan per menit, ukur panggilan Anda sendiri dengan token bucket agar Anda tetap di bawah batas alih-alih menemukannya dengan tercekik. Pemulihan menangani batas yang Anda capai; penjagaan kecepatan menjaga Anda agar tidak mencapainya.
Cara menguji jalur pemulihan
Sekarang gabungkan. Pola-pola di atas hanya sebaik bukti Anda bahwa mereka berfungsi, dan buktinya adalah tes yang memaksakan kegagalan yang tidak akan diberikan oleh API yang sehat. Bentuknya digunakan kembali di setiap skenario:
- Mock dependensi. Buat mock dari API yang dipanggil alat agen Anda, sehingga Anda mengontrol setiap kode status, header, body, dan penundaan, dan tidak ada tagihan atau email nyata yang terkirim selama pengujian.
- Program urutan. Skrip mock untuk menjawab serangkaian panggilan secara berurutan: pertama 429 dengan
Retry-After: 2, lalu 500, lalu 200 dengan body yang valid. Satu endpoint, tiga respons terprogram, busur pemulihan penuh dalam satu eksekusi. - Jalankan agen pada mock. Arahkan alat agen ke URL mock alih-alih layanan nyata dan jalankan skenario dari awal hingga akhir.
- Pastikan perilaku. Periksa apa yang penting: agen menunggu setidaknya 2 detik setelah 429 sebelum mencoba lagi, mencoba lagi setelah 500, berhasil pada panggilan ketiga, dan tidak pernah melebihi batas percobaan Anda.
Satu skenario itu membuktikan backoff dan Retry-After dalam satu lintasan. Tambahkan skenario kedua untuk jalur menyerah: skrip mock agar gagal setiap saat dan pastikan agen berhenti pada batas dan mengembalikan kesalahan yang bersih alih-alih berulang. Tambahkan yang ketiga untuk circuit breaker: gagal dalam panggilan berturut-turut yang cukup dan pastikan agen trip dan gagal cepat alih-alih membayar timeout pada setiap percobaan.
Pemeriksaan idempoten adalah yang sering dilewati orang, dan inilah yang menghemat uang. Skrip mock untuk menerima panggilan yang mengubah data, jatuhkan respons agar agen mengira itu gagal, lalu terima percobaan ulang. Sekarang pastikan bentuk permintaan: kedua permintaan membawa Idempotency-Key yang sama, dan mock melihat satu tindakan logis, bukan dua. Kunci baru pada percobaan ulang, atau panggilan duplikat, berarti Anda menemukan pengiriman ganda sebelum pelanggan melakukannya. Metode yang lebih luas untuk menguji agen yang memanggil API Anda menyiapkan harness secara menyeluruh.
Daftar periksa pemulihan kesalahan
Sebelum agen masuk ke produksi, periksa daftar ini:
- Setiap panggilan keluar memiliki timeout koneksi, timeout baca, dan anggaran total eksekusi.
- Percobaan ulang menggunakan exponential backoff dengan jitter, dibatasi baik dalam penundaan maupun jumlah percobaan.
- Respons 429 membaca dan menghormati
Retry-After, dengan backoff sebagai cadangan. - Circuit breaker trip per dependensi sehingga layanan yang mati gagal dengan cepat alih-alih berulang.
- Setiap panggilan yang mengubah status membawa kunci idempoten yang stabil yang bertahan dari percobaan ulang.
- Jalur menyerah mengembalikan kesalahan yang bersih, bukan penantian tanpa batas.
- Masing-masing telah dibuktikan dengan tes yang memaksakan kegagalan terhadap mock, bukan diasumsikan.
Centang ketujuh poin ini dan agen Anda akan pulih dengan sengaja alih-alih karena keberuntungan.
Di mana Apidog sesuai (dan di mana tidak)
Pertahankan pekerjaan alat dengan jujur. Apidog bukanlah kerangka kerja agen, host model, atau runtime. Ia tidak membangun, menjalankan, atau mengorkestrasi agen Anda, dan tidak menilai output model. Yang dimilikinya adalah lapisan API yang dipanggil agen Anda, yang justru merupakan tempat di mana pemulihan dimenangkan atau kalah.
Itu memberinya tiga tugas. Ia mem-mock dependensi yang dijangkau agen Anda, sehingga Anda mendapatkan pengganti yang dapat dikontrol alih-alih layanan langsung. Ia memprogram respons kegagalan (429 dengan Retry-After, 500, timeout, body yang salah format) yang tidak akan dihasilkan oleh API nyata sesuai perintah, sehingga Anda dapat melatih pemulihan. Dan ia memvalidasi permintaan yang diterima mock (kunci idempoten ada dan stabil, bentuk yang benar, jumlah panggilan yang diharapkan) sehingga pengiriman ganda atau header yang hilang menyebabkan kegagalan pengujian alih-alih kegagalan pelanggan. Itulah kecocokan yang jujur: Apidog mem-mock kegagalan yang harus dilalui agen Anda dan memeriksa apa yang dikirimnya kembali.
Pertanyaan yang sering diajukan
Bukankah Anthropic SDK menangani percobaan ulang untuk saya? Untuk panggilannya sendiri, ya. SDK mencoba ulang kesalahan tertentu dengan exponential backoff dan menghormati Retry-After, dan Anda menetapkan batas atas dengan opsi max-retries. Ini tidak mencakup API lain yang dipanggil alat agen Anda. Itu memerlukan pola yang sama yang diterapkan oleh Anda.
Kapan saya memerlukan kunci idempoten? Pada setiap panggilan yang membuat atau mengubah status: tagihan, pesanan, pesan terkirim, catatan baru. Panggilan baca-saja aman untuk dicoba ulang tanpa itu. Hasilkan kunci sekali per tindakan agar tetap stabil di seluruh percobaan ulang.
Latih satu kegagalan minggu ini
Anda tidak perlu membangun keempat pola sekaligus. Pilih salah satu yang paling merugikan, biasanya loop pembatasan laju atau percobaan ulang yang tidak idempoten, dan latih terhadap mock. Program 429, jatuhkan respons, dan amati apa yang dikirim agen. Pertama kali Anda melihat backoff yang bersih dan satu kunci idempoten di mana Anda takut akan tagihan ganda, Anda akan mempercayai agen dengan alasan yang lebih baik daripada demo yang mulus.
Unduh Apidog untuk mem-mock kegagalan, membuat skrip urutan, dan memastikan apa yang dilakukan agen Anda ketika API menolak.