KI Agenten

Abhängigkeiten · Data Nodes

Bezüge zu: Kompetenzen (über AGENT_USES_COMPETENCE), Richtlinien (über AGENT_BOUND_BY_POLICY), Wertschöpfung (über AGENT_SUPPORTS_PROCESS), Rollen (über AGENT_FULFILLS_ROLE)

Wird bezogen von: Bedarfe (über REQUESTS_MEMBER)

Der Entitätstyp „KI-Agent” führt einen digitalen Akteur als vollwertigen Knoten im Org-Graphen. Den Überblick, warum es das gibt, liefert KI Agenten — Überblick.

Wozu

Ein Agent trägt einen Zweck, Instruktionen (Persona/System-Prompt), optionale Fähigkeiten und einen Status (draft, active, retired). Sein eigentlicher Kontext entsteht aber nicht aus diesen Feldern, sondern aus seinen Verknüpfungen im Graphen.

Standardansicht

Cards mit Name, Zweck und Status. Wie bei allen Entitätstypen mit Entwürfen, Sichtbarkeit und Änderungshistorie.

Wichtige Beziehungen

Vier dedizierte Beziehungstypen verankern den Agenten:

AGENT_FULFILLS_ROLE (Agent → Rolle) — „erfüllt Rolle” / „wird erfüllt durch Agent”
AGENT_SUPPORTS_PROCESS (Agent → Wertstrom) — „unterstützt Wertstrom”
AGENT_USES_COMPETENCE (Agent → Kompetenz) — „nutzt Kompetenz”
AGENT_BOUND_BY_POLICY (Agent → Richtlinie) — „gebunden an Richtlinie” / „bindet Agent” — die Guardrail-Kante.

Diese Typen entstehen erst, wenn das Agenten-Modul in deinem Mandanten aktiv ist — und jeder einzelne zusätzlich erst dann, wenn auch seine Gegenseite ein Modul hat: AGENT_SUPPORTS_PROCESS braucht das Wertschöpfungs-Modul, AGENT_USES_COMPETENCE das Kompetenz-Modul. Fehlt eine Seite, ist der Typ schlicht nicht da und kommt bei der nächsten Aktivierung von selbst dazu.

Details: Beziehungstypen.

Schritt für Schritt

Agent anlegen — in der Ansicht „KI Agenten” auf „Neuer Agent”, Zweck und Instruktionen eintragen.
Verknüpfen — im Detailbereich unter „Beziehungen” den Agenten mit einer Rolle (AGENT_FULFILLS_ROLE), Wertströmen, Kompetenzen und bindenden Policies (AGENT_BOUND_BY_POLICY) verbinden.
Kontext ansehen — die Detailseite zeigt unter Agenten-Kontext das gebündelte Ergebnis: getrennt nach Guardrails (bindende Policies) und Kontext (Rollen/Wertströme/Kompetenzen).
Per MCP abrufen — externe Agenten und Automationen ziehen dasselbe Bündel über das MCP-Tool get_agent_context bzw. GET /api/agents/{uuid}/context.

Beispiel-Schema zum Kopieren

{
  "type": "object",
  "properties": {
    "purpose": { "type": "string", "title": "Zweck" },
    "instructions": { "type": "string", "title": "Instruktionen (Persona)" },
    "capabilities": { "type": "string", "title": "Fähigkeiten" },
    "status": { "type": "string", "title": "Status", "enum": ["draft", "active", "retired"] },
    "defaultModel": { "type": "string", "title": "Bevorzugtes Modell" }
  }
}

Details zu Schema-Optionen: JSON-Schema für Entitätstypen.

Grenzen: Durchsatz und Budget

Ein KI-Agent ist kein unendlicher Mitarbeiter. Ist die Bedarfsplanung für den Mandanten aktiv, trägt der Agententyp deshalb zwei Felder mehr:

Feld	Was es begrenzt
Wochenstunden	Der Durchsatz — auch mit unbegrenztem Budget schafft ein Agent in einer Periode nur eine bestimmte Menge. Bewusst dieselbe Einheit wie beim Menschen, damit sie mit dem Bedarf vergleichbar ist.
Budget je Periode	Das Geld — jeder Lauf kostet Tokens. Eine andere Währung, deshalb nicht in Stunden umgerechnet, sondern daneben angezeigt.

Beide sind Zusagen, keine Messungen: sie sagen, wie viel Arbeit und wie viel Geld dem Agenten zusteht — nicht, was er technisch leisten könnte. Genau wie beim Menschen: auch dessen Kapazität steht im Vertrag, nicht auf einer Stoppuhr.

