Log Panggilan Alat Agen AI: Apa yang Perlu Dicatat di Setiap Permintaan

Observabilitas Panggilan Alat Agen AI: Dari Jejak ke Pengujian Regresi

Seorang pengguna melaporkan bahwa agen “melakukan sesuatu yang aneh”. Log Anda hanya menunjukkan bahwa agen memanggil alat dan menerima 200, tetapi tidak menjelaskan argumen, target pesanan, alasan pemilihan alat, atau respons yang memengaruhi keputusan berikutnya.

Coba Apidog hari ini

INFO  agent run started
INFO  calling tool: updateOrder
INFO  tool returned 200
INFO  agent run completed

Sistem agen sering gagal dengan cara yang baru masuk akal setelah investigasi. Karena itu, log bukan sekadar output operasional—log adalah produk debugging Anda. Artikel ini menjelaskan cara mencatat setiap panggilan alat, menghubungkan keputusan model ke permintaan HTTP, menyunting data sensitif, dan mengubah jejak gagal menjadi pengujian regresi.

Untuk sisi layanan, lihat panduan observabilitas API. Setelah memiliki jejak, Apidog membantu Anda memutar ulang panggilan buruk ke endpoint yang sama dan memverifikasi perilakunya.

Hubungkan tiga lapisan dalam satu jejak

Setiap eksekusi agen menghasilkan peristiwa di tiga lapisan:

1. Penalaran — konteks yang dilihat model, alat yang tersedia, alat yang dipilih, dan argumennya.
2. Alat — validasi argumen, kebijakan, pemetaan ke HTTP, serta penanganan hasil.
3. HTTP — metode, URL, header, body, status, latensi, dan percobaan ulang.

Masalah hampir selalu melintasi lapisan:

• Agen memakai ID pelanggan salah: keputusan model baru terlihat pada URL atau body HTTP.
• API mengembalikan 200 dengan body kosong: masalah HTTP dapat muncul sebagai keputusan agen yang aneh beberapa langkah kemudian.
• Dua eksekusi tumpang tindih: korelasi berdasarkan timestamp saja cepat menjadi tidak andal.

Gunakan aturan berikut:

• Satu trace_id untuk seluruh eksekusi agen.
• Satu span_id untuk setiap panggilan alat.
• Tambahkan keduanya pada setiap catatan di ketiga lapisan.

Jejak OpenTelemetry sudah memodelkan struktur ini. Gunakan pula konvensi semantik GenAI OpenTelemetry agar atribut Anda portabel.

Catat data yang benar pada setiap panggilan alat

Satu catatan panggilan alat yang dapat diaudit dapat berbentuk seperti ini:

{
  "trace_id": "run_01J8ZK3M2Q",
  "span_id": "call_004",
  "parent_span_id": "call_003",
  "timestamp": "2026-08-26T14:03:11.482Z",
  "agent": "billing",
  "step": 4,

  "tool_name": "refundOrder",
  "tool_args": { "orderId": "ord_92", "amount": 1200, "reason": "duplicate" },
  "tools_available": ["getOrder", "listOrders", "refundOrder", "voidInvoice"],

  "http": {
    "method": "POST",
    "url": "/v1/orders/ord_92/refund",
    "request_body_hash": "sha256:1f4c...",
    "status": 200,
    "duration_ms": 412,
    "retry_count": 1,
    "idempotency_key": "9f2b7c14-6d3a-4b18"
  },

  "outcome": "success",
  "tokens": { "prompt": 8420, "completion": 96 },
  "policy": { "approval_required": true, "approved_by": "user_31", "dry_run": false }
}

Prioritaskan lima bidang berikut:

• tool_args: catat argumen yang dihasilkan model sebelum normalisasi oleh eksekutor. Ini adalah bukti utama saat agen memakai ID atau nilai yang salah.
• tools_available: jelaskan mengapa pemilihan alat tampak ganjil. Jika model memilih refundOrder, Anda perlu tahu alternatif yang tersedia saat itu.
• retry_count: bedakan API lambat dari API yang gagal dua kali lalu berhasil.
• outcome: gunakan enum eksplisit seperti success, failed, timed_out, blocked_by_policy, atau rejected_by_human. Jangan hanya menyimpulkan hasil dari kode HTTP.
• policy: simpan status persetujuan, pelaksana persetujuan, dan mode dry_run. Panggilan yang diblokir oleh kebijakan adalah penjaga yang bekerja, bukan otomatis kegagalan. Untuk implementasinya, lihat penjaga agen AI.

Catat keputusan model, bukan hanya tindakan

Panggilan alat menunjukkan apa yang terjadi; konteks keputusan menjelaskan mengapa itu terjadi.

Simpan data berikut pada catatan proses:

• Definisi alat atau hash definisinya. Perubahan kecil pada deskripsi alat dapat menggeser pemilihan alat secara besar. Bandingkan hash antara eksekusi baik dan buruk. Lihat desain skema alat untuk agen.
• Model dan konfigurasi. Catat ID model, suhu, dan versi prompt. Perilaku dapat berubah antarversi model tanpa ada perubahan pada kode Anda.
• Ukuran konteks. Menyimpan prompt penuh mahal dan sering sensitif. Simpan minimal jumlah token dan hash prompt. Prompt yang dua kali lebih besar biasanya menandakan konteks yang tidak semestinya masuk.
• Hasil alat mentah. Jika eksekutor memangkas respons sebelum memberikannya kepada model, simpan payload asli dalam jejak. Jika tidak, Anda tidak dapat membedakan data API yang hilang dari data yang terbuang oleh aplikasi. Lihat cara menjaga respons alat di luar jendela konteks.

Sunting data sebelum disimpan

Jejak agen dapat berisi request, konteks, dan data pribadi. Terapkan empat aturan berikut.

1. Jangan simpan kredensial

Hapus:

• Header Authorization
• API key
• Cookie
• URL bertanda tangan

Simpan pengenal kredensial, seperti ID key, bukan nilainya. Pengenal itu membantu Anda mengetahui agen atau identitas mana yang bertindak tanpa mengekspos rahasia. Praktik ini sejalan dengan panduan API key hak istimewa paling rendah untuk agen.

2. Sunting di batas pencatatan

Jangan mengandalkan penyaringan saat query. Pada saat itu, rahasia mungkin sudah tersimpan, direplikasi, atau dicadangkan. Sunting data di middleware logging sebelum catatan keluar dari proses.

3. Hash body yang tidak boleh disimpan

Hash body request memungkinkan Anda membuktikan dua panggilan identik tanpa menyimpan payload. Ini sangat berguna untuk investigasi penulisan duplikat.

4. Gunakan retensi bertingkat

Contoh kebijakan yang praktis:

• Jejak penuh: 7 hari.
• Ringkasan terstruktur yang sudah disunting: 1 tahun.
• Prompt dan body mentah: hanya bila diperlukan untuk investigasi.

Sebagian besar debugging terjadi dalam beberapa hari, sedangkan pertanyaan audit datang beberapa bulan kemudian.

Ubah jejak gagal menjadi pengujian

Jejak yang baik memberi Anda kasus uji realistis.

1. Ambil panggilan alat dari eksekusi gagal.
2. Putar ulang request terhadap API.
3. Verifikasi perbaikan.
4. Simpan replay tersebut sebagai pengujian regresi di CI.

Di Apidog, Anda dapat membangun ulang request gagal sebagai kasus tersimpan, menambahkan assertion untuk perilaku yang diperbaiki, lalu menjalankannya di CI. Insiden satu kali berubah menjadi cakupan permanen.

