Agenten in NomOS

NomOS governt zwei Arten von Agenten: solche, die es selbst ausführt, und deine eigenen, die du mitbringst. Hier steht der Unterschied und wie du beide nutzt.

Interne vs. externe Agenten

Der Unterschied ist, wer den Agenten ausführt und wie tief NomOS ihn kontrolliert.

Interner Agent

NomOS führt ihn aus (Bedrock, serverseitig). Du konfigurierst Auftrag, Werkzeuge, Autonomie, Modell, Budget. Jeder Schritt läuft durch den vollen Governance-Stack.

Externer Agent

Du führst ihn aus (Hermes, Claude Desktop, eigenes Programm). NomOS gibt ihm Identität und Regeln und governt kooperativ, was er via validate_action oder ask_brain vorlegt. Dazu kommt die Notbremse.

Bild: intern = ein Angestellter, den die Firma einstellt und steuert. Extern = ein externer Dienstleister mit Werkausweis: Zutritt und Hausordnung ja, Lohnliste nein.

Interne Agenten: von NomOS ausgeführt

Lege einen Agenten im Raum an (Tab «Agenten» → «Interne Agenten»): Auftrag, Werkzeuge (ask_brain), Autonomiestufe (L0–L3), Modell, Monatsbudget. Der geerbte Wissens-Scope kommt aus dem Raum.

Lebenszyklus: anlegen → Eval-Suite → Freigabe → Lauf → Beleg. Nur Raum-Owner (Entscheider) dürfen evaluieren und freigeben. Jeder Lauf erzeugt einen nachvollziehbaren Beleg (Urteil, Zitate, Kosten). Ändert sich die Raum-Verfassung nach der Freigabe, ist eine Re-Evaluation nötig.

Externe Agenten: Du bringst sie mit

Was ist ein externer Agent?

Ein externer Agent ist ein eigenständiges Programm, das Aufgaben ausführt: Dateien lesen, Code schreiben, Tickets bearbeiten, APIs aufrufen. Er läuft ausserhalb von NomOS; du bringst deinen Agenten mit (Hermes, Claude Desktop, Codex oder ein eigener). NomOS liefert die Governance-Schicht darunter.

Der Agent verbindet sich per MCP, fragt NomOS nach Wissen («ask_brain») und legt geplante Aktionen zur Prüfung vor («validate_action»). NomOS antwortet mit einem Urteil (allow, caution, require_approval oder block), bevor der Agent handelt. Das ist kooperative Governance: Der Agent ruft die Prüfung freiwillig auf. Die harte Absicherung ist der Kill-Switch (siehe unten).

Zwei Verbindungstypen

Wähle den Typ, der zu deinem Agenten passt. Der Unterschied ist die Identität, unter der der Agent handelt:

Per-User

Der Agent handelt in deinem Namen. Er verwendet deine OAuth-Identität und sieht genau die Räume, in denen du Mitglied bist. Geeignet für einen persönlichen Kopiloten, der deinen Raumzugriff widerspiegeln soll. Öffentlicher Client mit PKCE: Es gibt kein Secret, im verbindenden Client genügt die Client-ID.

NHI (Non-Human Identity)

Nicht-menschliche Identität: Der Agent erhält eine eigene, feste Maschinen-Identität, einen Keycloak-Service-Account mit Client-ID und Client-Secret. Geeignet für Team-Bots und Automatisierungen, die ohne Benutzersitzung laufen. Das Secret wird genau einmal angezeigt, direkt nach dem Anlegen. Danach kann es nicht mehr abgerufen werden.

Verbindungsdauer bei Per-User: Eine Verbindung hält bis zu 30 Tage ohne Nutzung, jede Nutzung verlängert sie. Erst danach musst du einmal neu verbinden.

Schritt für Schritt: eigene App verbinden

