Observabilitas agen AI: cara memahami apa yang dilakukan agen dan apa yang perlu dicatat

Apa itu observabilitas agen AI

Observabilitas agen AI adalah kemampuan menjawab, berdasarkan artefak — bukan ingatan dan bukan kata-kata agen — tiga pertanyaan: apa yang ia lakukan, mengapa begitu, dan apa yang membuktikan hasilnya benar. Jika setelah dua puluh menit kerja agen berkata «selesai, tetapi dua tes gagal, mungkin karena waktu tunggu», dan ketika ditanya jalur mana saja yang tersentuh ia menjawab «tunjukkan dulu kodenya» — observabilitas tidak ada. Agennya tidak bodoh: ia hanya tidak punya apa pun untuk dipresentasikan.

Masalahnya bersifat sistemik. Agen yang sama dalam seminggu bisa sepuluh kali dengan jujur mengatakan «selesai», dan setiap kali kata itu bisa berarti hal berbeda: di satu tempat semua tes dijalankan, di tempat lain hanya satu, di tempat lain tidak ada yang dijalankan. Makin lama proyek hidup, makin mahal setiap sesi berikutnya, karena ia dimulai dengan menggali-gali.

Dua lapisan: runtime dan proses

Observabilitas sering disamakan dengan log, padahal log hanya separuhnya.

Hanya runtime: terlihat apa yang gagal, tetapi tidak jelas apa yang diinginkan. Hanya proses: jelas apa yang diinginkan, tetapi tidak terlihat mengapa tidak berhasil. Keduanya dibutuhkan.

Mengapa agen tidak bisa melakukannya sendiri

Mengatakan kepada agen «catat yang lebih baik» tidak akan berhasil, karena tiga alasan.

• Ia tidak tahu apa yang tidak ia ketahui. Agen tidak akan mencatat sinyal yang pentingnya tidak ia sadari.
• Formatnya berubah-ubah. Di satu sesi ia menulis rinci, di sesi lain hanya satu baris. Sesi tidak bisa dibandingkan dan agregat tidak bisa dihitung.
• Proses tidak bisa ditutup dengan log. Jawaban atas «mengapa begini» ada di dokumen yang dibuat sebelum kerja, bukan di keluaran perintah.

Karena itu observabilitas dipasang ke dalam harness — lingkungan agen: templat, hook, skrip, format laporan yang wajib.

Apa yang dicatat: kumpulan minimal

Jurnal yang baik bukan transkrip segala hal, melainkan kumpulan fakta yang bisa dipakai untuk merekonstruksi jalannya kerja dan menghitung statistik.

• Identifikator: id sesi, id tugas atau fitur, model agen.
• Tindakan dengan efek samping: perintah apa yang dijalankan, berkas apa yang diubah. Membaca berkas biasanya tidak perlu dicatat.
• Hasil pemeriksaan: perintah verifikasi apa, kode kembalinya, berapa tes yang lulus dan gagal.
• Percobaan ulang: berapa percobaan dibutuhkan untuk satu langkah dan apa bedanya tiap percobaan.
• Pemakaian: token dan waktu, jika alat menyediakannya.
• Hasil akhir: tugas diterima, ditolak, atau ditinggalkan, dan mengapa.

Yang tidak boleh dicatat: rahasia, token akses, dan data pribadi dari keluaran perintah. Jurnal bisa berpindah ke akses bersama atau kembali ke konteks model.

Jurnal tindakan lewat hooks Claude Code

Di Claude Code, jurnal paling mudah dikelola dengan hooks — perintah yang dijalankan oleh alat itu sendiri, bukan oleh model, sehingga selalu berjalan. Hook menerima JSON di stdin yang menjelaskan event, termasuk id sesi, nama alat, dan parameternya. Contoh konfigurasi di .claude/settings.json yang setelah setiap pemanggilan Bash, Edit, atau Write menambahkan satu baris ke jurnal:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash|Edit|Write",
        "hooks": [
          { "type": "command", "command": ".claude/hooks/log-action.sh" }
        ]
      }
    ]
  }
}

#!/usr/bin/env bash
# .claude/hooks/log-action.sh — satu baris JSON per tindakan
mkdir -p .agent/logs
jq -c '{ts: (now | todate), session: .session_id, tool: .tool_name,
        cmd: .tool_input.command, file: .tool_input.file_path}' \
  >> .agent/logs/actions.jsonl || true

Format JSONL (satu rekaman JSON per baris) mudah difilter dengan jq dan dimuat ke sistem analisis apa pun. Selain itu, Claude Code sendiri menyimpan riwayat lengkap sesi secara lokal di direktori ~/.claude/projects/ — bisa dibuka jika ingin melihat penalaran dan keluaran secara utuh, tetapi untuk statistik jurnal kecil milik sendiri lebih praktis.

Trace: satu trace per sesi, span per tugas

Ketika agennya banyak atau berjalan terjadwal, jurnal teks saja tidak cukup: dibutuhkan agregat. Di sini berguna alat trace terdistribusi biasa dan standar OpenTelemetry.

• Trace — satu sesi agen.
• Span — satu tugas di dalam sesi.
• Span bersarang — langkah verifikasi: build, tes, e2e.