Jejak juga menunjukkan mock yang benar-benar Anda butuhkan: endpoint yang paling sering dipanggil agen dan status gagal yang benar-benar terjadi. Bangun mock dari data tersebut, bukan dari tebakan. Lihat panduan menjalankan agen terhadap mock, bukan produksi.

Pantau juga perubahan mingguan pada:

• Distribusi pemilihan alat.
• Tingkat retry per endpoint.
• Jumlah panggilan per tugas selesai.
• Persentase proses yang diblokir oleh kebijakan.

Perubahan lambat pada metrik ini sering muncul sebelum menjadi insiden. Tambahkan pemeriksaan kontrak untuk menangkap perubahan upstream, seperti dijelaskan dalam pengujian kontrak API.

Tiga investigasi yang harus dapat dijawab oleh jejak

“Agen menagih pelanggan yang salah”

Periksa:

• tool_args dari model.
• URL HTTP yang sudah di-resolve.
• Hasil alat pada langkah sebelumnya.

Sering kali hasil pencarian sebelumnya memuat lebih dari satu kecocokan dan model memilih entri pertama. Jejak harus menunjukkan hasil ambigu tersebut serta pilihan model.

“Ini berhenti berfungsi pada hari Selasa”

Bandingkan eksekusi baik dan buruk berdasarkan:

• ID model.
• Hash set alat.
• Versi prompt.
• Ukuran respons rata-rata.

Salah satu dari empat bidang ini biasanya menunjukkan perubahan yang memicu regresi.

“Apakah tindakan ini disetujui?”

Blok policy harus menjawabnya langsung:

{
  "approval_required": true,
  "approved_by": "user_31",
  "approved_at": "2026-08-26T14:03:10.001Z"
}

Jangan merekonstruksi persetujuan setelah insiden. Tulis saat keputusan dibuat.

Sampling: apa yang wajib disimpan

Jejak penuh untuk setiap proses dapat mahal pada volume tinggi. Namun, lalu lintas agen tidak seragam.

Selalu simpan penuh:

• Setiap proses gagal.
• Setiap proses yang diblokir kebijakan.
• Setiap proses yang melakukan operasi tulis.

Boleh disampling:

• Proses read-only yang berhasil.

Tetap simpan cukup sampel read-only untuk menghitung baseline metrik. Prinsip ini sejalan dengan panduan Google SRE tentang pemantauan sistem terdistribusi: lakukan sampling untuk sinyal, bukan sekadar volume.

Bahkan setelah payload dihapus, simpan catatan kerangka berisi nama alat, hasil, dan durasi. Bagian mahal biasanya adalah body dan prompt, bukan metadata terstruktur.

Jika memakai tail sampling, putuskan apakah jejak disimpan setelah hasil akhir diketahui. Proses yang tampak normal pada langkah ketiga tetapi gagal pada langkah kesembilan harus tetap disimpan penuh. Itu berarti Anda perlu melakukan buffering, bukan membuang data terlalu dini.

Tentukan lokasi penyimpanan jejak

Penyimpanan terpusat cocok jika agen adalah layanan yang Anda kelola dan memanggil API Anda sendiri. Namun, pendekatan itu kurang cocok untuk runtime coding di mesin pengembang karena jejak berada di terminal yang menjalankan proses tersebut.

Sharkly mengambil pendekatan lain: jejak eksekusi dilampirkan ke tugas yang ditugaskan kepada agen. Riwayat proses, log, dan hasil berada bersama tujuan, status, serta utas komentar tempat manusia meninjau pekerjaan.

Pendekatan ini tidak menggantikan pelacakan teknis atau runtime seperti Claude Code dan Codex. Perbedaannya adalah lokasi pengambilan: pertanyaan “mengapa agen melakukan itu?” dapat dijawab dengan membuka tugas, bukan mencari mesin, sesi, dan scrollback.

Empat angka yang harus ada di dasbor