Fehlt eine der beiden Angaben, zeigt die Auslastung „Grenze nicht hinterlegt” — nie ein Unendlichzeichen. Der Unterschied zwischen hat keine Grenze und wir haben keine eingetragen ist genau der, an dem Planungen scheitern.

roleALPHA führt Agenten nicht aus. Es beschreibt sie und liefert ihnen Kontext; laufen tun sie in Ihrer Umgebung. Der tatsächliche Verbrauch entsteht dort und ist hier nicht messbar. Wer ihn danebenlegen will, kann ihn aus der Agenten-Laufzeit einmelden; ohne Meldung steht „Verbrauch wird nicht gemeldet” — nicht Null. Null hieße, der Agent habe nichts verbraucht, und das weiß roleALPHA nicht.

Mehr dazu: KI-Agenten haben Grenzen.

Das Kontext-Bündel

Jedes Element im Bündel ist selbstbeschreibend: kind (role/process/competence/policy), binding (guardrail vs. informational), provenance (Beziehungstyp, direkt/vererbt), bei Policies eine version und die sourceService. So kann ein konsumierender Agent eine Policy nie versehentlich als bloßen Kontext behandeln. Zusätzlich trägt das Bündel eine contextVersion — einen billigen Änderungs-Hash (siehe unten).

Zugang für externe Agenten (API-Key)

Damit ein echter externer Agent seinen Kontext ziehen kann, bekommt jeder Agent im Detailbereich unter Agenten-Zugangsschlüssel eigene, einzeln widerrufbare API-Keys. Der Schlüssel wird nur einmal angezeigt — sofort kopieren.

Der Agent präsentiert ihn als Header x-agent-key: agt_… (REST und MCP) und zieht damit nur seinen eigenen Kontext:

REST: GET /api/agents/<uuid>/context (liefert die kanonische, ungefilterte Agent-Sicht)
MCP: Tool get_agent_context gegen den Agent-MCP-Endpoint

Die konkrete, kopierbare REST- und MCP-URL für genau diesen Agenten steht im Detailbereich unter Agenten-Zugangsschlüssel → Verbindung (der Host ist deployment-abhängig). Typische Form:

REST: https://<host>/api/agents/<uuid>/context
MCP: https://<host>/mcp/agent/mcp

Ein Key ist an seinen Agenten gebunden — der Versuch, damit den Kontext eines anderen Agenten zu ziehen, wird mit 403 abgelehnt.

Kontext-Änderungen erkennen

Pull (Standard): Der Agent zieht den Kontext vor jedem Lauf — immer frisch.
Billiger Check: GET /api/agents/<uuid>/context/version liefert nur die contextVersion. Ändert sie sich (neue Verknüpfung, geänderter Zweck), muss der Agent das volle Bündel neu ziehen.
Push (optional): Unter Kontext-Webhooks eine URL registrieren. Bei einer Änderung schickt roleALPHA eine signierte Benachrichtigung (X-RA-Signature: sha256=…, HMAC über den Body mit dem einmalig gezeigten Signatur-Secret).

Debug-Pull (für Administratoren)

Im Expert-Modus zeigt die Agenten-Kontext-Sektion einen Debug-Bereich mit dem Roh-JSON (kopierbar) und der contextVersion. Über „Als Agent ziehen” sieht ein Admin exakt das ungefilterte Bündel, das der Agent selbst über seinen Key bekäme.

rAlph

Der Assistent rAlph kann get_agent_context selbst aufrufen, sobald der Tenant das Modul KI Agenten in den KI-Einstellungen (allowed_services) freigibt und der Nutzer agent:read hat. Um genau die ungefilterte, externe Agenten-Sicht (dieselbe wie „Als Agent ziehen” oben) direkt im Chat zu sehen — statt der eigenen gefilterten Sicht — nutze den dedizierten Slash-Befehl /agent-context (nur Admins).

Verwandt

KI Agenten — Überblick — Überblick: Was KI Agenten ist und was nicht
Rollen — Rollen, die ein Agent erfüllt
Wertschöpfung — Wertströme, die ein Agent unterstützt
Kompetenzen — Kompetenzen, die ein Agent nutzt
Richtlinien — Richtlinien als Guardrails
Beziehungstypen — AGENT_FULFILLS_ROLE, AGENT_BOUND_BY_POLICY u.a.
rAlph – Slash-Befehle (/help, /report, /drafts) — rAlph-Slash-Befehle, inkl. /agent-context