Tutorial 26: Stapelverarbeitung | Easy Understand Hermes Agent

Dies ist Teil der offiziellen Hermes-Agent-Tutorialserie. Alle Tutorials ansehen

Stell dir das wie eine Morgen-Checkliste vor, die du vor der Arbeit durchgehst — du willst dir nicht jeden einzelnen Punkt selbst merken, also schreibst du sie einmal auf, und dein Assistent hakt sie jeden Tag automatisch ab. Genau das kannst du mit Hermes machen, und zwar mit Gateway-Hooks und einer simplen Datei namens BOOT.md.

In diesem Tutorial lernst du, wie Hermes bei jedem Gateway-Start einen eigenen „Stapel“ an Aufgaben abarbeitet — zum Beispiel Logs prüfen, Erinnerungen posten oder sogar einen Mini-Agenten starten, der nachdenkt und Bericht erstattet.

Schritt 1: Lege dein Hook-Verzeichnis an

Erstelle zuerst einen Ordner in deinem Hooks-Verzeichnis. Jeder Hook lebt in einem eigenen Unterordner mit zwei Dateien: HOOK.yaml (die Konfiguration) und handler.py (die Logik).

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

Jetzt erstellst du die HOOK.yaml:

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

Das war’s — das Event sagt Hermes, dass dieser Hook beim Gateway-Start ausgelöst werden soll.

Schritt 2: Schreibe den Handler

Jetzt erstellst du die handler.py. Hier passiert die eigentliche Magie. Der Handler liest eine Datei namens BOOT.md aus deinem Home-Verzeichnis und startet dann einen Hintergrund-Thread, der einen Agenten mit diesen Anweisungen ausführt.

Hier ist die Kernidee (vereinfacht):

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(),          # uses your gateway’s model
        **_resolve_runtime_agent_kwargs()       # uses your provider credentials
    )
    result = agent.run()
    print(f"boot-md completed: {result.summary()}")

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

Die zwei entscheidenden Zeilen:

_resolve_gateway_model() liest das aktuell konfigurierte Modell des Gateways.
_resolve_runtime_agent_kwargs() löst die Provider-Zugangsdaten genauso auf wie ein normaler Gateway-Durchlauf — inklusive API-Keys, Base-URLs, OAuth-Tokens und Credential-Pools.

Ohne diese Zeilen würde ein nackter AIAgent() auf die eingebauten Standardwerte zurückfallen und bei jedem nicht standardmäßigen Endpoint einen 401-Fehler werfen.

Schritt 3: Teste es

Starte das Gateway neu:

hermes gateway restart

Beobachte die Logs:

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

Du solltest Running BOOT.md (N chars) sehen, gefolgt von entweder boot-md completed: ... (eine Zusammenfassung dessen, was der Agent getan hat) oder boot-md completed (nothing to report), wenn der Agent mit einem exakten Stille-Token wie [SILENT] geantwortet hat.

Lösche ~/.hermes/BOOT.md, um die Checkliste zu deaktivieren — der Hook bleibt geladen, überspringt aber stillschweigend die Ausführung, wenn die Datei nicht vorhanden ist.

Das Muster erweitern

Zeitplan-bewusste Checklisten: Nutze datetime.now().weekday() in den Anweisungen der BOOT.md („Wenn Montag ist, prüfe auch das wöchentliche Deploy-Log“). Die Anweisungen sind Freitext, also ist alles möglich, worüber der Agent nachdenken kann.
Mehrere Checklisten: Richte den Hook auf eine andere Datei aus (STARTUP.md, MORNING.md, etc.) und registriere für jede Datei ein separates Hook-Verzeichnis.
Variante ohne Agent: Wenn du keine vollständige Agentenschleife brauchst, lass AIAgent komplett weg und lass den Handler direkt eine feste Benachrichtigung über httpx posten. Günstiger, schneller und ohne Provider-Abhängigkeit.

Warum das kein eingebautes Feature ist

Eine frühere Version von Hermes hatte das als eingebauten Hook und startete bei jedem Gateway-Boot stillschweigend einen Agenten mit Standardwerten. Das überraschte Nutzer mit benutzerdefinierten Endpoints und machte das Feature für alle unsichtbar, die nicht wussten, dass es lief. Wenn du es als dokumentiertes Muster behältst — von dir erstellt, in deinem Hooks-Verzeichnis — dann siehst du genau, was es tut, und entscheidest dich aktiv dafür, indem du die Dateien schreibst.

So funktioniert’s

Beim Gateway-Start scannt HookRegistry.discover_and_load() das Verzeichnis ~/.hermes/hooks/
Jedes Unterverzeichnis mit HOOK.yaml + handler.py wird dynamisch geladen
Handler werden für ihre deklarierten Events registriert
An jedem Lebenszyklus-Punkt feuert hooks.emit() alle passenden Handler
Fehler in einem Handler werden abgefangen und protokolliert — ein defekter Hook bringt den Agenten nie zum Absturz

:::info Gateway-Hooks feuern nur im Gateway (Telegram, Discord, Slack, WhatsApp, Teams). Die CLI lädt keine Gateway-Hooks. Für Hooks, die überall funktionieren, verwende Plugin-Hooks. :::

Zusammenfassung

Du weißt jetzt, wie du aus einer einfachen Textdatei eine mächtige Start-Checkliste machst, die automatisch läuft. Ob eine vollständige Agentenschleife oder ein schneller HTTP-Aufruf — das Muster ist dasselbe: Schreibe einen Hook, richte ihn auf eine Datei aus und lass Hermes den Rest erledigen.