Agen Terus Berbohong Padaku. Sampai Aku Membuka AI Agent ...

Selasa sore. Dua hari saya men-debug agen yang dengan percaya diri menjawab bahwa endpoint /users merespons dalam 47 detik. Nilai sebenarnya: 47 milidetik.

Coba Apidog hari ini

Masalahnya bukan di endpoint, bukan di pipeline metrik, dan bukan di model secara langsung. Masalahnya ada di batas antara model dan tool: tool mengembalikan angka tanpa satuan, lalu model menebak satuannya.

Saya baru menemukan itu setelah membuka execution trace di AI Agent Debugger Apidog. Dalam 12 menit, bug yang saya kejar selama dua hari terlihat jelas.

Bug yang Saya Kejar

Setup-nya sederhana:

Agen berbasis GPT-5.5
Satu server MCP custom
Tool bernama get_response_time(endpoint)
Tool tersebut mengambil data dari pipeline metrik
Prompt pengguna: Seberapa cepat endpoint /users?

Respons agen berubah-ubah:

“Endpoint merespons dalam 47 detik.”
“Sekitar 0,05 detik.”
“Kinerja dapat diterima.”

Saya sudah mencoba langkah debug umum:

Menambahkan logging di server MCP
Membaca respons model token demi token
Membandingkan prompt sistem
Menulis ulang instruksi model
Menjalankan ulang prompt yang sama berkali-kali

Tetap tidak ketemu.

Masalah utama saat men-debug agen adalah bug bisa berada di banyak tempat:

Prompt sistem
Prompt pengguna
Pemilihan model
Definisi tool
Parameter yang dikirim model ke tool
Payload hasil tool
Interpretasi model terhadap hasil tool

Console log biasanya hanya menunjukkan satu atau dua bagian. Untuk agen, itu tidak cukup.

Yang Terlihat di Panel Trace

Debugger Apidog menampilkan debug session dalam tiga panel:

Panel kiri: daftar session
Panel tengah: turn atau giliran percakapan
Panel kanan: execution trace lengkap

Saat membuka session yang gagal, saya bisa melihat urutan eksekusi secara eksplisit:

Prompt sistem yang diterima model
Prompt pengguna yang diterima model
Nama tool yang dipanggil model
Parameter tool dalam JSON
Payload hasil tool dalam JSON
Respons akhir model
Waktu, token, dan biaya untuk eksekusi tersebut

Panggilan tool terlihat benar:

get_response_time(endpoint="/users")

Model memilih tool yang benar dan mengirim argumen yang benar.

Lalu saya membuka payload hasil tool:

{
  "value": 47,
  "p95": 89,
  "samples": 1240
}

Di situlah bug-nya.

Pipeline metrik mengembalikan nilai dalam milidetik, tetapi payload tidak menyebutkan satuan. Model mengasumsikan angka 47 sebagai detik.

Tool benar. Model salah menginterpretasikan hasil tool. Prompt sistem saya juga tidak memberi instruksi tentang satuan.

Perbaikannya: Buat Payload Tool Lebih Eksplisit

Saya mengubah response schema tool dari ini:

{
  "value": 47,
  "p95": 89,
  "samples": 1240
}

Menjadi ini:

{
  "value": {
    "amount": 47,
    "unit": "ms"
  },
  "p95": {
    "amount": 89,
    "unit": "ms"
  },
  "samples": 1240
}

Lalu saya menambahkan satu kalimat ke prompt sistem:

Hasil tool mengembalikan satuan secara eksplisit. Bacalah dengan cermat.

Setelah itu saya menjalankan prompt yang sama tiga kali:

Seberapa cepat endpoint /users?

Ketiga session mengembalikan jawaban yang benar: endpoint merespons sekitar 47 ms.

Pelajarannya sederhana: untuk tool yang dipakai agen, jangan hanya mengembalikan angka. Kembalikan konteks yang dibutuhkan model untuk menafsirkan angka itu.

Contoh payload yang lebih aman:

{
  "metric": "response_time",
  "endpoint": "/users",
  "value": {
    "amount": 47,
    "unit": "ms"
  },
  "percentile": {
    "p95": {
      "amount": 89,
      "unit": "ms"
    }
  },
  "samples": 1240
}