Für Claude, Cursor, VS Code oder Hermes öffnest du «Apps verbinden», wählst die App und nutzt die MCP-URL, den Deep-Link oder das fertige Snippet. Beim ersten Verbinden meldest du dich an und bestätigst, falls gefragt, den Zustimmungsdialog; vorher muss kein externer Agent angelegt werden. Nur NHI-Agenten (feste Maschinen-Identitäten) laufen über Agenten-Bereich → «Externe Agenten» → «Agenten verbinden», weil dort Client-ID und Secret entstehen. Danach testest du den ersten Aufruf: «list_rooms()» sollte deine erlaubten Räume zurückgeben.

MCP-URL

https://<ihre-installation>/api/mcp

Der Geltungsbereich von NomOS

Im Geltungsbereich

Aktionen gegen Raum-Policies und Entscheide prüfen (validate_action); kuratiertes, raum-isoliertes Wissen liefern (ask_brain); Antworten mit Personendaten in Räumen der gesperrten Datenklasse zurückhalten, bevor der Agent sie sieht (DAT-03); sofortiger Kill-Switch (ein Plattform-Admin sperrt den Agenten, der Zugang zu ALLEN Räumen ist entzogen); ein Beleg für jede Frage, jede Prüfung und jeden Antrag. Die Isolation zwischen Räumen ist erzwungen: Ein NHI-Agent sieht nur seinen Heimat-Raum, ein Per-User-Agent genau die Räume der verbundenen Person. Ein Agent kann anstehende Entscheidungen als Entwurf im Raum erfassen (propose_decision); bindend wird der Entwurf erst durch menschliche Freigabe. Er kann zudem befristete Ausnahmen beantragen (request_exception), Entscheide strukturiert lesen (list_decisions, get_decision) und Belege abrufen (get_evidence). Details in der Werkzeug-Übersicht.

Ausserhalb des Geltungsbereichs

NomOS governt den Zugriff auf Wissen, Regeln und Entscheide. Es führt den Agenten nicht aus und übernimmt nicht dessen Compute-Umgebung. Diese Trennung ist gewollt: Sie hält die Governance-Schicht unabhängig von jeder Agenten-Laufzeit, damit sie einen Werkzeugwechsel überlebt. Auf der Stufe Connected ist die Konsultation kooperativ, der Agent ruft validate_action und ask_brain selbst auf; was er nie aufruft, kann auch nicht geprüft werden. Vollständige Vermittlung ist die Stufe Enforced und eine bewusste Betriebsentscheidung mit eigenen Voraussetzungen, kein Schalter. Einzelne Laufzeit-Prüfungen wie der Secret-Scan sind als Capability im Code verdrahtet und nicht über die Policy-Oberfläche konfigurierbar.

Die siebzehn MCP-Werkzeuge im Überblick

Der Lebenszyklus eines andockenden Agenten: orientieren → entdecken → lesen → prüfen → beitragen → nachvollziehen. Dafür stellt NomOS siebzehn MCP-Werkzeuge bereit:

