Mengapa Agen AI Gagal di Produksi (dan Cara Menguji Setiap Modus Kegagalan)

Agen Anda mungkin bekerja sempurna saat demo: membaca tiket, memanggil tiga API, lalu memposting ringkasan. Namun di produksi, agen bisa mengirim email ganda, menghabiskan anggaran token dalam loop percobaan ulang, atau meneruskan payload yang tidak dapat diproses frontend.

Coba Apidog hari ini

Kesenjangan antara prototipe dan agen yang andal biasanya bukan pada modelnya, melainkan pada panggilan API. Agen adalah loop pemanggilan alat (tool calling), dan setiap alat pada akhirnya adalah permintaan HTTP yang dapat gagal, dibatasi, kehabisan waktu, atau mengembalikan respons di luar kontrak. Karena itu, uji integrasi API agen seperti Anda menguji API produksi biasa.

Keandalan agen dapat diuji secara sistematis. Panduan ini membahas lima mode kegagalan utama serta cara membuat skenario pengujiannya di batas API menggunakan Apidog.

Agen gagal di batas API, bukan di prompt

Saat agen bermasalah di produksi, respons pertama sering kali adalah mengubah prompt. Ini kadang membantu, tetapi banyak kegagalan terjadi setelah model memilih alat.

Satu langkah agen biasanya melibatkan alur berikut:

Model memilih alat
  → aplikasi membuat request HTTP
  → layanan eksternal mengembalikan respons
  → aplikasi mengirim hasil ke model

Tiga dari empat langkah tersebut adalah integrasi API biasa. Jika API lambat, mengembalikan 429, berubah skema, atau mengirim body tidak valid, model akan bernalar berdasarkan input yang buruk dan dapat mengambil tindakan yang salah dengan percaya diri.

Pertanyaan yang perlu dijawab bukan:

Apakah model cukup pintar?

Tetapi:

Sudahkah setiap jalur kegagalan pada panggilan API agen diuji?

Berikut lima mode kegagalan yang perlu Anda latih sebelum merilis agen.

Mode kegagalan 1: panggilan alat melanggar kontrak

Kegagalan paling umum adalah model menghasilkan argumen alat yang tidak cocok dengan kontrak API:

• bidang wajib tidak dikirim;
• tipe data salah;
• nilai enum tidak valid;
• parameter masuk akal secara bahasa, tetapi tidak valid secara bisnis;
• endpoint benar, tetapi argumennya salah.

Contoh: agen reservasi memanggil POST /reservations dengan nilai berikut:

{
  "guests": "two"
}

Padahal API mengharapkan:

{
  "guests": 2
}

API mungkin mengembalikan 400. Lebih buruk lagi, API dapat mengembalikan 200 dengan status kesalahan tersembunyi di dalam body, lalu agen melanjutkan proses seolah reservasi berhasil.

Cara mengujinya

1. Definisikan skema untuk setiap alat yang dapat dipanggil agen.
2. Validasi request keluar terhadap skema tersebut.
3. Jadikan pelanggaran kontrak sebagai kegagalan eksplisit dalam pengujian.
4. Uji kasus tipe data salah, bidang hilang, enum tidak valid, dan nilai di luar batas.

Contoh kontrak sederhana:

{
  "type": "object",
  "required": ["date", "guests"],
  "properties": {
    "date": {
      "type": "string",
      "format": "date"
    },
    "guests": {
      "type": "integer",
      "minimum": 1
    }
  },
  "additionalProperties": false
}

Untuk implementasi lebih detail, lihat panduan menguji panggilan alat agen AI dan menguji agen yang memanggil API Anda.

Langkah praktisnya: impor atau buat kontrak alat di Apidog, jalankan agen terhadap kontrak tersebut, lalu periksa kegagalan validasi per bidang.

Mode kegagalan 2: error upstream dan batas laju

Setiap layanan eksternal dapat mengembalikan:

• 429 Too Many Requests;
• 500 Internal Server Error;
• timeout;
• koneksi terputus;
• respons lambat;
• body respons tidak valid.

