Hermes-Agent an NomOS anbinden

Hermes (Nous Research, MIT) ist ein selbst-lernender Agent und zugleich ein MCP-Host. NomOS governt ihn: Der Agent fragt NomOS nach Wissen und lässt geplante Aktionen vor dem Handeln gegen die Raum-Verfassung prüfen.

Was und wer

Hermes ist ein modell-agnostischer, selbst-lernender Agent und zugleich ein MCP-Host: Er kann sich an jeden MCP-Server hängen. NomOS ist ein solcher Server. Die Integration gibt einem Hermes-Agenten governten Zugriff auf NomOS.

Leitprinzip (ADR-037): Hermes ist der Akteur, NomOS ist die Autorität. Hermes handelt; NomOS liefert das Wissen und das verbindliche Urteil. Hermes-Memory und -Skills bleiben beim Agenten. Ins Gedächtnis fliesst Wissen nur als geprüfter, vom Owner bestätigter Vorschlag, nie als direkter Schreibzugriff.

Anbinden mit Maschinen-Identität (Bearer)

Hermes konfiguriert MCP-Server in «~/.hermes/config.yaml» unter «mcp_servers:». Für deinen eigenen Login nimm OAuth (nächster Abschnitt). Der Bearer-Pfad ist für eine Maschinen-Identität ohne Browser (NHI): Der Raum-Owner legt im Agenten-Bereich unter «Externe Agenten» einen NHI-Agenten an und erhält Client-ID und Secret. Der Eintrag liest das Token aus der Umgebung:

~/.hermes/config.yaml

mcp_servers:
  ainomos:
    url: "https://<ihre-installation>/api/mcp"
    headers:
      Authorization: "Bearer ${AINOMOS_TOKEN}"

Das Secret selbst ist kein Bearer. Tausche Client-ID und Secret per Client-Credentials gegen ein kurzlebiges Access-Token:

curl -s -X POST "https://<ihre-installation>/auth/realms/nimbus/protocol/openid-connect/token" \
  -d grant_type=client_credentials -d client_id=<CLIENT_ID> -d client_secret=<CLIENT_SECRET>

Setze das «access_token» aus der Antwort in der Shell als «AINOMOS_TOKEN». Das Token läuft nach wenigen Minuten ab; hol es bei Bedarf neu.

export AINOMOS_TOKEN="<ACCESS_TOKEN>"

Hinweis: Hermes liest die Variable «AINOMOS_TOKEN» beim Verbinden aus der Umgebung. Sie muss in der Shell gesetzt sein, in der die Hermes-Session läuft.

OAuth (empfohlen)

Hermes kann OAuth 2.1 auch selbst durchlaufen (Discovery, PKCE, Token-Exchange) und den Token selbst erneuern. Dafür statt der Header-Zeile «auth: oauth» plus den vorregistrierten Client «hermes-agent» setzen:

~/.hermes/config.yaml

mcp_servers:
  ainomos:
    url: "https://<ihre-installation>/api/mcp"
    auth: oauth
    oauth:
      client_id: "hermes-agent"

Der öffentliche PKCE-Client «hermes-agent» ist in Keycloak vorregistriert (ADR-038), wie «claude-desktop». Den OAuth-Login einmal anstossen:

hermes mcp login ainomos

Hermes öffnet dann den Browser-Login, fängt den Loopback-Callback selbst ab und erneuert den Token eigenständig. Ein Token von Hand zu holen entfällt. Der Browser-Ablauf ist verifiziert: Der Login meldet «Authorization Successful», danach hält Hermes die Sitzung selbst. OAuth ist damit der empfohlene Weg für deinen eigenen Login; den Bearer-Pfad brauchst du nur für eine Maschinen-Identität.

Skill installieren

Den governed-agent-Skill nach «~/.hermes/skills/» kopieren. Der Befehl setzt eine Kopie des NomOS-Repositorys voraus:

cp -r docs/integrations/hermes/company-brain-governed-agent ~/.hermes/skills/