1. Panggilan per tugas yang diselesaikan
   
   Jika meningkat, agen mungkin semakin banyak mengeksplorasi karena deskripsi alat memburuk atau endpoint mulai gagal.

2. Tingkat retry per endpoint
   
   Urutkan dependensi yang paling tidak andal dan deteksi penurunan kualitas lebih awal. Lihat pemulihan kesalahan agen.

3. Tingkat blocked_by_policy
   
   Nilainya seharusnya rendah dan stabil. Lonjakan dapat berarti agen mencoba operasi yang tidak seharusnya atau kebijakan menjadi hambatan.

4. Waktu hingga panggilan alat pertama
   
   Awal yang lambat biasanya menandakan prompt membengkak atau konteks tidak terkendali.

Daftar periksa implementasi

• [ ] Satu ID jejak per proses dan satu ID rentang per panggilan alat.
• [ ] ID tersebut dicatat di lapisan penalaran, alat, dan HTTP.
• [ ] Argumen model disimpan sebelum normalisasi.
• [ ] Daftar alat yang tersedia dicatat untuk setiap panggilan.
• [ ] Hasil memakai enum eksplisit, termasuk blok kebijakan.
• [ ] Jumlah retry dipisahkan dari jumlah panggilan.
• [ ] Catatan proses menyertakan model, suhu, versi prompt, dan hash set alat.
• [ ] Hasil alat mentah tersedia untuk investigasi.
• [ ] Kredensial disunting di middleware logging.
• [ ] Body yang sensitif di-hash, bukan disimpan.
• [ ] Retensi disusun berdasarkan sensitivitas.
• [ ] Jejak gagal dapat diputar ulang sebagai pengujian regresi.

Tujuannya sederhana: saat seseorang bertanya mengapa agen melakukan sesuatu, Anda dapat menjawab berdasarkan catatan, bukan tebakan. Unduh Apidog untuk memutar ulang panggilan dari jejak dan menyimpannya sebagai pengujian.

Pertanyaan yang sering diajukan

Haruskah menggunakan OpenTelemetry atau alat observabilitas agen khusus?

Gunakan OpenTelemetry untuk transport dan model jejak karena sudah menangani korelasi serta kemungkinan telah digunakan oleh infrastruktur Anda. Alat observabilitas khusus agen dapat menambahkan tampilan yang lebih nyaman, tetapi data dasarnya sebaiknya tetap portabel.

Berapa biaya pelacakan penuh?

Biayanya lebih rendah dari perkiraan jika retensinya bertingkat. Simpan payload penuh beberapa hari, lalu pertahankan metadata terstruktur tanpa body untuk periode lebih panjang. Dump prompt biasanya bagian termahal, jadi hash dan ukur ukurannya daripada menyimpannya secara default.

Apakah teks penalaran model perlu dicatat?

Biasanya tidak. Alat yang dipilih, argumen yang dihasilkan, serta pilihan alat yang tersedia sudah menjelaskan sebagian besar keputusan. Jika penyedia mengekspos konten penalaran, simpan hanya untuk proses gagal dan perlakukan sebagai data sensitif.

Bagaimana melacak beberapa agen?

Gunakan satu trace_id untuk seluruh tugas. Berikan rentang sendiri kepada setiap agen dan catat handoff sebagai peristiwa. Lihat penyerahan konteks multi-agen.

Bagaimana jika agen berjalan di mesin pelanggan?

Catat secara lokal, sunting secara agresif, dan kirim hanya metrik agregat kecuali pengguna memilih ikut. Nama alat, hasil, dan durasi biasanya cukup untuk pemantauan tingkat armada tanpa payload meninggalkan perangkat.

Apakah hash body request benar-benar berguna?

Ya. Hash membuktikan dua panggilan identik tanpa menyimpan payload aslinya, sehingga berguna untuk sebagian besar investigasi penulisan duplikat. Pasangkan dengan kunci idempoten untuk mencegah duplikasi sejak awal.