Agen yang rapuh akan berhenti pada error pertama atau mencoba ulang tanpa batas. Agen yang andal menerapkan batas percobaan ulang, jeda, jitter, dan penghentian yang jelas.

Diskusi tentang pola pemulihan kesalahan agen menunjukkan bahwa masalah ini sangat umum pada implementasi agen.

Skenario mock yang harus diuji

Jangan hanya menguji API yang sehat. Buat mock dengan urutan respons seperti ini:

Request 1 → 429 + Retry-After: 2
Request 2 → 500
Request 3 → 200

Lalu verifikasi bahwa agen:

1. membaca header Retry-After;
2. menunggu sebelum mencoba ulang;
3. menambahkan jitter agar retry tidak serentak;
4. berhenti setelah jumlah retry maksimum;
5. tidak mengirim tindakan berulang untuk operasi yang tidak idempoten;
6. membuka circuit breaker jika layanan terus gagal.

Contoh kebijakan retry:

const retryPolicy = {
  maxAttempts: 3,
  baseDelayMs: 1000,
  maxDelayMs: 10000,
  jitter: true
};

Untuk operasi yang membuat efek samping, gunakan kunci idempoten:

POST /payments
Idempotency-Key: payment_01HQ...

Dengan kunci ini, retry tidak seharusnya membuat pembayaran, email, atau pesanan kedua. Baca panduan tentang kunci idempoten untuk pola implementasinya.

Simulasikan juga pembatasan laju berdasarkan panduan apa arti respons batas laju terlampaui. Untuk retry, timeout, delay, dan circuit breaker, gunakan referensi pemulihan kesalahan agen AI.

Mode kegagalan 3: output non-deterministik

Menetapkan suhu ke nol tidak selalu menghasilkan output yang identik secara byte. Perbedaan perangkat keras, batching, perubahan sisi penyedia, dan detail runtime dapat tetap menghasilkan variasi. Diskusi vLLM tentang seed dan suhu menunjukkan bahwa reproduktifitas penuh tidak sesederhana menetapkan satu parameter.

Jangan menulis pengujian seperti ini:

expect(agentReply).toBe("Pesanan Anda berhasil dibuat.");

Pengujian seperti itu mudah flaky. Saat test menjadi tidak stabil, tim cenderung mengabaikannya. Pelajari penyebabnya di artikel apa yang menyebabkan pengujian tidak stabil.

Uji struktur dan makna, bukan teks persis

Gunakan assertion yang memeriksa:

• skema JSON;
• bidang wajib;
• bidang yang tidak boleh ada;
• target dan bentuk panggilan alat;
• rentang nilai numerik;
• status bisnis yang diharapkan.

Contoh:

expect(result).toMatchObject({
  status: "success"
});

expect(result.total).toBeGreaterThanOrEqual(0);
expect(result.total).toBeLessThanOrEqual(cart.total);
expect(result).not.toHaveProperty("internal_error");

Untuk output terstruktur, validasi respons terhadap JSON Schema:

{
  "type": "object",
  "required": ["summary", "priority"],
  "properties": {
    "summary": { "type": "string", "minLength": 1 },
    "priority": { "enum": ["low", "medium", "high"] }
  }
}

Strategi lengkap tersedia di menguji agen AI non-deterministik. Jika agen menyimpan state, pelajari juga cara kerja memori agen, karena memori menambah sumber variasi pada hasil pengujian.

Mode kegagalan 4: biaya tidak terkendali

Agen bekerja dalam loop, dan setiap iterasi memiliki biaya. Satu agen yang gagal berhenti saat retry dapat mengubah biaya kecil menjadi tagihan besar dalam semalam.

Biaya juga merupakan masalah keandalan karena loop berlebihan membuat agen:

• lebih lambat;
• sulit diprediksi;
• lebih sering mencapai batas laju;
• lebih rentan gagal pada tahap berikutnya.

Tambahkan batas biaya ke pengujian

