Selasa sore. Dua belas giliran menjadi sesi debug, dan agen dengan percaya diri memberitahu saya bahwa endpoint /users kami merespons dalam empat puluh tujuh detik. Angka sebenarnya adalah empat puluh tujuh milidetik.
Saya telah mengejar bug ini selama dua hari. Setiap kali saya menambahkan pernyataan cetak (print statement) ke server MCP, jawaban agen bergeser cukup banyak sehingga membuat saya berpikir saya sudah mencapai sesuatu. Setiap kali saya menulis ulang prompt sistem, responsnya terdengar lebih masuk akal. Tidak ada yang benar.
Yang belum saya lakukan, sampai sore itu, adalah membuka jejak eksekusi (execution trace) yang sebenarnya dan melihat apa yang dilewatkan antara model dan alat. Itulah gunanya AI Agent Debugger Apidog. Saya telah menginstalnya tiga minggu sebelumnya dan melupakannya. Butuh dua belas menit untuk menemukan bug tersebut.
Inilah yang mengejutkan saya.
Bug yang Saya Kejar
Pengaturannya sederhana. Sebuah agen yang dibangun di atas GPT-5.5. Satu server MCP yang saya tulis dalam semalam akhir pekan, mengekspos alat get_response_time(endpoint) yang mengkueri pipeline metrik kami. Sebuah prompt sistem yang mungkin berisi empat puluh kata. Prompt pengguna: “Seberapa cepat endpoint /users?”
Agen itu menjawab dengan cepat. Menjawab dengan percaya diri. Menjawab dengan salah, setiap kali, dengan cara yang berbeda. Terkadang “endpoint merespons dalam 47 detik.” Terkadang “sekitar 0,05 detik.” Pernah, yang paling saya ingat, “kinerja dapat diterima.”
Saya telah melakukan hal-hal yang biasa Anda lakukan. Menambahkan logging ke server MCP. Membaca respons model token-demi-token. Membandingkan (diffing) prompt sistem. Mengumpat. Saya memiliki tiga jendela terminal terbuka dan satu halaman Notion berisi hipotesis yang gagal pada Selasa pagi.
Masalahnya dalam men-debug agen adalah bahwa bug jarang berada di tempat Anda mencari pertama kali. Bug bisa berada di prompt sistem, di pilihan model, di definisi alat, di parameter yang dilewatkan model ke alat, di data yang dikembalikan alat, atau di cara model menafsirkan data tersebut. Enam tempat. Log konsol hanya menunjukkan satu.
Apa yang Sebenarnya Ditampilkan Panel Jejak
Debugger Apidog terbuka menjadi tiga kolom. Sesi di kiri. Giliran di tengah. Jejak di kanan. Klik sesi mana pun dan kolom tengah akan menampilkan dialog: pesan pengguna, respons model, panggilan alat, hasil alat, respons model berikutnya. Klik giliran mana pun dan kolom kanan akan meluas menampilkan pohon eksekusi lengkap di bawahnya.
Pohon eksekusi (execution tree) adalah bagian yang selama ini saya lewatkan. Setiap langkah, secara berurutan:
- Prompt sistem sebagaimana diterima model
- Prompt pengguna sebagaimana diterima model
- Nama panggilan alat dan parameternya, dalam format JSON, persis seperti yang dikeluarkan model
- Payload hasil alat, dalam format JSON, persis seperti yang dikembalikan alat
- Respons model, dengan waktu dan token untuk giliran tersebut
Saya membuka sesi yang gagal. Panggilan alat tampak baik-baik saja: get_response_time(endpoint="/users"). Model telah memilih alat yang tepat dengan argumen yang benar.
Kemudian saya memperluas hasil alat.
{"value": 47, "p95": 89, "samples": 1240}
Itu dia. Pipeline metrik mengembalikan nilai dalam milidetik. Model mengasumsikan detik. 47 menjadi “47 detik” melalui halusinasi percaya diri yang tidak peduli mempertanyakan satuannya. Alat itu benar. Model itu salah. Prompt sistem saya tidak memiliki instruksi tentang satuan, dan respons alat tidak memiliki anotasi satuan.
Dua belas menit sejak membuka debugger. Dua hari saya menyalahkan prompt sistem.
Perbaikan Membutuhkan Enam Baris
Saya mengubah dua hal. Di server MCP, saya memperbarui bentuk respons:
{
"value": { "amount": 47, "unit": "ms" },
"p95": { "amount": 89, "unit": "ms" },
"samples": 1240
}
Kemudian saya menambahkan satu kalimat ke prompt sistem: “Hasil alat mengembalikan satuan secara eksplisit. Bacalah dengan cermat.”
Saya menjalankan prompt /users yang sama tiga kali lagi. Tiga sesi berbeda di panel kiri. Ketiganya dengan benar mengembalikan “endpoint merespons sekitar 47 ms” dengan rincian milidetik-ke-persentil dalam penalaran model. Biaya token delapan belas persen lebih rendah daripada percobaan saya yang gagal, mungkin karena model tidak menghasilkan prosa pemulihan di sekitar asumsi buruknya sendiri.
Saya menjalankan prompt yang sama pada Claude Opus 4.7 dalam sesi kedua, berdampingan. Hasilnya sama, biaya dua kali lipat, sedikit lebih bertele-tele. Saya tahu model mana yang akan masuk produksi.
Inilah bagian dari alat yang membuat saya menghormatinya. Bukan pencarian bug, yang seharusnya bisa dilakukan oleh debugger yang layak. Perbandingan model, dijalankan pada konfigurasi yang identik dengan metrik ringkasan di panel kiri: jumlah giliran, jumlah langkah, waktu, token, dolar. Saya telah melakukan perbandingan itu di Google Sheet selama enam bulan. Sekarang hanya butuh tiga klik.
Apa yang Selama Ini Saya Salah Pahami
Asumsi yang keliru adalah bahwa AI Agent Debugger adalah alat logging. Bukan. Alat logging menunjukkan apa yang terjadi. Debugger menunjukkan apa yang sebenarnya dipertukarkan oleh model dan alat, yang merupakan lapisan yang berbeda.
Jika Anda menulis agen dan Anda telah melakukan apa yang saya lakukan, yaitu membaca keluaran model dan menebak-nebak penyebab kegagalan, inilah yang ingin saya tegaskan. Anda tidak sedang men-debug agen. Anda sedang men-debug hipotesis Anda tentang agen tersebut. Itu adalah hal yang berbeda, dan hanya salah satunya yang akan membawa Anda pada perbaikan.
Hal yang saya tolak untuk internalisasi selama enam bulan adalah bahwa agen adalah sistem tertutup antara model, prompt, alat, dan respons alat. Bug selalu berada di salah satu dari keempat hal tersebut. Jika Anda dapat melihat keempatnya secara bersamaan, Anda dapat menemukan bug dalam dua belas menit. Jika tidak bisa, Anda bisa mengejarnya selama seminggu.
Hal lain yang diungkapkan debugger, yang tidak saya duga, adalah non-deterministik dalam agen saya sendiri. Saya menjalankan prompt yang sama lima kali setelah perbaikan, hanya untuk konfirmasi. Tiga kali dijalankan memanggil get_response_time sekali. Dua kali dijalankan memanggilnya dua kali, yang kedua kali dengan jalur endpoint dalam kasus (kapitalisasi) yang berbeda. Skema alat saya peka huruf besar/kecil. Saya tidak menyadarinya karena semua kasus uji yang gagal kebetulan menggunakan huruf kecil. Itu adalah bug kedua yang seharusnya saya rilis tanpa menyadarinya.
Analisis multi-jalankan (multi-run analysis) adalah fitur yang akan paling sering saya gunakan di masa mendatang. Klik Jalankan lima kali. Lihat panel sesi. Apa pun yang bervariasi di antara eksekusi adalah tempat agen Anda rapuh.
Coba Sendiri: Panduan Penyiapan Lengkap
Jika Anda menginginkan pengaturan yang sama dengan yang saya gunakan selama perburuan bug, berikut adalah alur dari instalasi baru hingga sesi debug yang berjalan. Lima layar, secara berurutan.
Langkah 1: Buat Sesi Debug Agen Baru
Buka Apidog dan klik AI Agent Debugger di bilah tab atas. Bagian atas halaman mengkonfigurasi model dan status jalankan.
- Pilih penyedia model di kiri (OpenAI, Anthropic, dan lainnya)
- Pilih model spesifik di tengah, misalnya
gpt-5.5 - URL Dasar (Base URL) terisi secara otomatis setelah penyedia dipilih, tidak perlu entri manual
- Klik Jalankan untuk memulai sesi
Langkah 2: Konfigurasi Prompt
Tab Prompts memiliki dua area masukan.
- Prompt Sistem: mendefinisikan peran agen, tujuan, batasan, dan aturan penggunaan alat
- Prompt Pengguna: masukan uji untuk sesi ini, misalnya “Apa itu Apidog?”
Klik Jalankan di kanan atas saat keduanya sudah diatur. Jika Anda ingin kotak masukan dibersihkan secara otomatis setelah setiap jalankan, centang Bersihkan setelah Kirim.
Langkah 3: Konfigurasi Alat
Tab Alat mencantumkan semua yang dapat dipanggil agen saat runtime. Angka pada tab adalah jumlah alat yang tersedia atau telah dikonfigurasi saat ini.
Alat bawaan disertakan dengan debugger. Nyalakan atau matikan sesuai kebutuhan.
| Alat | Fungsi |
|---|---|
bash |
Menjalankan perintah dalam sesi shell persisten |
web_fetch |
Mengambil konten web dan mengubahnya ke Markdown, teks, atau HTML |
read |
Membaca file teks, gambar, atau PDF |
edit |
Menerapkan penggantian string yang tepat pada file |
write |
Membuat atau menimpa file |
grep |
Mencari konten file dengan ekspresi reguler |
glob |
Menemukan file menggunakan pola glob |
kill_shell |
Mengatur ulang sesi shell saat ini |
Alat MCP menambahkan sistem eksternal atau kemampuan kustom melalui Server MCP. Tiga metode koneksi:
- STDIO: meluncurkan proses Server MCP lokal
- HTTP: menghubungkan ke Server MCP yang mendukung HTTP Streamable
- SSE: menghubungkan ke Server MCP berdasarkan Server-Sent Events
Server MCP yang memerlukan otentikasi menerima header permintaan atau alur OAuth 2.0. Setelah koneksi berhasil, pilih alat mana yang diekspos server ke agen.
Langkah 4: Konfigurasi Keterampilan, Otentikasi, dan Parameter Model
Tiga tab yang lebih kecil melengkapi pengaturan.
- Keterampilan (Skills): alur kerja yang dapat digunakan kembali untuk agen. Berguna untuk alur kerja proyek tetap, spesifikasi operasi tugas umum, dan mengurangi teks panjang yang berulang dalam prompt sistem. Keterampilan dimuat sesuai kebutuhan saat runtime.
- Otentikasi: kredensial yang diperlukan oleh layanan model atau layanan MCP.
- Pengaturan: parameter runtime model seperti Suhu (Temperature), Maksimum Token (Max Tokens), dan Top P. Parameter yang didukung bervariasi berdasarkan penyedia, jadi periksa apa yang sebenarnya diterima model Anda.
Langkah 5: Membaca Tiga Panel
Setelah mengklik Jalankan, sesi yang baru saja Anda buat muncul di panel kiri. Setiap sesi menampilkan ringkasan satu baris:
Session 3
1 turn · 1 step · 10s · 3.1k tokens · $0.02
gpt-5.5
- Panel Sesi (kiri): riwayat setiap eksekusi dengan metrik ringkasan
- Panel Giliran (tengah): setiap putaran dialog pengguna/model. Klik putaran untuk memuat detail eksekusinya di kanan.
- Panel Jejak (kanan): rantai eksekusi lengkap agen secara berurutan, termasuk prompt sistem dan pengguna, setiap panggilan model, proses berpikir model jika model mengeksposnya, panggilan alat MCP dan eksekusi Keterampilan kustom, parameter masukan alat, hasil, waktu yang digunakan, pesan kesalahan, dan keluaran akhir.
Ketika panggilan alat gagal atau model mengembalikan pengecualian, langkah yang gagal ada di panel Jejak dengan masukan dan keluarannya terlihat. Tidak perlu menyelam ke dalam log.
Langkah 6: Bandingkan Kinerja Model
Prompt yang sama, konfigurasi alat yang sama, model yang berbeda. Setiap eksekusi menciptakan sesi baru, dan panel kiri memungkinkan Anda membandingkannya secara berdampingan.
- Jumlah langkah eksekusi untuk tugas yang sama
- Model mana yang memilih alat lebih akurat
- Model mana yang memiliki waktu respons lebih rendah
- Model mana yang menjaga konsumsi token dan biaya lebih dapat diprediksi
Poin Penting
Dua hari proses debug menyusut menjadi satu sore, dan saya tidak belajar pelajaran tentang bug itu sendiri. Saya belajar tentang peralatannya. Alasan saya mengejar perbaikan yang salah adalah karena alat yang saya gunakan tidak menunjukkan apa yang perlu saya lihat. Saya memiliki keluaran model dan keluaran alat, dan tidak ada kerangka bersama untuk melihat keduanya. Kerangka bersama itulah intinya.
Jika Anda telah menulis lebih dari satu agen dan Anda belum membuka AI Agent Debugger Apidog, agen berikutnya yang Anda kirim akan memiliki bug yang berada di antara model dan alat. Anda akan menghabiskan seminggu untuk itu. Anda akan menulis halaman Notion berisi hipotesis yang gagal. Bug itu akan persis di tempat yang seharusnya ditunjukkan oleh debugger pada hari pertama.
Unduh Apidog dan buka pada agen berikutnya yang memberi Anda jawaban salah dengan suara percaya diri. Dua belas menit. Empat puluh tujuh milidetik, bukan empat puluh tujuh detik.
Referensi fitur lengkap, termasuk pengaturan transportasi MCP dan ketersediaan paket, tersedia di Apidog AI Agent Debugger: ketersediaan, cakupan, dan pengaturan.