• list_rooms: zeigt die erlaubten Räume und einen begrenzten Themen-Digest aus aktuellen governten Entscheiden, damit der Agent zuerst den passenden Raum wählt.
• search_brain_catalog: durchsucht sichtbare Brain-Store-Angebote nach Text, Raum, Herkunft, Genre oder Publisher; die Suche liest nur und ändert keinen Raum-Scope.
• get_brain_offer: liest Metadaten, Publisher, Version, Datenklasse, Inhaltszählungen und repräsentative Titel eines sichtbaren Angebots.
• list_brain_relationships: zeigt für einen erlaubten Raum direkte, geerbte und verfügbare Brains samt exaktem next_action; es wird nichts abonniert oder beantragt.
• request_brain_access: beantragt als Owner des Zielraums den Zugriff auf ein geschütztes Corp Brain. Ein bezeichneter menschlicher Publisher-Approver entscheidet im Posteingang; die Genehmigung erstellt nie ein Abo.
• ask_brain(room, question): stellt eine Frage mit vollem Governance-Stack und liefert eine Antwort mit Belegen, einer run_id (Beleg) und einer conversation_id für Folgefragen. Ohne belastbare Grundlage ist die Beleg-Liste leer; was das Retrieval dennoch fand, steht separat als nearest_sources (Kontext, kein Beleg).
• list_decisions(room): liest die geltenden Entscheide strukturiert und deterministisch (kein LLM), inklusive geerbter (als solche markiert); mine=true zeigt, was aus den eigenen Vorschlägen wurde.
• get_decision(room, key): liest einen Entscheid vollständig: Inhalt, Status, Owner, Herkunft (z. B. «vorgeschlagen von Agent X») und Assoziationen.
• get_decision_neighbours(room, key): typisierte Nachbarn eines Entscheids, einen Schritt weit, je mit Nachbar-Titel und Art, Relationstyp, Richtung, Effekt, Kanten-Status (active steuert, proposed ist inert), maintained-Flag, Typ-Gewicht des Raums, Abruf-Priorität und Provenienz.
• get_passage(room, knowledge_object_id, version?): liest die Textstelle eines zitierten Eintrags über den autorisierten Leser: Text, Quelldokument, Version, Gültigkeit, Owner und ob es beratendes Wissen oder ein bindender Entscheid ist. Dieselben Gates wie der Leser der Oberfläche, nur die aktuelle Textstelle, version_served steht neben version_requested.
• validate_action(room, action, content, tool?): prüft eine geplante Aktion vorab gegen die Raum-Verfassung und liefert allow, caution, require_approval oder block, dazu eine Beleg-ID. Mit tool fliessen auch die Werkzeug-Regeln des Raums ins Urteil ein.
• propose_decision(room, type, title, …): erfasst eine im Dialog anstehende Entscheidung als Entwurf (ADR, BDR oder SDR); bindend macht sie erst die menschliche Freigabe. Offene Entwürfe pro vorschlagender Identität und Raum sind gedeckelt (siehe Raumdetails).
• propose_knowledge(room, title, body_md, summary, source_note): reicht im Einsatz erarbeitetes Wissen als Entwurf ins Import-Review ein; ins Gedächtnis gelangt es erst nach menschlicher Übernahme.
• list_knowledge_proposals(room): zeigt deine eigenen Wissens-Einreichungen über alle Status (Entwurf, übernommen, abgelehnt); die Rückmeldung zu propose_knowledge.
• request_exception(room, policy_key, justification, scope?): beantragt eine befristete Ausnahme von einer Leitplanke. Genehmigen kann nur ein Entscheider des Raums (Raum-Owner, Governance-Owner oder Mandanten-Admin) im Posteingang. Harte Regeln haben keinen Ausnahmepfad.
• get_evidence(run_id): öffnet den unveränderlichen Beleg-Nachweis einer Antwort (Verdikt, Regeln, Belege, Akteur, Zeit); Ein- und Ausgabe stehen nur als Hashes im Bundle, nie als Klartext.
• get_answer_relations(run_id): liest die strukturierten Governance-Relationen einer Antwort: die vom Block nachgezogenen depends_on-Voraussetzungen (samt dem ziehenden Entscheid) und die conflicts_with-Paare, als Daten. Nur lesend, kein Sprachmodell, gleiche Reichweite wie get_evidence.

Die Brain-Store-Werkzeuge lesen nur; request_brain_access reicht nur einen governten Antrag ein. Es gibt bewusst keine Werkzeuge, die Corp-Zugriff genehmigen, Brains abonnieren, Entscheide freigeben, Ausnahmen genehmigen, Räume verwalten oder löschen. Entscheidungen treffen Menschen in der governten Oberfläche.

Wo sehe ich den Agenten-Harness?

