Agen Anda berfungsi dalam demo. Ia membaca tiket, memanggil tiga API, dan memposting ringkasan yang bersih. Kemudian Anda merilisnya. Seminggu kemudian, ia mengirim email kepada pelanggan yang sama dua kali, menghabiskan anggaran token satu hari untuk loop percobaan ulang, dan menyerahkan payload yang tidak dapat diuraikan oleh frontend Anda.
Kesenjangan antara prototipe yang berfungsi dan agen yang andal adalah tempat sebagian besar tim terjebak. Model ini jarang menjadi penyebabnya. Masalahnya terletak pada bagian yang diperlakukan sebagai perpipaan: panggilan API yang dilakukan agen untuk mendapatkan jawaban. Agen adalah loop panggilan alat, dan setiap panggilan alat adalah permintaan HTTP yang dapat gagal, dibatasi, kehabisan waktu, atau mengembalikan sesuatu yang tidak Anda duga. Lewati pengujian panggilan-panggilan itu seperti Anda menguji API produksi mana pun, dan agen Anda hanya berjarak satu respons buruk dari insiden.
Inilah bagian yang meyakinkan: keandalan agen dapat diuji. Anda tidak perlu memercayai model untuk berperilaku. Anda sengaja melatih jalur kegagalan, sebelum pengguna Anda menemukannya. Panduan ini mengelompokkan kegagalan agen ke dalam lima mode dan menunjukkan cara mengatasi setiap mode. Pekerjaan ini terjadi di batas API, jadi Anda memerlukan platform yang dapat Anda arahkan ke dependensi agen untuk merancang kontrak, menguji kegagalan, dan memeriksa apa yang dikembalikan. Apidog melakukan pekerjaan itu, dan berjalan melalui contoh-contoh di bawah ini.
Agen gagal di batas API, bukan di prompt
Ketika agen berperilaku tidak semestinya dalam produksi, naluri pertama adalah mengedit prompt. Kadang-kadang itu membantu. Lebih sering kegagalan tidak ada hubungannya dengan pemilihan kata. Agen meminta sesuatu dari API yang sebenarnya, dan responsnya lambat, salah format, dibatasi tingkatnya, atau memiliki bentuk yang berbeda dari yang diharapkan agen. Model kemudian bernalar atas masukan yang buruk dan melakukan sesuatu dengan yakin namun salah.
Lihatlah apa yang melibatkan satu langkah agen. Model memilih sebuah alat. Kode Anda mengubah pilihan itu menjadi permintaan HTTP. Layanan eksternal menjawab. Kode Anda memberikan hasil kembali ke model. Empat serah terima, dan tiga di antaranya adalah integrasi API biasa, bukan pembelajaran mesin. Itu adalah kabar baik, karena integrasi API adalah masalah pengujian yang sudah terpecahkan. Anda sudah tahu cara menguji titik akhir yang lambat atau menegaskan skema JSON. Agen meningkatkan taruhan, karena model bertindak berdasarkan apa pun yang diterimanya alih-alih memunculkan pengecualian yang bersih.
Jadi pertanyaan keandalan bukanlah “apakah model cukup pintar.” Ini adalah “sudahkah saya menguji setiap cara panggilan API agen dapat berjalan menyimpang.” Lima mode mencakup sebagian besar hal ini.
Mode kegagalan 1: panggilan alat yang menyimpang dari kontrak
Kegagalan agen yang paling umum adalah panggilan alat yang tidak sesuai dengan API yang dipanggilnya. Model membuat parameter, menghilangkan bidang yang wajib, mengirim string padahal skema menginginkan bilangan bulat, atau memanggil titik akhir yang tepat dengan argumen yang tidak masuk akal. Misalkan agen pemesanan memanggil POST /reservations dengan guests: "two" alih-alih guests: 2. API mengembalikan 400, atau lebih buruk, 200 dengan kesalahan tersembunyi di dalam body, dan agen terus berjalan seolah-olah berhasil.
Anda mengatasi ini dengan menguji panggilan alat sebagai sebuah kontrak. Definisikan skema untuk setiap alat yang dapat dipanggil agen, lalu pastikan permintaan keluar cocok: bidang yang wajib ada, jenis yang benar, enum yang valid. Ketika agen menghasilkan panggilan yang melanggar kontrak, Anda ingin hal itu gagal secara keras dalam pengujian, bukan diam-diam dalam produksi. Panduan kami tentang menguji panggilan alat agen AI membahas hal ini secara mendalam, dan metode yang lebih luas untuk menguji agen yang memanggil API Anda mencakup pengaturan secara menyeluruh.
Langkah praktis: tangkap skema alat yang digunakan agen Anda, muat ke dalam Apidog, dan jalankan panggilan alat nyata agen terhadap definisi tersebut. Ketidaksesuaian akan muncul sebagai kegagalan validasi yang menyebutkan bidang persis yang rusak.
Mode kegagalan 2: kesalahan upstream dan batas laju
Setiap panggilan eksternal yang dilakukan agen dapat mengembalikan 429, 500, atau tidak sama sekali sebelum batas waktu. Agen yang dibangun dengan baik menangani ini dengan percobaan ulang dan penundaan. Agen yang rapuh akan menyerah pada kesalahan pertama atau, yang lebih berbahaya, mencoba ulang dengan sangat keras sehingga memicu pembatasan lebih lanjut dan berputar dalam loop yang menghabiskan anggaran Anda. Pertanyaan yang paling sering diajukan di papan diskusi SDK Anthropic secara harfiah adalah tentang pola pemulihan kesalahan agen, yang memberitahu Anda seberapa umum masalah ini.
Anda tidak dapat menguji pemulihan terhadap API yang sehat, karena API yang sehat tidak pernah mengembalikan kesalahan yang perlu Anda tangani. Di sinilah mocking sangat berguna. Buat mock dependensi agen dan program urutan: 429 dengan header Retry-After, lalu 500, lalu berhasil. Sekarang perhatikan apa yang dilakukan agen Anda. Apakah ia menunda dengan jitter? Apakah ia menghormati header tersebut? Apakah ia menyerah dengan anggun setelah sejumlah percobaan yang masuk akal, atau membuka pemutus sirkuit sehingga ia berhenti membebani layanan yang jelas-jelas mati? Dan jika tindakan yang dicoba ulang tidak idempoten, apakah pengulangan akan mengenakan biaya ganda atau mengirim ganda? Kunci idempoten adalah yang membuat percobaan ulang aman untuk diulang.
Batas laju perlu latihan tersendiri. Jika Anda belum melihat bagaimana agen Anda berperilaku ketika penyedia membatasi lajunya, baca panduan kami tentang apa arti respons batas laju terlampaui dan kemudian simulasikan. Panduan khusus tentang pemulihan kesalahan agen AI mencakup pola percobaan ulang, batas waktu, penundaan, dan pemutus sirkuit secara lengkap.
Mode kegagalan 3: output non-deterministik
Atur suhu ke nol dan Anda tetap tidak akan mendapatkan output yang identik secara byte di seluruh eksekusi. Pengembang terus-menerus menemukan kembali hal ini; ada diskusi vLLM yang panjang tentang seed dan suhu yang tidak cukup untuk reproduktifitas. Perubahan pada perangkat keras, batching, dan sisi penyedia semuanya memperkenalkan variasi. Jika pengujian Anda menegaskan string yang persis sama, pengujian tersebut menjadi tidak stabil, dan pengujian yang tidak stabil diabaikan, yang lebih buruk daripada tidak ada pengujian. Ulasan kami tentang apa yang menyebabkan pengujian tidak stabil berlaku langsung di sini.
Solusinya adalah menegaskan struktur dan makna, bukan teks yang persis sama. Periksa bahwa respons tervalidasi terhadap skema JSON. Periksa bahwa panggilan alat memiliki bentuk dan target yang benar. Periksa bahwa jawaban numerik berada dalam rentang yang masuk akal. Periksa bahwa kunci yang wajib ada dan bidang yang dilarang tidak ada. Uji yang mengatakan "balasan berisi total antara 0 dan nilai keranjang" bertahan dari variasi alami model sambil tetap menangkap regresi nyata. Panduan tentang menguji agen AI non-deterministik menjabarkan strategi lengkap, dan artikel tentang cara kerja memori agen menunjukkan mengapa status membuat ini lebih sulit.
Mode kegagalan 4: biaya tidak terkendali
Agen berulang, dan perulangan membutuhkan biaya. Satu agen yang macet yang mencoba ulang panggilan yang gagal beberapa ribu kali dapat mengubah tagihan kecil menjadi besar dalam semalam. Salah satu laporan lapangan dalam diskusi SDK menggambarkan penurunan biaya agen dari 500 dolar per bulan menjadi 80 tanpa kehilangan kualitas, yang menunjukkan seberapa cepat biaya merayap dan seberapa banyak kelonggaran biasanya tersembunyi dalam desain.
Biaya adalah masalah keandalan, bukan hanya masalah keuangan, karena bug yang membuang uang (perulangan, panggilan berlebihan, konteks yang terlalu besar) juga membuat agen lambat dan tidak dapat diprediksi. Lacak token per eksekusi, batasi anggaran per tugas, dan cache apa yang bisa Anda lakukan. Untuk sisi baris perintah, panduan kami tentang mengurangi biaya token agen memiliki tuas konkret. Saat Anda menguji jalur pemulihan terhadap mock, perhatikan juga jumlah panggilan. Agen yang berhasil tetapi melakukan empat puluh panggilan untuk mencapainya adalah insiden biaya yang menunggu untuk terjadi.
Mode kegagalan 5: tanpa pagar pembatas
Kegagalan yang paling menyakitkan adalah ketika agen melakukan persis seperti yang diperintahkan dan hasilnya tetap buruk. Ia mengirim email, menghapus catatan, atau menempatkan pesanan, karena tidak ada yang menghalangi keputusan model dan tindakan langsung. Forum SDK memiliki utas yang mudah diingat yang dibangun di sekitar agen yang mengirim email jam tiga pagi kepada bos seseorang. Lucu sekali, mahal dua kali.
Pagar pembatas adalah sabuk pengaman. Terapkan daftar izin untuk tindakan yang dapat diambil agen tanpa persetujuan. Lindungi panggilan yang merusak atau tidak dapat dibatalkan di balik konfirmasi manusia. Beri agen mode 'dry-run' yang menjelaskan apa yang akan dilakukannya tanpa benar-benar melakukannya. Kemudian uji bahwa pagar pembatas berfungsi: buat mock titik akhir yang memiliki efek samping, jalankan agen, dan pastikan ia melewati jalur konfirmasi daripada tindakan langsung. Panduan keamanan seperti OWASP Top 10 untuk aplikasi LLM adalah daftar periksa yang solid untuk apa yang harus dilindungi. Panduan tentang pagar pembatas agen AI membahas gerbang persetujuan dan kontrol radius ledakan secara mendalam.
Cara menyusun pengujian agen
Kelima mode memiliki satu bentuk pengujian yang sama, dan Anda dapat menggunakannya kembali:
- Tangkap skema alat yang dapat dipanggil agen Anda, sehingga Anda memiliki kontrak untuk ditegaskan.
- Buat mock setiap dependensi sehingga Anda mengontrol waktu, kode status, dan isi, serta menghindari efek samping yang sebenarnya.
- Arahkan agen melalui skenario, termasuk jalur yang tidak menyenangkan yang tidak akan dihasilkan oleh API langsung sesuai permintaan.
- Tegaskan apa yang dikirim agen dan bagaimana ia bereaksi: bentuk permintaan, perilaku pemulihan, jumlah panggilan, dan apakah pagar pembatas diaktifkan.
Jalankan loop itu untuk satu alat, lalu tambahkan yang berikutnya. Pengaturan ini akan terbayar dengan sendirinya pertama kali menangkap panggilan alat yang rusak sebelum pengguna melakukannya.
Daftar periksa keandalan agen
Sebelum agen masuk ke produksi, periksa daftar ini:
- Setiap panggilan alat divalidasi terhadap skema, dan pelanggaran kontrak akan menyebabkan kegagalan dalam pengujian.
- Respons 429, 500, dan batas waktu upstream disimulasikan, dan agen pulih dengan penundaan.
- Tindakan yang dicoba ulang bersifat idempoten, sehingga pengulangan tidak dapat melakukan penagihan ganda atau pengiriman ganda.
- Pengujian menegaskan struktur dan makna, bukan string yang persis sama, sehingga variasi normal tidak menyebabkan ketidakstabilan.
- Penggunaan token per eksekusi diukur, dan batas anggaran menghentikan perulangan yang tidak terkendali.
- Tindakan destruktif berada di balik daftar izin atau gerbang persetujuan manusia.
- Jalur pagar pembatas diuji dengan mock, bukan diasumsikan.
Centang ketujuh poin ini dan Anda telah menguji cara-cara agen rusak dalam produksi.
Di mana Apidog cocok (dan di mana tidak)
Jelaskan tentang tugas alat ini. Apidog bukanlah kerangka kerja agen, host model, atau harness evaluasi. Ia tidak membangun atau menjalankan agen Anda. Yang dilakukannya adalah memiliki lapisan API tempat agen Anda bergantung, dan di situlah tepatnya kegagalan ini berada.
Dalam praktiknya, itu berarti tiga hal. Anda merancang dan menyimpan kontrak untuk alat yang dipanggil agen Anda, sehingga Anda dapat memvalidasi permintaan keluar terhadapnya. Anda membuat mock dependensi tersebut dan memprogram respons kegagalan (429, 500, batas waktu, body yang salah format) yang tidak akan dihasilkan oleh API langsung sesuai permintaan, sehingga Anda dapat berlatih pemulihan. Dan Anda menulis penegasan pada respons (skema, bentuk, rentang, kunci yang wajib) yang bertahan dari output non-deterministik. Itulah kecocokan yang jujur: Apidog menguji API yang dipanggil agen Anda, menguji kegagalan yang perlu Anda tangani, dan memeriksa apa yang dikembalikan. Gambaran umum kami tentang pengujian AI agentik menempatkan ini dalam gambaran QA yang lebih luas.
Pertanyaan yang sering diajukan
Apakah keandalan agen adalah masalah model atau masalah rekayasa? Sebagian besar rekayasa. Pilihan model memang penting, tetapi kegagalan yang menyebabkan insiden (panggilan alat yang buruk, batas laju yang tidak ditangani, pagar pembatas yang hilang) adalah masalah integrasi dan pengujian yang dapat Anda selesaikan tanpa mengubah model.
Dapatkah saya menguji agen tanpa memanggil API nyata yang digunakannya? Ya, dan sebaiknya Anda melakukannya. Buat mock dependensi agar Anda dapat memaksa respons kesalahan, mengontrol waktu, dan menghindari efek samping. Itu adalah satu-satunya cara yang andal untuk menguji jalur pemulihan dan pagar pembatas.
Bagaimana cara menulis pengujian ketika output berubah setiap kali dijalankan? Tegaskan struktur dan makna alih-alih teks yang persis sama. Validasi respons terhadap skema, periksa bentuk panggilan alat, dan gunakan rentang untuk angka. Panduan menguji agen AI non-deterministik membahas hal ini secara rinci.
Apa yang harus saya uji terlebih dahulu? Pagar pembatas pada tindakan destruktif, kemudian pemulihan kesalahan. Kedua hal ini melindungi Anda dari kegagalan paling mahal: agen mengambil tindakan yang merugikan, atau agen berulang dan menguras anggaran Anda.
Mulai dengan satu mode kegagalan
Anda tidak harus menguji kelima mode sekaligus. Pilih salah satu yang paling membuat Anda takut, biasanya pagar pembatas atau pemulihan kesalahan, dan latih terhadap mock minggu ini. Program kegagalan, jalankan agen, dan perhatikan apa yang dilakukannya. Pertama kali Anda melihat agen Anda menangani 429 yang disimulasikan dengan penundaan yang bersih alih-alih loop yang menguras anggaran, Anda akan lebih memercayainya, dan untuk alasan yang lebih baik daripada demo hijau.
Unduh Apidog untuk merancang kontrak, menguji kegagalan, dan menegaskan respons yang dibutuhkan agen Anda.