Pola Debug yang Lebih Praktis

Sebelum mengubah prompt, cek dulu empat hal ini di trace:

Apakah prompt sistem benar-benar diterima model?
Apakah model memilih tool yang benar?
Apakah parameter tool sesuai?
Apakah payload tool cukup jelas untuk diinterpretasikan model?

Dalam kasus saya, nomor 1 sampai 3 benar. Masalahnya ada di nomor 4.

Itu sebabnya menambahkan logging di server MCP tidak cukup. Log server hanya menunjukkan bahwa tool mengembalikan data. Trace menunjukkan bagaimana model membaca data itu.

Yang Saya Salah Pahami

Saya awalnya menganggap AI Agent Debugger sebagai alat logging. Ternyata bukan itu poin utamanya.

Logging menjawab:

Apa yang terjadi di server?

Debugger menjawab:

Apa yang sebenarnya dipertukarkan antara model, prompt, tool, dan hasil tool?

Untuk agen AI, pertanyaan kedua jauh lebih penting.

Agen adalah sistem yang terdiri dari:

Model
Prompt
Tool
Respons tool

Bug biasanya muncul di batas antarbagian itu. Kalau Anda hanya melihat output akhir model, Anda sedang men-debug asumsi, bukan sistemnya.

Bug Kedua: Non-determinism

Setelah memperbaiki satuan, saya menjalankan prompt yang sama lima kali.

Hasilnya:

Tiga run memanggil get_response_time satu kali
Dua run memanggil get_response_time dua kali
Pada beberapa run, endpoint dikirim dengan kapitalisasi berbeda

Tool saya ternyata case-sensitive. Semua test case sebelumnya memakai huruf kecil, jadi bug itu tidak terlihat.

Ini pola debug yang sekarang saya pakai:

Jalankan prompt yang sama minimal lima kali
Bandingkan session di panel kiri
Cari bagian yang berubah antar-run
Perbaiki bagian yang membuat agen rapuh

Jika prompt yang sama menghasilkan tool call yang berbeda, parameter berbeda, atau urutan langkah berbeda, berarti ada area yang perlu distabilkan.

Coba Sendiri: Setup AI Agent Debugger Apidog

Berikut alur dari instalasi baru sampai session debug berjalan.

Langkah 1: Buat Session Debug Agen Baru

Buka Apidog, lalu klik AI Agent Debugger di tab atas.

Konfigurasikan bagian model:

Pilih provider model, misalnya OpenAI atau Anthropic
Pilih model spesifik, misalnya gpt-5.5
Base URL akan terisi otomatis setelah provider dipilih
Klik Jalankan untuk memulai session

Langkah 2: Konfigurasi Prompt

Buka tab Prompts.

Isi dua bagian utama:

Prompt Sistem: peran agen, tujuan, batasan, dan aturan penggunaan tool
Prompt Pengguna: input uji untuk session ini

Contoh prompt sistem:

Anda adalah agen observability internal.
Gunakan tool yang tersedia untuk membaca metrik.
Jika tool mengembalikan satuan, gunakan satuan tersebut secara eksplisit.
Jangan menebak satuan.

Contoh prompt pengguna:

Seberapa cepat endpoint /users?

Klik Jalankan di kanan atas.

Jika ingin input dibersihkan otomatis setelah setiap run, aktifkan Bersihkan setelah Kirim.

Langkah 3: Konfigurasi Tool

Tab Alat berisi semua tool yang dapat dipanggil agen saat runtime.

Debugger menyediakan beberapa tool bawaan:

Tool	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

Untuk tool custom, gunakan MCP Tool. Ada tiga metode koneksi:

STDIO: menjalankan server MCP lokal sebagai proses
HTTP: menghubungkan ke server MCP dengan HTTP Streamable
SSE: menghubungkan ke server MCP berbasis Server-Sent Events

Jika server MCP membutuhkan autentikasi, konfigurasikan header request atau OAuth 2.0. Setelah koneksi berhasil, pilih tool mana yang diekspos ke agen.

Langkah 4: Konfigurasi Skills, Autentikasi, dan Parameter Model