Agenten-Bereich → Raum wählen → Ansicht «Governance»: Der Abschnitt «Was ein andockender Agent bekommt» zeigt den globalen Basis-Harness, das wirksame Raum- und Client-Addendum, die Werkzeugliste und die Capability-Matrix live vom Server. Alle Raum-Mitglieder können lesen; Raum-Owner bearbeiten Standard- und Client-Fassungen.

Der globale Basis-Harness bleibt überall gleich und nicht überschreibbar. Das Standard-Addendum gilt für den Raum, bis Claude, Cursor, VS Code oder Hermes einen eigenen Fork erhalten. list_rooms und ask_brain liefern die wirksame Addendum-Quelle zusätzlich, damit ein Agent den Unterschied sieht.

Wie Agenten-Aktivität gemessen wird

Raum-Owner sehen im Detail eines externen Agenten die letzte zugeordnete Aktivität sowie 7- und 30-Tage-Zähler für governte Anfragen, MCP-Ressourcen-Lesezugriffe und Entscheid-Vorschläge. Die Projektion ist auf den gewählten Raum und den registrierten OAuth-Client begrenzt.

Die Messung ist ab Release 0.40.1 vorwärtsgerichtet und keine Lebenszeit-Summe. Entscheid-Lesezugriffe fehlen bewusst, bis list_decisions und get_decision ein vollständiges deterministisches Lese-Ereignis erzeugen; NomOS erfindet diese Kennzahl nicht aus anderen Aufrufen.

Selbst verbinden (Self-Service)

Moderne MCP-Clients (z. B. Claude) können sich selbst bei NomOS registrieren: MCP-URL im Client einfügen, der Client meldet sich automatisch an. Es braucht kein Ticket und keinen Admin-Schritt. Das Tor ist deine eigene Zustimmung: Beim ersten Verbinden erscheint ein Zustimmungsdialog, und erst mit deiner Zustimmung funktioniert die Verbindung.

Der Zustimmungsdialog zeigt, welche Berechtigungen die App anfragt: Identität, Profil, E-Mail und, falls die App ihn anfordert, dauerhaften Zugriff (die Verbindung bleibt dann ohne erneutes Anmelden bestehen und ist jederzeit widerrufbar). Die Verbindung läuft unter deiner eigenen Identität: Die App sieht genau das, was du selbst sehen darfst, ohne zusätzliche Rechte. Fragt die App später mehr an, wirst du erneut um Zustimmung gebeten.

Ohne Zustimmung läuft nichts. Bis du beim ersten Verbinden zustimmst, steht eine selbst registrierte App als «Wartet auf erste Zustimmung» in der Plattform-Übersicht; diese Übersicht sehen nur Plattform-Admins. Dort sehen sie jede selbst registrierte Verbindung («Selbst registriert») und können sie jederzeit über den Kill-Switch abschalten. Jede Aktion läuft weiterhin durch den vollen Governance-Stack: Policies, Schutz von Personendaten, Belege.

Geführtes Verbinden

Wer Claude, Cursor, VS Code oder Hermes anschliessen will, findet in der Galerie «Apps verbinden» pro Client den Self-Service-Weg mit echtem Endpoint, Deep-Link oder fertigem Snippet, ohne vorher einen Agenten anzulegen. Nur für eine Maschinen-Identität (NHI) legt der Raum-Owner einen Agenten unter «Externe Agenten» an.

Zur Galerie: Apps verbinden

Team-Verbindungen für Organisationen

Organisationen müssen die Verbindung nicht jedem Mitglied einzeln erklären: Unterstützt der Client Team-MCP (etwa Cursor im Dashboard unter «Integrations & MCP»), hinterlegt ein Team-Admin den NomOS-Server einmalig zentral. Er steht dann allen Mitgliedern zur Verfügung, auch automatisierten Cloud Agents, ohne dass jemand die Adresse selbst eintragen muss.

