Seorang pengguna melaporkan bahwa agen "melakukan sesuatu yang aneh" kemarin sore. Anda membuka log dan menemukan ini:
INFO agent run started
INFO calling tool: updateOrder
INFO tool returned 200
INFO agent run completed
Agen memanggil updateOrder. Anda tidak tahu dengan argumen apa, terhadap pesanan mana, mengapa ia memilih alat itu, atau apa yang kembali. Proses tersebut berhasil berdasarkan setiap ukuran yang Anda catat, dan Anda tidak dapat merekonstruksi satu pun keputusan yang dibuatnya.
Sistem agen gagal dengan cara yang hanya masuk akal setelah diselidiki, yang berarti log adalah produknya. Panduan ini mencakup apa yang harus dicatat pada setiap panggilan alat, bagaimana menghubungkan keputusan model dengan permintaan HTTP yang dihasilkannya, apa yang harus disunting, dan bagaimana mengubah jejak menjadi pengujian. Posting kami tentang observabilitas API mencakup sisi layanan; yang ini mencakup lapisan agen yang berada di atasnya.
Apidog berguna setelah Anda memiliki jejak, karena cara tercepat untuk memahami panggilan yang buruk adalah dengan memutarnya ulang terhadap titik akhir yang sama dan melihat apa yang terjadi.
Tiga lapisan, satu jejak
Sebuah agen menghasilkan peristiwa pada tiga level, dan sebagian besar tim hanya mencatat level tengah.
Lapisan penalaran adalah tempat model membuat keputusan. Apa yang ada dalam konteks, alat apa yang ditawarkan, mana yang dipilihnya, dan dengan argumen apa.
Lapisan alat adalah eksekutor Anda. Ia memvalidasi argumen, menerapkan kebijakan, memetakan panggilan ke permintaan HTTP, dan menangani hasilnya.
Lapisan HTTP adalah koneksi. Metode, URL, header, isi, status, latensi.
Debugging hampir selalu melintasi lapisan. "Agen mengirimkan ID pelanggan yang salah" adalah masalah penalaran yang hanya terlihat pada lapisan HTTP. "API mengembalikan 200 dengan badan kosong" adalah masalah HTTP yang muncul sebagai penalaran aneh tiga langkah kemudian. Jika ketiga lapisan tidak diikat bersama oleh pengidentifikasi bersama, Anda akan terjebak dalam korelasi berdasarkan stempel waktu, yang berhenti berfungsi saat dua proses tumpang tindih.
Jadi aturan pertama: satu ID jejak per eksekusi agen, satu ID rentang per panggilan alat, dan keduanya dicap pada setiap catatan di setiap lapisan. Jejak OpenTelemetry sudah memodelkan bentuk ini secara tepat, dan ada serangkaian konvensi semantik GenAI yang berkembang untuk menamai atribut sehingga data Anda portabel.
Apa yang harus dicatat pada setiap panggilan alat
Sebuah catatan yang menjawab pertanyaan nyata memiliki bentuk kira-kira 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 }
}
Lima bidang melakukan pekerjaan yang tidak proporsional.
tool_args adalah yang paling sering hilang, dan itu adalah yang selalu Anda inginkan. Catat argumen yang dihasilkan model, sebelum eksekutor Anda menormalkannya. Ketika agen mengirimkan ID yang salah, di sinilah terlihat.
tools_available menjelaskan pemilihan. Jika model memilih alat yang aneh, pertanyaan pertama adalah apa lagi yang bisa dipilihnya. Bidang ini membutuhkan beberapa byte dan menjawabnya secara instan.
retry_count memisahkan "API lambat" dari "API gagal dua kali lalu berfungsi." Tanpa itu, tiga percobaan terlihat seperti satu panggilan.
outcome harus berupa enum eksplisit, bukan sesuatu yang disimpulkan dari kode status. success, failed, timed_out, blocked_by_policy, rejected_by_human. Dua yang terakhir penting karena panggilan yang diblokir adalah penjaga yang berfungsi, bukan kesalahan, dan mencampurnya merusak tingkat kegagalan Anda.
policy adalah jejak audit Anda. Ketika seseorang bertanya apakah tindakan destruktif disetujui, inilah jawabannya. Ini berpasangan dengan penegakan yang dijelaskan dalam posting kami tentang penjaga agen AI.
Catat keputusannya, bukan hanya tindakannya
Bug agen yang paling sulit adalah pilihan, jadi catatlah cukup untuk merekonstruksinya.
Simpan definisi alat yang digunakan untuk proses, atau hash dari definisi tersebut. Ketika akurasi seleksi bergeser, dugaan pertama adalah deskripsi yang diedit seseorang, dan hash segera memberi tahu Anda apakah set alat berubah antara proses yang baik dan yang buruk. Posting kami tentang desain skema alat mencakup mengapa teks itu sangat menggeser perilaku.
Catat model dan pengaturannya. ID model, suhu, dan versi prompt termasuk dalam catatan proses. Perilaku berubah di seluruh versi model, dan tanpa bidang ini Anda akan menghabiskan sehari menyelidiki kode Anda sendiri.
Catat apa yang dilihat model, atau setidaknya ukurannya. Buangan prompt lengkap mahal untuk disimpan dan seringkali sensitif. Hitungan token ditambah hash memberi Anda sebagian besar nilai diagnostik: proses yang promptnya dua kali ukuran biasanya adalah proses di mana sesuatu ditambahkan yang seharusnya tidak ada.
Catat hasil alat mentah sebelum pemangkasan. Jika eksekutor Anda memproyeksikan respons ke bawah sebelum menyerahkannya ke model, seperti dalam posting kami tentang menjaga respons alat keluar dari jendela konteks, simpan muatan penuh dalam jejak. Jika tidak, Anda tidak dapat mengetahui apakah data hilang atau Anda menjatuhkannya.
Sunting sebelum Anda menyimpan
Jejak agen sangat berbahaya karena mengandung permintaan dan penalaran di sekitarnya, dan prompt memiliki kebiasaan mengumpulkan data pribadi.
Empat aturan membuat ini dapat dikelola.
Jangan pernah menyimpan kredensial. Hapus Authorization, kunci API, cookie, dan URL yang ditandatangani. Catat pengidentifikasi kredensial, seperti ID kunci, dan bukan nilainya. Posting kami tentang kunci API hak istimewa paling rendah untuk agen membahas mengapa Anda menginginkan pengidentifikasi itu: ia memberi tahu Anda agen mana yang bertindak.
Sunting di batas, bukan di kueri. Penyaringan pada waktu baca berarti rahasia telah ditulis ke disk, direplikasi, dan dicadangkan. Sunting dalam middleware pencatatan sebelum catatan meninggalkan proses.
Hash badan yang tidak dapat Anda simpan. Hash badan permintaan masih memungkinkan Anda membuktikan dua panggilan identik, yang merupakan sebagian besar dari apa yang Anda butuhkan untuk penyelidikan duplikat, tanpa menyimpan muatan.
Atur retensi berdasarkan sensitivitas. Jejak penuh selama seminggu, ringkasan yang disunting selama setahun. Sebagian besar debugging terjadi dalam hitungan hari; sebagian besar pertanyaan audit tiba dalam hitungan bulan.
Ubah jejak menjadi pengujian
Manfaat dari penelusuran yang baik bukan hanya debugging yang lebih cepat. Ini adalah pasokan kasus uji yang realistis.
Setiap proses yang gagal adalah sebuah skenario. Ambil panggilan alat dari jejak yang buruk, putar ulang terhadap API Anda, dan Anda memiliki reproduksi. Ketika perbaikan diterapkan, simpan putar ulang sebagai uji regresi. Di Apidog Anda dapat membangun kembali permintaan yang gagal sebagai kasus yang disimpan, menegaskan perilaku yang diperbaiki, dan menjalankannya di CI, begitulah insiden sekali jadi berubah menjadi cakupan permanen.
Jejak juga memberi tahu Anda apa yang harus ditiru. Titik akhir yang paling sering dipanggil agen Anda, dan status kegagalan yang sebenarnya ditemui, langsung berasal dari data daripada tebakan. Bangun mock di sekitar itu, mengikuti posting kami tentang menjalankan agen terhadap mock daripada produksi.
Dan mereka menampilkan pergeseran lambat yang mungkin tidak Anda sadari. Lacak beberapa angka per minggu: distribusi pemilihan alat, tingkat coba ulang per titik akhir, panggilan per tugas yang selesai, dan persentase proses yang diblokir oleh kebijakan. Pergeseran pada salah satunya adalah sinyal sebelum menjadi insiden. Pemeriksaan tingkat kontrak, seperti dalam panduan pengujian kontrak API kami, menangkap perubahan hulu yang biasanya menyebabkannya.
Tiga investigasi yang harus dilewati jejak
"Agen menagih pelanggan yang salah." Anda memerlukan argumen yang dihasilkan model, URL yang diselesaikan, dan langkah sebelumnya. Sembilan dari sepuluh kali ID berasal dari hasil alat sebelumnya yang mengembalikan lebih dari satu kecocokan dan model memilih yang pertama. Jejak menunjukkan hasil sebelumnya, ambiguitas, dan pilihannya. Tanpa tool_args Anda memiliki 200 dan pelanggan yang sangat tidak senang.
"Itu berhenti berfungsi pada hari Selasa." Bandingkan proses yang baik dan proses yang buruk bidang demi bidang. ID model, hash set alat, versi prompt, ukuran respons rata-rata. Sesuatu berubah, dan salah satu dari keempatnya biasanya menamainya. Inilah mengapa catatan proses membawa konfigurasi dan bukan hanya peristiwa: perbedaan hanya mungkin jika kedua belah pihak mencatat bidang yang sama.
"Apakah ada yang menyetujui ini?" Blok kebijakan adalah seluruh jawaban, dan harus ditulis pada saat keputusan, tidak direkonstruksi kemudian. approval_required, approved_by, dan stempel waktu mengubah percakapan tegang menjadi pencarian.
Perhatikan apa kesamaan dari semua ini. Tidak ada satu pun yang dijawab dengan "alat mengembalikan 200." Ketiganya dijawab oleh bidang yang biayanya hampir tidak ada untuk ditulis dan tidak mungkin dipulihkan setelah fakta.
Sampling, dan apa yang tidak boleh diambil sampelnya
Pelacakan fidelitas penuh pada setiap proses menjadi mahal pada volume tinggi, jadi tim melakukan sampling. Lakukan sampling dengan hati-hati, karena lalu lintas agen tidak seragam.
Selalu simpan setiap proses yang gagal, setiap proses yang mengalami blokir kebijakan, dan setiap proses yang mengandung penulisan. Itu adalah proses yang akan ditanyakan siapa pun. Sampel proses baca-saja yang berhasil, karena itu adalah sebagian besar volume dan yang paling tidak menarik secara individu, meskipun Anda masih menginginkan cukup banyak untuk menghitung baseline Anda.
Bab buku SRE Google tentang pemantauan sistem terdistribusi masih merupakan pernyataan paling jelas mengapa Anda mengambil sampel untuk sinyal daripada untuk volume, dan alasannya berlaku secara langsung.
Simpan catatan proses bahkan ketika Anda menghapus muatan. Jejak kerangka dengan nama alat, hasil, dan durasi kecil dan masih mendukung empat metrik di atas. Bagian yang mahal adalah badan dan prompt, dan itulah bagian yang dapat Anda hapus terlebih dahulu.
Satu peringatan tentang pengambilan sampel ekor: jika Anda memutuskan apa yang akan disimpan setelah proses selesai, pastikan keputusan terjadi setelah hasil diketahui. Sebuah proses yang terlihat baik pada langkah ketiga dan gagal pada langkah kesembilan harus dipertahankan secara penuh, yang berarti buffering daripada membuang saat Anda berjalan.
Di mana jejak harus berada
Semua hal di atas mengasumsikan Anda memiliki penyimpanan. Itu adalah asumsi yang tepat ketika agen adalah layanan Anda sendiri yang memanggil API Anda sendiri. Ini tidak cocok ketika agen adalah runtime coding di mesin pengembang, karena jejak kemudian berada di terminal mana pun yang menjalankannya.
Sharkly mengambil pendekatan lain: jejak eksekusi dilampirkan pada Tugas yang ditugaskan kepada agen. Riwayat proses, log eksekusi, dan hasilnya berada di samping tujuan, status, dan utas komentar tempat manusia meninjau pekerjaan. Perbedaan praktisnya adalah pengambilan. "Mengapa agen melakukan itu" menjadi pertanyaan yang Anda jawab dengan membuka tugas, daripada dengan menemukan mesin, sesi, dan scrollback.
Ini tidak menggantikan pelacakan yang dijelaskan di sini, dan juga tidak menggantikan runtime; Claude Code dan Codex masih melakukan pekerjaan itu. Yang berubah adalah di mana catatan berakhir ketika agen bukanlah layanan yang Anda terapkan.
Perhatikan empat angka
Jejak hanya berguna jika ada yang melihat. Keempat ini layak ditempatkan di dasbor.
Panggilan per tugas yang diselesaikan. Ukuran efisiensi yang paling jelas. Jika naik, agen semakin banyak menjelajah, biasanya karena deskripsi semakin buruk atau titik akhir mulai gagal.
Tingkat coba ulang per titik akhir. Mengurutkan ketergantungan Anda yang paling tidak andal dan menunjukkan kapan salah satu menurun. Posting kami tentang pemulihan kesalahan agen mencakup apa yang harus dilakukan tentang bagian atas daftar itu.
Tingkat diblokir-oleh-kebijakan. Seharusnya rendah dan stabil. Lonjakan berarti agen mencoba hal-hal yang tidak seharusnya, atau kebijakan terlalu ketat dan sekarang menjadi hambatan.
Waktu hingga panggilan alat pertama. Awal yang lambat biasanya berarti prompt yang membengkak, dan ukuran prompt adalah hal yang tumbuh tanpa ada yang memutuskan untuk mengembangkannya.
Daftar periksa
- Satu ID jejak per proses, satu ID rentang per panggilan alat, dicap di ketiga lapisan.
- Argumen model dicatat sebelum normalisasi.
- Daftar alat yang tersedia dicatat pada setiap panggilan.
- Hasil dicatat sebagai enum eksplisit, termasuk blok kebijakan.
- Jumlah percobaan ulang terpisah dari jumlah panggilan.
- Model, suhu, versi prompt, dan hash set alat pada catatan proses.
- Hasil alat mentah disimpan, bukan hanya versi yang dipangkas yang diserahkan ke model.
- Kredensial dihapus di middleware, badan di-hash di mana tidak dapat disimpan.
- Retensi berjenjang berdasarkan sensitivitas.
- Jejak yang gagal dapat diubah menjadi kasus uji yang dapat diputar ulang.
Tujuannya sederhana: ketika seseorang bertanya mengapa agen melakukan itu, Anda dapat menjawab dari catatan daripada dari tebakan. Unduh Apidog untuk memutar ulang panggilan dalam jejak dan menyimpan reproduksi sebagai pengujian.
Pertanyaan yang sering diajukan
Haruskah saya menggunakan OpenTelemetry atau alat observabilitas agen yang dibuat khusus? Gunakan OpenTelemetry untuk transport dan model jejak, karena sudah menangani korelasi dan infrastruktur Anda mungkin menggunakannya. Alat khusus agen menambahkan tampilan yang berguna di atas; data di bawahnya harus tetap portabel.
Berapa biaya penyimpanan pelacakan penuh? Lebih sedikit dari yang orang duga, jika Anda menatanya. Muatan penuh selama beberapa hari dan catatan terstruktur tanpa badan untuk jangka waktu yang lebih lama menjaga sebagian besar volume tetap rendah. Buangan prompt adalah bagian yang mahal, jadi hash dan ukur daripada menyimpannya secara default.
Apakah saya perlu mencatat teks penalaran model? Biasanya tidak. Alat yang dipilihnya, argumen yang dihasilkannya, dan opsi yang dimilikinya menjelaskan sebagian besar keputusan. Jika penyedia mengekspos konten penalaran, simpan hanya untuk proses yang gagal dan perlakukan sebagai sensitif.
Bagaimana cara melacak beberapa agen? Pertahankan satu ID jejak untuk seluruh tugas dan berikan setiap agen rentang sendiri, dengan penyerahan dicatat sebagai peristiwa. Posting kami tentang penyerahan multi-agen mencakup apa yang termasuk dalam catatan penyerahan itu.
Bagaimana jika agen berjalan di mesin pelanggan? Catat secara lokal, sunting secara agresif, dan kirim hanya metrik agregat kecuali jika pengguna memilih ikut. Nama alat, hasil, dan durasi biasanya cukup untuk pemantauan tingkat armada tanpa ada muatan yang meninggalkan perangkat.
Apakah hash badan permintaan benar-benar berguna? Ya, untuk pertanyaan yang paling umum. Ini membuktikan dua panggilan identik, yang menyelesaikan sebagian besar investigasi penulisan duplikat, tanpa menyimpan muatan itu sendiri. Pasangkan dengan kunci idempoten yang seharusnya mencegah duplikat.