Atribut minimum pada span: id fitur dan sesi, model, hasil pemeriksaan, token, jumlah percobaan ulang. Data seperti ini bisa dibaca di Jaeger, Grafana Tempo, atau Honeycomb, dan menjawab pertanyaan yang tidak terlihat dalam satu sesi: jenis tugas mana yang paling sering butuh percobaan ulang, di mana agen menghabiskan token paling banyak, setelah perubahan harness mana proporsi tugas yang diterima turun. Claude Code memiliki ekspor metrik dan event bawaan melalui OpenTelemetry — diaktifkan dengan variabel lingkungan, rinciannya ada di dokumentasi alat.

Commit sebagai jurnal

Jurnal paling murah dan paling andal sudah Anda miliki — git. Yang perlu dilakukan hanyalah membuatnya mudah dibaca.

1. Satu commit — satu tugas. Dengan begitu git log sama dengan daftar yang dikerjakan, dan membatalkan tugas cukup dengan satu git revert.
2. Di pesan — apa yang diubah dan bagaimana diverifikasi. Bukan «fix», melainkan apa yang diubah, mengapa, dan perintah apa yang memverifikasinya.
3. Commit hanya setelah pemeriksaan hijau. Dengan begitu setiap titik riwayat adalah keadaan yang bisa dipakai, dan git bisect bisa menemukan pelakunya.

fix(payments): pembulatan diskon ke sen

Diskon dihitung dalam float, pada jumlah 999.99 satu sen hilang.
Perhitungan dipindah ke int dalam satuan sen.
Terverifikasi: make test (142 passed), make e2e checkout — ok.
Di luar lingkup: pembulatan di laporan, dicatat di BACKLOG.md.

Laporan agen: bukti, bukan kesan

Pesan akhir agen juga merupakan artefak observabilitas, jika bentuknya tetap. Tuliskan templat di AGENTS.md atau CLAUDE.md:

## Laporan di akhir tugas
- Yang dikerjakan: daftar perubahan (berkas — isinya)
- Cara verifikasi: perintah persis dan hasilnya
- Yang TIDAK diverifikasi dan mengapa
- Penyimpangan dari kontrak tugas
- Pertanyaan terbuka untuk manusia

Aturan utamanya: setiap pernyataan merujuk pada bukti — berkas dan baris, keluaran tes, entri jurnal. «Kelihatannya normal» dan «menurut saya oke» tidak dihitung sebagai laporan. Butir «yang tidak diverifikasi» sangat berharga: ia dengan jujur menunjukkan batas keyakinan.

Kontrak sebelum kode dan rubrik sesudahnya

Lapisan proses dimulai sebelum kerja. Kontrak singkat tentang tugas (sprint contract) mencatat lingkup, kriteria penerimaan, bagian «di luar lingkup», dan pertanyaan terbuka yang diputuskan manusia. Bagian «di luar lingkup» mencegah separuh perdebatan tentang hasil.

Setelah kerja, hasilnya dinilai berdasarkan rubrik, bukan kesan. Jika tidak, dua reviewer berpengalaman akan memberi vonis berbeda, dan penilaian menjadi undian.

Setiap dimensi dinilai A/B/C/D, dan penilaian tanpa rujukan tidak sah. Aturan keputusan sederhana: satu D atau dua C — tolak, dengan daftar apa yang harus diperbaiki. Rubrik yang sama bisa diterapkan oleh agen pemeriksa terpisah.

Cara menelusuri apa yang dilakukan agen dalam satu sesi

Jika laporan tidak ada atau tidak bisa dipercaya, telusuri artefak dengan urutan berikut.

1. Keadaan pohon kerja: git status — apa yang belum di-commit, apakah ada berkas sampah.
2. Riwayat: git log --stat sejak awal sesi — commit dan berkas apa saja.
3. Skala perubahan: git diff --stat main...HEAD, lalu diff lengkap untuk berkas-berkas penting.
4. Jurnal tindakan: perintah apa yang dijalankan dan apa yang dikembalikan pemeriksaan.
5. Verifikasi ulang: jalankan sendiri build dan tes. Percayai keluaran perintah, bukan ceritera ulang.

# perintah apa yang dijalankan agen di sesi terakhir
jq -r 'select(.tool=="Bash") | .cmd' .agent/logs/actions.jsonl | tail -n 30
# berkas apa yang paling sering diubah
jq -r '.file // empty' .agent/logs/actions.jsonl | sort | uniq -c | sort -rn | head

Kesalahan umum

• Mencatat semuanya. Gigabyte transkrip tidak dibaca siapa pun. Catat tindakan dengan efek samping dan hasil pemeriksaan.
• Format bebas. Jika agen yang menentukan format jurnal, tidak akan ada agregat. Format ditentukan oleh harness.
• Percaya laporan tanpa keluaran perintah. «Tes hijau» tanpa keluaran hanyalah pendapat.
• Percobaan ulang buta. Tanpa penyebab kegagalan, agen mengubah tempat yang acak. Minta diagnosis dengan rujukan ke log dulu, baru perbaikan.
• «Nanti saja dibersihkan.» Berkas debug dan perubahan yang belum di-commit membingungkan sesi berikutnya: ia tidak bisa membedakan yang sementara dari yang disengaja.

Ringkasan

Observabilitas agen AI dibangun dari dua lapisan: runtime (jurnal tindakan lewat hooks, trace, commit dengan deskripsi pemeriksaan) dan proses (kontrak tugas sebelum kode, rubrik, dan laporan dengan tautan ke bukti). Dengan begitu «selesai» berarti hal yang sama di setiap sesi, dan menelusuri pekerjaan agen memakan waktu hitungan menit. Topik ini dibahas praktis di kursus harness engineering, pada proyek contoh backend pembayaran.