Der Zugriff bleibt trotzdem pro Person governt: Jedes Mitglied meldet sich beim ersten Verbinden einzeln an und bestätigt seinen eigenen Zustimmungsdialog; die Identität bleibt per-User. Eine Verbindung sieht immer nur, was das jeweilige Mitglied selbst sehen darf, und jede Verbindung erscheint einzeln unter «Meine Verbindungen» und in der Plattform-Übersicht der Admins.

MCP-Konfiguration

Für Per-User-Apps zeigt «Apps verbinden» direkt die MCP-URL, den Deep-Link oder ein fertiges Snippet; beim ersten Aufruf startet der OAuth-Flow mit deiner Zustimmung. Nur bei NHI-Agenten erzeugt der Wizard zuerst Client-ID und Secret, die du anschliessend in die Agenten-Konfiguration übernimmst (z. B. «~/.hermes/config.yaml» für Hermes).

.mcp.json: Per-User (OAuth-Flow beim ersten Aufruf)

{
  "mcpServers": {
    "ainomos": {
      "type": "http",
      "url": "https://<ihre-installation>/api/mcp"
    }
  }
}

NHI, Schritt 1: Zugriffs-Token holen (client_credentials; das Secret wird getauscht, nicht als Bearer benutzt)

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>
# Antwort: { "access_token": "eyJ…" }. Dieses JWT im nächsten Schritt als Bearer einsetzen.
# Hinweis: das Token laeuft ab (Minuten) → bei Bedarf neu holen (Client mit Auto-Refresh).

.mcp.json für NHI, Schritt 2: das access_token als Bearer (Service-Account)

{
  "mcpServers": {
    "ainomos": {
      "type": "http",
      "url": "https://<ihre-installation>/api/mcp",
      "headers": {
        "Authorization": "Bearer <ACCESS_TOKEN>"
      }
    }
  }
}

Beispiel-Anwendungsfälle

• Support-Agent: Ein selbst-lernender Chatbot prüft jede Antwort via validate_action gegen die Team-Policies, bevor er antwortet. So verlässt keine Antwort den Agenten ungeprüft.
• Dev/Coding-Agent: Ein Coding-Agent validiert vorgeschlagene Codeänderungen gegen die Architekturentscheide (ADRs) des Teams, bevor er einen PR öffnet.
• Research/Analyse-Agent: Ein Analyse-Agent muss Regeln für Personendaten einhalten. In Räumen der gesperrten Datenklasse hält NomOS Antworten mit Personendaten zurück, bevor der Agent sie sieht.
• Ops-Automatisierung (NHI): Ein unbeaufsichtigter Bot (z. B. für Nacht-Deployments) läuft als NHI. Der Kill-Switch des Plattform-Admins ist die Sicherheitsbremse.

Häufige Fragen

Was ist der Unterschied zwischen einem internen und einem externen Agenten?

Einen internen Agenten führt NomOS aus; du konfigurierst sein Verhalten, und jeder Schritt läuft durch den vollen Governance-Ablauf. Einen externen Agenten führst du aus; NomOS governt ihn kooperativ über MCP und hält den Kill-Switch bereit.

Wann nehme ich welchen?

Soll NomOS den Agenten betreiben (gehosteter Assistent mit Auftrag und Budget) → intern. Hast du schon einen eigenen Agenten und willst ihn nur governen → extern.

Führt NomOS meinen externen Agenten aus?

Nein. Ein externer Agent läuft ausserhalb; NomOS antwortet nur auf seine MCP-Aufrufe und governt sie. Die harte Absicherung ist der Kill-Switch.

Wo lege ich welchen an?

Beide auf der Agenten-Seite im Raum: interner Agent über «anlegen» (Auftrag/Werkzeuge), externer über «verbinden» (Per-User/NHI). Beim Erstellen eines internen Agenten gelten 2–63 Zeichen für die Kennung (Kleinbuchstaben, Zahlen, Bindestriche) und ein positives Budget. Feldfehler werden am Eingabefeld angezeigt; bei einem Serverfehler bleiben deine Eingaben erhalten. Fehlgeschlagene Werkzeugabfragen kannst du erneut laden. Du kannst einen Entscheidungsentwurf selbst vorbereiten. Das ist keine automatisch erkannte Freigabelücke und keine Freigabe. Typ, Titel und Grundlage sind vor dem Speichern zu prüfen.