Ada tiga tab tambahan yang perlu dicek.

Skills

Skills adalah workflow yang dapat digunakan ulang oleh agen.

Gunakan skills untuk:

Workflow proyek yang sering dipakai
Instruksi operasi yang panjang
Mengurangi prompt sistem yang terlalu besar
Memuat instruksi hanya saat dibutuhkan runtime

Otentikasi

Gunakan tab Otentikasi untuk kredensial yang dibutuhkan oleh:

Provider model
Server MCP
Layanan eksternal yang dipanggil tool

Pengaturan

Gunakan tab Pengaturan untuk parameter runtime model, seperti:

Temperature
Max Tokens
Top P

Parameter yang tersedia bergantung pada provider dan model. Pastikan parameter yang Anda atur memang didukung oleh model yang dipakai.

Langkah 5: Baca Tiga Panel Debug

Setelah klik Jalankan, session baru muncul di panel kiri.

Contoh ringkasan session:

Session 3
1 turn · 1 step · 10s · 3.1k tokens · $0.02
gpt-5.5

Gunakan panel berikut saat debug:

Panel Sesi kiri: riwayat eksekusi dan metrik ringkasan
Panel Giliran tengah: dialog pengguna/model per turn
Panel Trace kanan: rantai eksekusi lengkap agen

Panel trace dapat menampilkan:

Prompt sistem
Prompt pengguna
Panggilan model
Proses berpikir model jika diekspos oleh model
Panggilan tool MCP
Eksekusi custom skill
Parameter input tool
Payload hasil tool
Waktu eksekusi
Error message
Output akhir

Saat tool gagal atau model mengembalikan exception, buka langkah yang gagal di panel trace. Input dan output-nya bisa langsung dilihat tanpa masuk ke log server.

Langkah 6: Bandingkan Model

Untuk membandingkan model, gunakan setup yang sama:

Prompt sama
Tool sama
Parameter sedekat mungkin sama
Model berbeda

Setiap run membuat session baru. Dari panel kiri, bandingkan:

Jumlah step untuk tugas yang sama
Model mana yang memilih tool dengan lebih akurat
Model mana yang lebih cepat
Konsumsi token
Biaya
Stabilitas output antar-run

Dalam kasus saya, prompt yang sama dijalankan pada GPT-5.5 dan Claude Opus 4.7. Hasilnya sama, tetapi biaya dan verbosity berbeda. Itu cukup untuk membantu memilih model untuk produksi.

Checklist Debug Agen

Gunakan checklist ini setiap kali agen memberi jawaban salah:

[ ] Prompt sistem terlihat benar di trace
[ ] Prompt pengguna terlihat benar di trace
[ ] Model memilih tool yang benar
[ ] Parameter tool sesuai schema
[ ] Payload tool berisi satuan dan konteks
[ ] Model tidak menebak nilai yang tidak ada di payload
[ ] Prompt yang sama stabil saat dijalankan beberapa kali
[ ] Perbandingan model dilakukan dengan konfigurasi identik

Untuk tool response, hindari payload ambigu seperti ini:

{
  "value": 47
}

Lebih baik gunakan payload eksplisit:

{
  "metric": "response_time",
  "endpoint": "/users",
  "value": {
    "amount": 47,
    "unit": "ms"
  }
}

Poin Penting

Bug agen sering berada di antara model dan tool, bukan hanya di kode backend atau prompt.

Dalam kasus ini, bug dua hari selesai setelah melihat execution trace:

Tool mengembalikan 47
Satuan tidak disebutkan
Model menafsirkan sebagai detik
Response schema diperbaiki
Prompt sistem diberi instruksi singkat
Output menjadi stabil

Jika Anda sedang membangun agen dengan MCP tool, jangan hanya mengandalkan log server. Lihat seluruh pertukaran antara prompt, model, tool call, dan tool result.

Unduh Apidog dan jalankan debugger pada agen berikutnya yang memberi jawaban salah dengan percaya diri.

Referensi fitur lengkap, termasuk pengaturan transportasi MCP dan ketersediaan paket, tersedia di Apidog AI Agent Debugger: ketersediaan, cakupan, dan pengaturan.

推荐订阅源

DEV Community