Tutorial 26: Elaborazione in Lotti

Questa parte fa parte della serie di tutorial ufficiali di Hermes Agent. Vedi tutti i tutorial

Pensala come una checklist mattutina che esegui prima di iniziare a lavorare: non vuoi ricordare ogni attività da solo, quindi le scrivi una volta e il tuo assistente le spunta automaticamente ogni giorno. È esattamente ciò che Hermes ti permette di fare con gli hook del gateway e un semplice file chiamato BOOT.md.

In questo tutorial, imparerai come far eseguire a Hermes un “lotto” personalizzato di attività ogni volta che il tuo gateway si avvia, come controllare i log, pubblicare promemoria o persino eseguire un mini-agente che pensa e riporta i risultati.

---

Passo 1: Crea la directory del tuo hook

Per prima cosa, crea una cartella all’interno della tua directory degli hook. Ogni hook vive nella propria sottocartella con due file: HOOK.yaml (la configurazione) e handler.py (la logica).

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

Ora crea HOOK.yaml:

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

Tutto qui: l’evento dice a Hermes di attivare questo hook all’avvio del gateway.

---

Passo 2: Scrivi l’handler

Ora crea handler.py. È qui che avviene la magia. L’handler legge un file chiamato BOOT.md dalla tua directory home, quindi avvia un thread in background che esegue un agente con quelle istruzioni.

Ecco l’idea principale (semplificata):

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"Esecuzione di BOOT.md ({len(content)} caratteri)")

    agent = AIAgent(
        instructions=content,
        model=_resolve_gateway_model(),          # usa il modello del tuo gateway
        **_resolve_runtime_agent_kwargs()       # usa le tue credenziali del provider
    )
    result = agent.run()
    print(f"boot-md completato: {result.summary()}")

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

Le due righe chiave:

• _resolve_gateway_model() legge il modello attualmente configurato dal gateway.
• _resolve_runtime_agent_kwargs() risolve le credenziali del provider nello stesso modo in cui farebbe un normale turno del gateway, incluse chiavi API, URL di base, token OAuth e pool di credenziali.

Senza queste, un semplice AIAgent() ripiega sui valori predefiniti integrati e riceverà un errore 401 contro qualsiasi endpoint non predefinito.

---

Passo 3: Provalo

Riavvia il gateway:

hermes gateway restart

Osserva i log:

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

Dovresti vedere Esecuzione di BOOT.md (N caratteri) seguito da boot-md completato: ... (un riepilogo di ciò che ha fatto l’agente) oppure boot-md completato (nessun report) quando l’agente risponde con un token di silenzio esatto come [SILENT].

Elimina ~/.hermes/BOOT.md per disabilitare la checklist: l’hook rimane caricato ma viene saltato silenziosamente se il file non esiste.

---

Estendere il pattern

• Checklist sensibili alla pianificazione: usa datetime.now().weekday() nelle istruzioni di BOOT.md (“se è lunedì, controlla anche il log di deploy settimanale”). Le istruzioni sono testo libero, quindi tutto ciò su cui l’agente può ragionare è valido.
• Checklist multiple: punta l’hook a un file diverso (STARTUP.md, MORNING.md, ecc.) e registra directory hook separate per ciascuno.
• Variante senza agente: se non hai bisogno di un ciclo completo dell’agente, salta del tutto AIAgent e fai pubblicare all’handler una notifica fissa direttamente tramite httpx. Più economico, più veloce e senza dipendenza dal provider.

---

Perché non è integrato

Una versione precedente di Hermes includeva questa funzionalità come hook integrato e generava silenziosamente un agente con impostazioni predefinite a ogni avvio del gateway. Questo sorprendeva gli utenti con endpoint personalizzati e rendeva la funzionalità invisibile a chi non sapeva che fosse in esecuzione. Mantenerlo come pattern documentato, creato da te nella tua directory degli hook, significa che vedi esattamente cosa fa e che scegli di attivarlo scrivendo i file.

---

Come funziona

1. All’avvio del gateway, HookRegistry.discover_and_load() esegue la scansione di ~/.hermes/hooks/
2. Ogni sottodirectory con HOOK.yaml + handler.py viene caricata dinamicamente
3. Gli handler vengono registrati per gli eventi dichiarati
4. A ogni punto del ciclo di vita, hooks.emit() attiva tutti gli handler corrispondenti
5. Gli errori in qualsiasi handler vengono catturati e registrati: un hook rotto non fa mai crashare l’agente

:::info Gli hook del gateway si attivano solo nel gateway (Telegram, Discord, Slack, WhatsApp, Teams). La CLI non carica gli hook del gateway. Per hook che funzionano ovunque, usa gli hook dei plugin. :::

---

Riepilogo

Ora sai come trasformare un semplice file di testo in una potente checklist di avvio che viene eseguita automaticamente. Che si tratti di un ciclo completo dell’agente o di una rapida chiamata HTTP, il pattern è lo stesso: scrivi un hook, puntalo a un file e lascia che Hermes faccia il resto.

Prossimo passo: Tutorial 27 — Modalità vocale: parlare con Hermes a mani libere.