Wo finde ich das Secret eines Per-User-Agenten?

Es gibt keines. Per-User-Agenten sind öffentliche Clients mit PKCE: Der Nachweis kommt aus dem OAuth-Login der Person. Nur NHI-Agenten haben ein Secret (einmalig beim Anlegen sichtbar). Die Knöpfe in der Detail-Ansicht kopieren Client-ID bzw. MCP-Konfiguration.

Was ist der Unterschied zwischen Per-User und NHI?

Per-User: Der Agent handelt mit deiner Identität (deine Räume, deine Rechte). NHI: Der Agent hat eine eigene Maschinen-Identität. Er ist nicht an eine Person gekoppelt und eignet sich für Team-Automatisierungen.

Wo kommt das Client-Secret her, und was tue ich, wenn ich es verliere?

Das Secret erzeugt Keycloak beim Anlegen eines NHI-Agenten. Es wird genau einmal im Wizard angezeigt; kopiere es sofort. Geht es verloren, gibt es keine Möglichkeit, es wieder abzurufen. Die einzige Lösung: den Agenten entfernen und neu anlegen.

Was macht der Kill-Switch genau?

Ein Plattform-Admin kann einen Agenten sofort sperren. Damit wird der Keycloak-Client des Agenten deaktiviert, und der Zugang zu ALLEN Räumen ist augenblicklich entzogen, unabhängig davon, wie viele Räume der Agent hatte.

Kann ein gesperrter Agent wieder entsperrt werden?

Ja. Ein Plattform-Admin kann einen gesperrten Agenten unter Administration → «Externe Agenten» mit «Reaktivieren» wieder freischalten; das wird als Beleg festgehalten. Ein widerrufener Agent bleibt dauerhaft gesperrt.

Kann der Agent Daten aus anderen Räumen sehen?

Nur aus Räumen, zu denen seine Identität gehört. Ein NHI-Agent sieht nur seinen Heimat-Raum. Ein Per-User-Agent sieht genau die Räume der verbundenen Person. Ein Aufruf auf einen anderen Raum scheitert mit einem 403-Fehler; die Isolation ist im Backend erzwungen.

Führt NomOS meinen Agenten aus?

Nein. NomOS stellt eine MCP-Schnittstelle bereit, und dein Agent ruft die Werkzeuge auf. NomOS führt keinen Code deines Agenten aus und kontrolliert nicht dessen Compute-Umgebung.

Welche Daten bekommt der Agent zurück?

ask_brain liefert eine governte Antwort mit Belegen, Owner, Gültigkeitsdatum und Beleg-ID, identisch zum Web-UI. validate_action liefert ein Urteil (allow, caution, require_approval oder block), die geltenden bindenden Regeln, eine KI-Einschätzung (markiert als beratend) und eine Beleg-ID.

Wie werden PII-Daten behandelt?

NomOS prüft Antworten mit Presidio auf Personendaten (DAT-03). In Räumen der gesperrten Datenklasse hält ask_brain eine Antwort mit Personendaten zurück, bevor der Agent sie sieht; in anderen Räumen geht sie durch. validate_action markiert Personendaten in einer geplanten Aktion als «caution». Die Erkennungsschwelle stellt der Plattform-Admin ein.

Wer darf einen Agenten anbinden?

Agenten im Raum anlegen oder entfernen kann nur der Raum-Owner. Jedes Mitglied kann aber eigene Apps über «Apps verbinden» unter seiner eigenen Identität anschliessen. Der Plattform-Admin sieht alle Agenten plattformweit und kann jeden über den Kill-Switch sperren.