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:

1. Prompt sistem
2. Prompt pengguna
3. Pemilihan model
4. Definisi tool
5. Parameter yang dikirim model ke tool
6. Payload hasil tool
7. 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:

1. Apakah prompt sistem benar-benar diterima model?
2. Apakah model memilih tool yang benar?
3. Apakah parameter tool sesuai?
4. 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:

1. Jalankan prompt yang sama minimal lima kali
2. Bandingkan session di panel kiri
3. Cari bagian yang berubah antar-run
4. 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:

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.