Lacak metrik berikut per eksekusi:

- jumlah tool call
- jumlah retry
- token input
- token output
- total token
- waktu eksekusi
- biaya estimasi

Contoh assertion anggaran:

expect(metrics.toolCalls).toBeLessThanOrEqual(8);
expect(metrics.retryCount).toBeLessThanOrEqual(3);
expect(metrics.totalTokens).toBeLessThanOrEqual(12000);

Jika agen berhasil menyelesaikan tugas tetapi melakukan 40 panggilan API, itu tetap merupakan regresi yang perlu ditangani.

Terapkan juga:

1. batas token per tugas;
2. batas jumlah tool call;
3. batas durasi workflow;
4. caching untuk data yang tidak berubah;
5. penghentian eksplisit saat anggaran habis.

Untuk pengoptimalan berbasis CLI, lihat panduan mengurangi biaya token agen.

Mode kegagalan 5: tidak ada pagar pembatas

Kegagalan paling mahal terjadi saat agen menjalankan instruksi dengan benar, tetapi tindakan tersebut tidak seharusnya dilakukan tanpa kontrol tambahan.

Contohnya:

• mengirim email ke pelanggan;
• menghapus data;
• membuat pesanan;
• melakukan refund;
• mengubah akses pengguna;
• memposting konten publik.

Pagar pembatas (guardrails) memisahkan keputusan model dari tindakan yang berdampak.

Terapkan kontrol tindakan

Gunakan kombinasi berikut:

• daftar izin untuk aksi yang dapat dilakukan otomatis;
• konfirmasi manusia untuk tindakan destruktif;
• mode dry-run;
• batas nilai transaksi;
• pembatasan lingkungan, misalnya hanya sandbox;
• audit log untuk setiap tool call.

Contoh keputusan aksi:

if (action.type === "send_email" && !approval.granted) {
  return {
    status: "requires_approval",
    message: "Email belum dikirim. Menunggu persetujuan manusia."
  };
}

Untuk mode dry-run:

if (mode === "dry-run") {
  return {
    action: "delete_record",
    target: recordId,
    executed: false
  };
}

Kemudian uji guardrail dengan mock endpoint yang memiliki efek samping. Pastikan agen masuk ke jalur persetujuan, bukan langsung memanggil endpoint tindakan.

Gunakan OWASP Top 10 untuk aplikasi LLM sebagai daftar periksa keamanan. Untuk implementasi gerbang persetujuan dan pembatasan radius dampak, lihat panduan pagar pembatas agen AI.

Cara menyusun pengujian agen

Kelima mode kegagalan tersebut dapat menggunakan pola pengujian yang sama.

1. Tangkap kontrak alat
   
   Dokumentasikan input, output, error, dan efek samping untuk setiap alat.

2. Mock semua dependensi eksternal
   
   Kontrol status HTTP, delay, timeout, header, dan body respons tanpa memicu efek samping nyata.

3. Jalankan skenario normal dan gagal
   
   Jangan hanya menjalankan happy path. Paksa API mengembalikan 429, 500, timeout, body rusak, dan respons di luar skema.

4. Assert request dan perilaku agen
   
   Periksa bentuk request, jumlah retry, penggunaan token, pemanggilan tool, dan aktivasi guardrail.

Contoh matriks skenario:

Skenario	Respons mock	Assertion utama
Parameter tidak valid	400	Agen berhenti dan melaporkan error kontrak
Batas laju	429 + Retry-After	Agen menunggu dan retry terbatas
Upstream gagal	500 tiga kali	Agen membuka circuit breaker atau gagal dengan jelas
Respons rusak	JSON tidak sesuai skema	Agen tidak meneruskan payload ke langkah berikutnya
Aksi destruktif	Endpoint tersedia	Agen meminta persetujuan sebelum eksekusi
Loop berlebihan	Respons retry berulang	Agen berhenti saat anggaran call/token tercapai

