Tutorial 26: Procesamiento por Lotes | Easy Understand Hermes Agent

Esto es parte de la serie oficial de tutoriales de Hermes Agent. Ver todos los tutoriales

Piensa en esto como una lista de verificación matutina que ejecutas antes de empezar a trabajar: no quieres recordar cada tarea tú mismo, así que las escribes una vez, y tu asistente las marca automáticamente cada día. Eso es exactamente lo que Hermes te permite hacer con gateway hooks y un simple archivo llamado BOOT.md.

En este tutorial, aprenderás cómo hacer que Hermes ejecute un “lote” personalizado de tareas cada vez que tu gateway se inicie — como revisar logs, publicar recordatorios, o incluso ejecutar un mini-agente que piensa y reporta.

Paso 1: Crea tu directorio de hooks

Primero, crea una carpeta dentro de tu directorio de hooks. Cada hook vive en su propia subcarpeta con dos archivos: HOOK.yaml (la configuración) y handler.py (la lógica).

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

Ahora crea HOOK.yaml:

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

Eso es todo — el evento le dice a Hermes que dispare este hook cuando el gateway arranque.

Paso 2: Escribe el handler

Ahora crea handler.py. Aquí es donde ocurre la magia. El handler lee un archivo llamado BOOT.md desde tu directorio de inicio, y luego inicia un hilo en segundo plano que ejecuta un agente con esas instrucciones.

Aquí está la idea central (simplificada):

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(),          # usa el modelo de tu gateway
        **_resolve_runtime_agent_kwargs()       # usa tus credenciales de proveedor
    )
    result = agent.run()
    print(f"boot-md completed: {result.summary()}")

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

Las dos líneas clave:

_resolve_gateway_model() lee el modelo configurado actualmente en el gateway.
_resolve_runtime_agent_kwargs() resuelve las credenciales del proveedor de la misma manera que lo hace un turno normal del gateway — incluyendo claves API, URLs base, tokens OAuth y grupos de credenciales.

Sin estas, un AIAgent() simple cae en los valores predeterminados integrados y devolverá un error 401 contra cualquier endpoint no predeterminado.

Paso 3: Pruébalo

Reinicia el gateway:

hermes gateway restart

Observa los logs:

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

Deberías ver Running BOOT.md (N chars) seguido de boot-md completed: ... (resumen de lo que hizo el agente) o boot-md completed (nothing to report) cuando el agente responda con un token de silencio exacto como [SILENT].

Elimina ~/.hermes/BOOT.md para desactivar la lista de verificación — el hook permanece cargado pero se omite silenciosamente cuando el archivo no está.

Extendiendo el patrón

Listas de verificación sensibles al horario: usa datetime.now().weekday() dentro de las instrucciones de BOOT.md (“si es lunes, también revisa el log de despliegue semanal”). Las instrucciones son texto libre, así que cualquier cosa que el agente pueda razonar es válida.
Múltiples listas de verificación: apunta el hook a un archivo diferente (STARTUP.md, MORNING.md, etc.) y registra directorios de hook separados para cada uno.
Variante sin agente: si no necesitas un bucle completo de agente, omite AIAgent por completo y haz que el handler publique una notificación fija directamente vía httpx. Más barato, más rápido y sin dependencia de proveedor.

Por qué esto no es una función integrada

Una versión anterior de Hermes incluía esto como un hook integrado y silenciosamente lanzaba un agente con valores predeterminados básicos en cada arranque del gateway. Eso sorprendió a los usuarios con endpoints personalizados e hizo que la función fuera invisible para quienes no sabían que estaba ejecutándose. Mantenerlo como un patrón documentado — construido por ti, en tu directorio de hooks — significa que ves exactamente lo que hace y te suscribes escribiendo los archivos.

Cómo funciona

Al iniciar el gateway, HookRegistry.discover_and_load() escanea ~/.hermes/hooks/
Cada subdirectorio con HOOK.yaml + handler.py se carga dinámicamente
Los handlers se registran para sus eventos declarados
En cada punto del ciclo de vida, hooks.emit() dispara todos los handlers coincidentes
Los errores en cualquier handler se capturan y registran — un hook roto nunca bloquea al agente

:::info Los gateway hooks solo se activan en el gateway (Telegram, Discord, Slack, WhatsApp, Teams). El CLI no carga gateway hooks. Para hooks que funcionen en todas partes, usa plugin hooks. :::

Resumen

Ahora sabes cómo convertir un simple archivo de texto en una poderosa lista de verificación de arranque que se ejecuta automáticamente. Ya sea un bucle completo de agente o una llamada HTTP rápida, el patrón es el mismo: escribe un hook, apúntalo a un archivo, y deja que Hermes se encargue del resto.