Der Skill erzwingt, dass Hermes vor riskanten Aktionen (Dateien schreiben, PR öffnen, Nachrichten senden, Infra ändern, sensible Daten lesen) «validate_action» ruft und NomOS als Autorität für Policies, Entscheidungen und Wissen behandelt.

Härtung

In Profilen, die mit NomOS arbeiten, Pflicht: Schreibzugriff auf Memory und Skills nur mit Freigabe.

~/.hermes/config.yaml

memory:
  write_approval: true
skills:
  write_approval: true

• Minimales Toolset: nur freigeben, was der Anwendungsfall wirklich braucht. Das begrenzt zugleich, was am Check vorbei möglich ist.
• Kein YOLO-Modus, keine breiten lokalen Secrets.
• Getrennte Profile pro Kunde/Raum; Sandbox (Docker/Modal) wo möglich.

Die wichtigsten Werkzeuge für Hermes

list_rooms()

Listet die Räume, in denen die anfragende Person Mitglied ist. Das ist der Einstieg, um den richtigen Raum zu finden (per Slug oder Anzeigename).

ask_brain(room, question)

Liefert eine governte Antwort mit Belegen und einer «run_id» über den vollen Governance-Pfad (Retrieval, Regel-Check, Beleg). «room» akzeptiert den Slug oder den Anzeigenamen eines eigenen Mitglieds-Raums. Für Folgefragen die «conversation_id» aus der vorherigen Antwort mitgeben: Der Verlauf fliesst als Kontext ein, und die Antwort liefert die «conversation_id» mit. Belege gelten weiterhin je Antwort.

validate_action(room, action, content, tool?)

Der Laufzeit-PDP: legt eine geplante Aktion vor, bevor der Agent handelt, und erhält ein Urteil («allow», «caution», «require_approval» oder «block»), die geltenden bindenden Regeln, eine als Beratung markierte KI-Einschätzung und eine «evidence_id». Nennt die Aktion ein Werkzeug, «tool» mitgeben: Dann prüft das Urteil auch die Werkzeug-Regeln des Raums und nennt bei «require_approval» den Freigabe-Weg. «room» akzeptiert Slug oder Anzeigename.

propose_decision(room, type, title, context_md, options_md, recommendation_md)

Erfasst eine im Dialog anstehende Entscheidung als Entwurf im Raum (ADR, BDR oder SDR, mit Kontext, Optionen und Empfehlung). Bindend macht den Entscheid nur der zuständige Entscheider in der Wissens-Bibliothek; der Vorschlagende wird als Herkunft vermerkt. Pro Raum kann jede vorschlagende Identität nur eine begrenzte Zahl offener Entwürfe halten; die Raumdetails zeigen den Deckel und ob er vom Raum oder von der Installation stammt.

Testen

Prüfen, ob Hermes den Server und die Tools sieht:

Hermes

hermes mcp

Erscheinen «ainomos» und die Werkzeuge, im Chat zwei Sonden fahren:

• «list my NomOS rooms» → Hermes ruft «list_rooms()» und zeigt die erlaubten Räume.
• «validate action in room [Raumname]: delete prod database» → das Urteil sollte «block» sein.

Kooperative Prüfung und Gateway

«validate_action» ist ein kooperatives PDP: Hermes ruft es freiwillig. Ist das Hermes-Toolset nicht begrenzt, kann der Agent Werkzeuge direkt nutzen und den Check umgehen. Ohne Gateway schützen deshalb ein minimales Toolset, der verpflichtende Skill und eine Sandbox. Für Werkzeuge, die über das NomOS-Gateway laufen, setzt NomOS die Regeln technisch durch: Im Raum-Modus «Unterstützt» stoppt es blockierte Aufrufe, im Modus «Strikt» verlangt es zusätzlich Freigaben. Das Gateway schaltet der Betrieb zu; ohne diese Einstellung ist es aus.

Der End-to-End-Durchstich ist erfolgt: Hermes verbindet sich per OAuth, «list_rooms» liefert die governten Räume, «ask_brain» und «validate_action» antworten mit Urteil und Beleg. Damit ist der ganze serverseitige Pfad inklusive OAuth-Login verifiziert. Ohne Gateway hängt der Schutz am begrenzten Toolset.