Mulai dari satu alat, lalu tambahkan alat berikutnya. Pendekatan ini biasanya membayar dirinya sendiri saat Anda menemukan request rusak sebelum pengguna menemukannya.

Daftar periksa keandalan agen

Sebelum merilis agen ke produksi, pastikan semua poin berikut terpenuhi:

• [ ] Setiap tool call tervalidasi terhadap skema.
• [ ] Pelanggaran kontrak menyebabkan test gagal.
• [ ] Respons 429, 500, dan timeout telah disimulasikan.
• [ ] Retry memiliki delay, jitter, dan batas percobaan.
• [ ] Tindakan yang di-retry bersifat idempoten.
• [ ] Test memeriksa struktur dan makna, bukan string persis.
• [ ] Token, jumlah tool call, dan anggaran per tugas diukur.
• [ ] Tindakan destruktif memerlukan allowlist atau persetujuan manusia.
• [ ] Jalur guardrail diuji menggunakan mock.
• [ ] Tidak ada efek samping nyata saat menjalankan test.

Jika ketujuh area utama ini sudah diuji, Anda telah mencakup sebagian besar cara agen gagal di produksi.

Di mana Apidog cocok, dan di mana tidak

Apidog bukan framework agen, host model, atau harness evaluasi LLM. Apidog tidak membangun atau menjalankan agen Anda.

Perannya ada pada lapisan API yang dipanggil agen:

1. merancang dan menyimpan kontrak API alat;
2. memvalidasi request agen terhadap kontrak;
3. membuat mock untuk respons 429, 500, timeout, atau body salah format;
4. memeriksa skema, bentuk, rentang nilai, dan bidang wajib dalam respons.

Dengan kata lain, Apidog membantu Anda menguji API yang dipanggil agen, kegagalan yang harus ditangani agen, serta respons yang diterima agen. Untuk konteks QA yang lebih luas, baca pengujian AI agentik.

Pertanyaan yang sering diajukan

Apakah keandalan agen adalah masalah model atau rekayasa?

Sebagian besar adalah masalah rekayasa. Pilihan model penting, tetapi insiden seperti tool call rusak, rate limit yang tidak ditangani, retry tanpa batas, dan guardrail yang hilang adalah masalah integrasi yang dapat diuji tanpa mengganti model.

Dapatkah saya menguji agen tanpa memanggil API nyata?

Ya, dan sebaiknya lakukan itu. Mock memungkinkan Anda memaksa error, mengontrol waktu respons, dan menghindari efek samping. Ini adalah cara paling andal untuk menguji jalur pemulihan dan guardrail.

Bagaimana cara menguji output yang berubah setiap kali dijalankan?

Assert struktur dan makna, bukan teks persis. Validasi skema respons, bentuk tool call, bidang wajib, dan rentang nilai. Lihat panduan menguji agen AI non-deterministik untuk detailnya.

Apa yang sebaiknya diuji terlebih dahulu?

Mulai dari guardrail untuk tindakan destruktif dan pemulihan error. Keduanya melindungi Anda dari dua kegagalan paling mahal: agen melakukan tindakan merugikan atau agen berulang hingga menguras anggaran.

Mulai dengan satu mode kegagalan

Anda tidak perlu menguji kelima mode sekaligus. Pilih satu risiko terbesar minggu ini—biasanya guardrail atau pemulihan error—lalu buat mock untuk skenario tersebut.

Program kegagalannya, jalankan agen, dan ukur responsnya:

Apakah agen berhenti?
Apakah ia mencoba ulang dengan benar?
Apakah ia menghindari tindakan ganda?
Apakah ia meminta persetujuan?
Apakah ia tetap berada dalam anggaran?

Saat agen dapat menangani 429 yang disimulasikan dengan delay yang benar, atau menahan email sampai ada persetujuan manusia, Anda memiliki alasan teknis untuk memercayainya—bukan hanya karena demo terlihat hijau.

Unduh Apidog untuk merancang kontrak, membuat mock kegagalan, dan memvalidasi respons yang dibutuhkan agen Anda.