Tutorial 26: Pemrosesan Batch | Easy Understand Hermes Agent

Ini adalah bagian dari seri tutorial resmi Hermes Agent. Lihat semua tutorial

Anggap saja ini seperti daftar periksa pagi yang kamu jalankan sebelum mulai bekerja — kamu tidak perlu mengingat setiap tugas sendiri, jadi kamu menuliskannya sekali, dan asistenmu otomatis mencentangnya setiap hari. Itulah yang bisa dilakukan Hermes untukmu dengan gateway hooks dan sebuah file sederhana bernama BOOT.md.

Dalam tutorial ini, kamu akan belajar cara membuat Hermes menjalankan “batch” tugas khusus setiap kali gateway-mu dimulai — seperti memeriksa log, mengirim pengingat, atau bahkan menjalankan mini-agent yang berpikir dan melaporkan kembali.

Langkah 1: Buat direktori hook-mu

Pertama, buat folder di dalam direktori hooks-mu. Setiap hook berada di subfolder-nya sendiri dengan dua file: HOOK.yaml (konfigurasi) dan handler.py (logika).

mkdir -p ~/.hermes/hooks/boot-md
cd ~/.hermes/hooks/boot-md

Sekarang buat HOOK.yaml:

name: "boot-md"
event: "gateway_startup"

Itu saja — event tersebut memberi tahu Hermes untuk memicu hook ini saat gateway melakukan boot.

Langkah 2: Tulis handler-nya

Sekarang buat handler.py. Di sinilah keajaiban terjadi. Handler membaca file bernama BOOT.md dari direktori home-mu, lalu memulai thread latar belakang yang menjalankan agent dengan instruksi tersebut.

Berikut ide intinya (disederhanakan):

import os, threading
from pathlib import Path
from hermes.agent import AIAgent

def run_boot_md():
    content = Path.home().joinpath(".hermes", "BOOT.md").read_text()
    print(f"Running BOOT.md ({len(content)} chars)")

    agent = AIAgent(
        instructions=content,
        model=_resolve_gateway_model(),          # menggunakan model gateway-mu
        **_resolve_runtime_agent_kwargs()       # menggunakan kredensial provider-mu
    )
    result = agent.run()
    print(f"boot-md completed: {result.summary()}")

def handler(event):
    thread = threading.Thread(target=run_boot_md, daemon=True)
    thread.start()

Dua baris kunci:

_resolve_gateway_model() membaca model yang sedang dikonfigurasi di gateway.
_resolve_runtime_agent_kwargs() menyelesaikan kredensial provider dengan cara yang sama seperti giliran gateway normal — termasuk API keys, base URLs, token OAuth, dan kumpulan kredensial.

Tanpa keduanya, AIAgent() polos akan kembali ke default bawaan dan akan gagal dengan kode 401 terhadap endpoint non-default mana pun.

Langkah 3: Uji coba

Mulai ulang gateway:

hermes gateway restart

Pantau log-nya:

hermes logs --follow --level INFO | grep boot-md

Kamu akan melihat Running BOOT.md (N chars) diikuti oleh boot-md completed: ... (ringkasan apa yang dilakukan agent) atau boot-md completed (nothing to report) saat agent membalas dengan token diam persis seperti [SILENT].

Hapus ~/.hermes/BOOT.md untuk menonaktifkan daftar periksa — hook tetap dimuat tetapi otomatis dilewati saat file tersebut tidak ada.

Mengembangkan pola ini

Daftar periksa yang sadar jadwal: kunci berdasarkan datetime.now().weekday() di dalam instruksi BOOT.md (“jika hari Senin, periksa juga log deploy mingguan”). Instruksinya berupa teks bebas, jadi apa pun yang bisa dipikirkan oleh agent bisa digunakan.
Beberapa daftar periksa: arahkan hook ke file yang berbeda (STARTUP.md, MORNING.md, dll.) dan daftarkan direktori hook terpisah untuk masing-masing.
Varian non-agent: jika kamu tidak membutuhkan loop agent penuh, lewati AIAgent sepenuhnya dan buat handler mengirim notifikasi tetap langsung melalui httpx. Lebih murah, lebih cepat, dan tidak bergantung pada provider.

Mengapa ini tidak menjadi fitur bawaan

Versi awal Hermes mengirimkan ini sebagai hook bawaan dan diam-diam memunculkan agent dengan default polos setiap kali gateway boot. Hal itu mengejutkan pengguna dengan endpoint khusus dan membuat fitur ini tidak terlihat oleh pengguna yang tidak tahu bahwa fitur tersebut berjalan. Menjaganya sebagai pola yang terdokumentasi — dibuat olehmu, di direktori hooks-mu — berarti kamu bisa melihat dengan jelas apa yang dilakukannya dan ikut serta dengan menulis file-file tersebut.

Cara Kerjanya

Saat gateway dimulai, HookRegistry.discover_and_load() memindai ~/.hermes/hooks/
Setiap subdirektori dengan HOOK.yaml + handler.py dimuat secara dinamis
Handler didaftarkan untuk event yang dideklarasikan
Di setiap titik siklus hidup, hooks.emit() memicu semua handler yang cocok
Kesalahan di handler mana pun akan ditangkap dan dicatat — hook yang rusak tidak akan pernah membuat agent crash

:::info Gateway hooks hanya aktif di gateway (Telegram, Discord, Slack, WhatsApp, Teams). CLI tidak memuat gateway hooks. Untuk hooks yang berfungsi di mana saja, gunakan plugin hooks. :::

Ringkasan

Kamu sekarang tahu cara mengubah file teks sederhana menjadi daftar periksa startup yang kuat dan berjalan otomatis. Baik itu loop agent penuh atau panggilan HTTP cepat, polanya sama: tulis hook, arahkan ke file, dan biarkan Hermes menangani sisanya.