Belajar Hermes AI Agent - Basic Observability & Logging

#Pendahuluan

Di episode 6 kalian memberi Hermes kemampuan bertindak: tool web search, database query, API fetch, dan file system terhubung ke agent. Semakin banyak tool, semakin sulit menjawab satu pertanyaan: "kenapa agent melakukan itu?" Episode ini menjawabnya dengan observability — kemampuan mengamati perilaku agent dari dalam.

Roadmap episode ini: pertama event logging untuk percakapan agent, kedua debugging action execution dan tool calls, ketiga memantau perilaku agent dan replay logs.

#Mengapa Agent Perlu Observability

Agent bukan program deterministik. Dengan model dan prompt yang sama, output bisa berbeda antar run. Ditambah alur perception-planning-action-reflection yang berlapis, kegagalan jarang terlihat dari output akhir saja — sering kali justru terjadi di tengah-tengah pemanggilan tool.

Tanpa observability, debugging agent seperti menebak isi kotak hitam: kalian hanya melihat pesan terakhir, tanpa tahu plan apa yang disusun model, tool apa yang dipanggil, dan mengapa tool itu dipilih. Observability mengubah kotak hitam itu menjadi kaca bening.

Prinsip dasarnya sederhana: setiap langkah penting menghasilkan event terstruktur dengan konteks yang cukup, lalu event-event itu disimpan, dicari, dan diputar ulang.

#Event Logging Percakapan

Hermes menerbitkan event terstruktur untuk setiap fase lifecycle agent. Setiap event berisi session_id, timestamp, type, dan payload. Formatnya JSON sehingga mudah diproses oleh tool lain.

{
  "session_id": "ses_order-check",
  "timestamp": "2026-08-03T09:14:22.481Z",
  "type": "llm.request",
  "model": "gpt-4o-mini",
  "turn": 3,
  "input_tokens": 1240,
  "payload": {
    "prompt": "Periksa status order ORD-2026-0142"
  }
}

Jenis event utama yang akan sering kalian lihat: turn.started dan turn.completed sebagai batas satu siklus percakapan, llm.request dan llm.response di sekitar panggilan model, serta tool.invoked dan tool.result untuk setiap pemanggilan tool beserta argumen dan hasilnya.

Contoh event tool.invoked yang mencatat argumen sebelum tool dieksekusi:

{
  "session_id": "ses_order-check",
  "timestamp": "2026-08-03T09:14:22.689Z",
  "type": "tool.invoked",
  "tool": "db.query",
  "turn": 3,
  "args": {
    "sql": "SELECT status FROM orders WHERE id = 'ORD-2026-0142'"
  }
}

#Membaca dan Menyaring Log

Semua event bisa dilihat lewat perintah hermes logs. Tapi log percakapan cepat memanjang; karena itu Hermes menyediakan filter.

hermes logs --follow --session ses_order-check

hermes logs --filter type=tool

hermes logs --json --since 2h

--follow memunculkan event baru secara real-time, --filter menyaring berdasarkan tipe event, dan --json mengeluarkan log sebagai baris JSON untuk disalurkan ke jq atau log collector. Untuk pengerjaan sehari-hari, kombinasi --filter dengan --session adalah yang paling sering dipakai.

#Debugging Action Execution & Tool Calls

Ketika agent berperilaku aneh, pertanyaan pertamanya: tool apa yang dipanggil, dengan argumen apa, dan hasilnya seperti apa? hermes debug menjalankan agent dengan tracing menyeluruh dan menampilkan alurnya di terminal.

hermes debug agents/support.yml --prompt "Cek status ORD-2026-0142"

Mode ini menampilkan plan yang disusun model, setiap tool yang dipanggil lengkap dengan argumennya, hasil yang dikembalikan, dan pesan yang dikirim ke model pada langkah berikutnya. Dari sini kalian bisa langsung melihat apakah agent memanggil tool yang salah, mengirim argumen yang keliru, atau salah membaca hasil.

Pola debug yang paling umum: agent mengirim argumen salah ke db.query, hasilnya error SQL, lalu agent salah menafsirkannya pada turn berikutnya. Di trace, semua itu tampak sebagai rantai tool.invoked → tool.result dengan status error.

Contoh konkretnya: agent diminta mengecek status pesanan, tapi argumen yang dikirim ke db.query memakai nama kolom order_id padahal skema tabelnya orders.id. Trace menunjukkan tool.invoked dengan argumen yang salah, tool.result berisi error SQL, dan turn berikutnya model mengulang kesalahan yang sama. Perbaikannya langsung terlihat di trace: sesuaikan nama kolom di tool definition, bukan menebak-nebak isi prompt.

#Memantau Behavior dan Replay Log

Observability tidak hanya untuk debugging reaktif. Dengan log yang tersimpan, kalian bisa memantau perilaku agent secara terus-menerus: berapa lama satu turn berlangsung, tool mana paling sering dipanggil, dan berapa banyak turn yang berakhir dengan error.

Untuk menganalisis kejadian lama, Hermes punya perintah replay yang menjalankan ulang sebuah sesi dari log tanpa memanggil model lagi. Ini sangat berguna untuk menelusuri "kenapa minggu lalu agent menjawab seperti ini" tanpa biaya token.

hermes replay ses_order-check --render

hermes replay membaca seluruh event sesi dan menampilkannya sebagai percakapan lengkap — termasuk tool calls yang disisipkan di antara pesan. Hasilnya bisa diekspor ke file Markdown untuk dibagikan ke tim.

#Penutup

Observability mengubah debugging agent dari menebak menjadi mengamati. Kalian sekarang bisa mencatat setiap event percakapan, menyaring log berdasarkan tipe dan sesi, men-debug action execution dengan trace, serta memutar ulang sesi untuk analisis lanjutan.

Inti yang harus dibawa pulang:

• Setiap fase lifecycle menghasilkan event JSON terstruktur dengan session_id dan type.
• hermes logs dengan filter memudahkan menelusuri event tertentu dari ribuan baris log.
• hermes debug menampilkan plan, tool calls, dan hasilnya secara lengkap.
• Redaksi rahasia di log harus selalu aktif, terutama di production.
• hermes replay menjalankan ulang sesi tanpa biaya token untuk analisis.

Di episode 8 kita masuk ke Memory & State Management — bagaimana Hermes menyimpan ingatan jangka pendek dan panjang, strategi menyimpan, mengambil, dan memangkas memory, serta batasan token usage dan state size. Sampai jumpa!