Agenten und Dauerberechtigungen — Dokumentation

Niemand in der Schleife — so gewollt

CommandAGI ist für Maschinen gebaut, die ohne Aufsicht laufen. Ein Agent mit einer Berechtigung schaltet eine Einheit scharf, führt Programme aus und sendet Befehle in Echtzeit, über die Werkbank, die API oder MCP, ohne Bestätigung für jede Aktion. Was das sicher macht, ist keine Person, die zusieht; es sind die Berechtigung, die Grenzen des Treibers und das Protokoll.

Prinzipale

Alles, was handelt, ist ein Prinzipal: agent:<name> oder person:<name>. Ein Prinzipal weist sich mit einer Zugangsdatei aus — er nennt sich nie nur selbst. Eine Anfrage, die nur behauptet, wer sie ist, wird abgelehnt.

Host-Zugangsdatei — cagp_…, einmal ausgestellt von commandagi grant token --principal agent:<name> (oder wenn eine Berechtigung hinzugefügt wird). Der Host speichert nur deren SHA-256. grant token rotiert sie; grant forget entfernt sie.
Konto-Zugangsdatei — cagc.<payload>.<signature>, signiert mit dem Schlüssel Ihres Kontos (Ed25519) für Agenten, die in der Cloud laufen. Sie nennt den Prinzipal, das Konto, ein Ablaufdatum und optional einen Host. Sie wird nur für Berechtigungen akzeptiert, die dieses Konto erteilt hat. Widerrufen mit grant revoke-credential.

Dauerberechtigungen

Eine Dauerberechtigung ist eine Befugnis, die ein Konto einem Prinzipal gibt, durch eine ausdrückliche Handlung einer Person. Keine Werkzeug- oder Agentenroute erstellt oder erweitert eine Berechtigung; der API-Schlüssel eines Agenten wird auf jeder Route abgelehnt, die Befugnisse ändert.

shell

commandagi grant add --principal agent:night-shift \
  --world shop --unit mill-1 --channel gcode \
  --verb open --verb arm --verb run --verb send \
  --for 8h --note "night shift"
commandagi grant list
commandagi grant revoke g-3f9a1c20b7de

Eine Berechtigung nennt eine Welt und optional Einheiten, Kanäle und Verben — lässt man eines weg, gilt es für alle. Sie kann ablaufen (--for 8h, --expires <ISO-Zeit>). Berechtigungen werden in ~/.commandagi/grants.json gespeichert, bei jeder Aktion gelesen und können auch in der Werkbank unter Einstellungen → Berechtigungen erstellt werden. Eine fehlerhafte Berechtigungsdatei gewährt gar keine Berechtigung.

json

{ "grants": [ { "id": "g-3f9a1c20b7de", "principal": "agent:night-shift",
  "grantedBy": "acct:user:u_8f2k", "world": "shop", "units": ["mill-1"],
  "channels": ["gcode"], "verbs": ["open", "arm", "run", "send"],
  "expires": "2026-10-01T06:00:00Z", "note": "night shift" } ] }

Derselbe Befehl erstellt drei weitere Arten von Berechtigungen: --file PREFIX… (Dateien unter einem Pfad schreiben), --outreach APP… --per-day N (Nachrichten über verbundene Apps senden) und --market VENUE… --symbol S --max-qty N --max-notional N --per-day N (Aufträge platzieren).

Berechtigungen gelten für physische Welten. Eine Simulationswelt braucht keine.

Verben, Scharfschalten und Sichern

Eine Berechtigung kann vier Verben geben: einen Kanal öffnen, eine Einheit scharf schalten, ein Programm ausführen, einen Befehl senden.

Treiber, die Hardware bewegen, öffnen unscharf. Jeder Prinzipal mit einer Berechtigung für die Einheit kann sie scharf schalten. Eine scharfe Sitzung, die fünf Minuten untätig ist, schaltet sich selbst unscharf.
Treiber, die nur Eingaben annehmen — eine Shell, ein Python-Kernel, eine Auftragsübergabe — brauchen kein Scharfschalten; die Berechtigung wird bei jeder Eingabe geprüft.
Sichern ist immer erlaubt. stop, disarm und close — und Sicherungsbefehle wie Vorschub halten, Pause, Notaus und Drehmoment aus — sind jedem erlaubt, der irgendeine nicht abgelaufene Berechtigung für die Einheit hat, wer die Sitzung geöffnet hat, und der Person des Kontos selbst. Das Stornieren eines offenen Auftrags zählt ebenfalls als Sichern.

Die Regeln, denen jede Aktion folgt

Vor dem Senden aufgezeichnet. Bevor der Treiber aufgerufen wird, wird ein Vermerk — der Prinzipal und die Aktion — an den Datenstrom des Laufs angehängt und geschrieben. Ein schreibgeschütztes Projekt lehnt die Aktion ab, statt ohne Protokoll zu handeln.
Eine Bestätigung ist kein Zustand. Eine Antwort oder ein ok bedeutet nie, dass der befohlene Zustand erreicht wurde. Befehle bleiben ausstehend, bis die Maschine einen Zustand meldet.
Unbekannt bleibt unbekannt. Ein verlorener Link wird als state: unknown aufgezeichnet. Ein Datenstrom, der ohne Endesatz endet, gilt als unterbrochen: Zustand unbekannt.
Keine stillen Wiederholungen. Ein physischer Befehl wird vom System nie wiederholt. Ein Agent kann entscheiden, es erneut zu versuchen; diese Entscheidung ist ein eigener aufgezeichneter Befehl.
Grenzen liegen beim Treiber. Deklarierte Grenzen, Mindestabstände und erlaubte Verben werden vom Treiber durchgesetzt, nicht von einer Person. Eingabedatenströme sind getaktet: eine Aktion nach der anderen, mindestens 30 ms auseinander.
Simulation und Physik werden nie gemischt. Ein Lauf gehört zu einer Welt, und die Quelle seiner Datensätze muss der Art der Welt entsprechen.

Unterhaltungen und ihr Agent

Eine Unterhaltung, die in einer physischen Welt startet, gewährt dem Agenten der Unterhaltung (threads.agent, standardmäßig agent:mcp) jedes Verb auf den Einheiten dieser Welt, für höchstens 24 Stunden, und widerruft es, wenn die Unterhaltung geschlossen wird. Ausschalten mit der Einstellung "threads.agentControl": false.

Weiter

Verbinden Sie einen Agenten über MCP mit all dem: SDK und MCP.

Agenten und Dauerberechtigungen.