Agents-Übersicht

Ongrid ist ein Multi-Agent-ReAct-System. Der Benutzer spricht immer mit dem coordinator — der Top-Level-Persona auf der Chat-Oberfläche. Wenn eine Aufgabe in eine spezialisierte Domäne passt (tiefgehende Grundursachen-Untersuchung, Review einer mutierenden Aktion, Netzwerk-Tiefenanalyse), dispatcht der coordinator zu einem Sub-Agenten (einem „worker") über das AgentTool. Jeder worker führt denselben Graph-Kernel gegen eine gefilterte Tool-Tasche aus und liefert eine endgültige Antwort, die der coordinator in seine Antwort einwebt.

Diese Seite ist die Karte. Die Per-Persona-Seiten erklären jeden Agenten im Detail.

Personas, keine Chat-Threads

Eine Persona ist eine On-Disk-Datei, die beschreibt, was ein Agent tut. Das kanonische Layout — gleiche Form wie Claude Codes Agent-Format mit snake_case-Keys:

---
name: specialist-disk
description: 文件系统 / 磁盘容量专家 — du / find / stat / inode / 挂载 / 大文件
when_to_use: |
  When the task is about disk / filesystem health:
    - Disk full / utilization climbing
    - Hunt for large files / large directories
    - inode exhaustion / mount point inspection
tools:
  - query_knowledge
  - host_find_large_files
  - host_du_summary
  - host_stat_file
  - host_bash
  - query_promql
  - get_host_load
permission_mode: read-only
max_turns: 15
---
[markdown body — this becomes the system prompt]

Der Body unterhalb des Frontmatters ist der SystemPrompt. Zwei Persona-Dateien mit demselben name kollidieren, und der Loader protokolliert eine Warnung. Siehe Persona-Format-Referenz für jedes Feld.

Personas liegen unter ./agents/ im Manager-Image (/app/agents/ innerhalb des Containers). Ongrid liefert eingebaute Personas im Image aus und liest auch nutzerverfasste Personas aus einem gemounteten Verzeichnis — siehe Benutzerdefinierte Agenten.

Coordinator vs. Worker

Aspekt	Coordinator	Worker
Wer spricht mit Benutzer	Ja (über Chat-Oberfläche oder IM)	Nie — Worker-Ausgabe geht zum Coordinator
Tool-Tasche	Breit: query_*, AgentTool, Redirect-Stubs	Schmal: persona tools:-Whitelist
Persona-Name	default (oder Per-Org-Override)	specialist-*, incident-investigator, reviewer
Gespawnt von	Runtime (eine pro Chat-Session)	AgentTool oder review_gate-Decorator
Kann spawnen	Ja (Workers)	Nein (Workers können absichtlich nicht verschachtelt werden)
Session	Langlebig, persistiert	Neue Session pro Spawn, auf einen Turn beschränkt

Die Aufgabe des coordinators ist Dispatch + Triage + Synthese. Deep-Dive-Tools liegen auf den Workers. Der coordinator trägt RedirectStub-Slots für Tools, die das LLM bekanntermaßen halluziniert (host_bash, get_host_load, …); ein Aufruf einer dieser gibt eine Redirect-Nachricht zurück, die das Modell anstupst, über AgentTool erneut aufzurufen.

AgentTool

Das Dispatch-Primitive des coordinators. Wire-Name AgentTool (PascalCase zur Angleichung an Claude Codes Tool-Katalog). Das LLM-sichtbare Schema:

{
  "type": "object",
  "properties": {
    "description":   {"type": "string"},
    "subagent_type": {"type": "string"},
    "prompt":        {"type": "string"}
  },
  "required": ["description", "subagent_type", "prompt"]
}

• description — 1-Zeilen-Aufgabenzusammenfassung, die das SPA-Tile verwendet.
• subagent_type — Persona-name. Der in den System-Prompt des coordinators injizierte Katalog listet gültige Werte (die Persona-Registry, minus reviewer und default).
• prompt — vollständiges Aufgaben-Briefing. Der Worker kann den Kontext des coordinators nicht sehen — packen Sie jedes benötigte Detail (incident_id, device_id, exakte Wortwahl).

Der Aufruf ist aus Sicht des coordinators synchron. Er blockiert, bis der Worker completed / failed / killed erreicht. Eine frühere Revision hatte einen async background: true-Flag; schwache Modelle nahmen ihn, beantworteten den Benutzer mit der ausstehenden task_id und folgten nie nach. Der Flag ist heute weg (siehe agent_tool.go für den Post-Mortem-Kommentar). Der einzige asynchrone Pfad ist der reviewer — und der wird vom Decorator getrieben, nicht vom LLM.

Dedupe ist eingebaut

Ein 120s LRU, der per sha256(subagent_type + canonical(prompt)) gekeyt ist, kurzschließt den zweiten von zwei identischen AgentTool-Aufrufen. Das LLM sieht das vorherige Ergebnis mit einem expliziten „du hast das bereits dispatched"-Hint. Senkt Coordinator-Loop-Ausbrüche (E2E-Eval D1 sah 122 Tool-Aufrufe in 240s ohne Dedupe).

Wie ein System-Prompt komponiert wird

ComposeSystemPrompt baut den Prompt, den das LLM empfängt, in dieser Reihenfolge zusammen:

1. basePrompt — die universelle Präambel der Runtime. Kann leer sein.
2. agentProfile.SystemPrompt — der Markdown-Body der Persona. Coordinator kann einen tragen (die meisten tun das); Worker immer.
3. agentProfile.CriticalReminder — eingewickelt in <critical-reminder>...</critical-reminder>. Dies ist die persona-level Konstante; die Graph-Schicht reinjeziert sie außerdem pro-Turn als <system-reminder>, damit sie Long-Session-Attention-Drift überlebt.
4. Für jedes aktive Skill: ein [能力: <name>]-Header + der PromptBody des Skills.

Der coordinator erhält einen Extra-Block vor der Skill-Liste: den Agent-Katalog (buildAgentCatalog) — eine Markdown-Aufzählung „verfügbarer Specialists" mit der description und der ersten Zeile von when_to_use. Der Katalog schließt absichtlich reviewer aus (nur der ReviewGate-Decorator darf ihn spawnen) und default (die virtuelle Top-Level-Persona — sie als spawnbaren Sub-Agenten aufzulisten, würde dem coordinator erlauben, sich selbst rekursiv zu spawnen).

Die Agent-Registry

Die AgentRegistry hält geparste Personas im Speicher. Einmaliges Laden beim Start; Reload() unter einem einzelnen sync.RWMutex-Swap, sodass ein in-flight Coordinator-Turn nie eine halb geladene Registry beobachtet.

Methode	Wann
Load(root)	Start. Durchläuft <root>/**/*.md rekursiv.
Reload(root, ...)	Marketplace-Install/Uninstall. Atomarer Swap.
ByName(name)	Lookup zur Spawn-Zeit. Gibt (nil, false) bei Miss zurück.
Replace(ag)	User-Agent-Edit. Upsert in place — Live-Registry, kein Restart.
Remove(name)	User-Agent-Delete.

Per-Datei-Parse-Fehler landen als Warnungen statt den Walk abzubrechen (gleiche Policy wie die Skill-Registry). Nicht existierende Agent-Roots sind kein Fehler — man bekommt eine leere Registry, keinen Startup-Fehler.

Reviewer und das Review-Gate

Der reviewer ist speziell: der coordinator kann ihn nicht spawnen. Er wird durch den ReviewGate-Decorator gegated, der jedes Tool umhüllt, dessen Class "write" oder "destructive" ist. Der Decorator:

1. Baut eine Vorschlags-Payload (action, target, reason, blast_radius, operator).
2. Spawnt den reviewer-Worker (synchron aus Sicht des inneren Tools) mit eigenem 60s-Timeout, unabhängig vom 15s-Timeout des inneren Tools.
3. Wenn der reviewer Decision: approve zurückgibt, fällt der Aufruf durch das innere Tool. Andernfalls gibt der Decorator ErrReviewRejected zurück, das den Grund des reviewers umhüllt.

Deshalb lässt der Agent-Katalog reviewer weg: nur der Decorator darf ihn aufrufen. Ihn in den Katalog zu setzen, würde dem coordinator erlauben, Ad-hoc-„Reviews" zu dispatchen, die nichts gaten.

Siehe Reviewer für die vollständige Zustandsmaschine.

Worker-Lebenszyklus

Runtime.SpawnWorker Zustandsmaschine:

pending  → running  → completed
                   ↘ failed
                   ↘ killed     (StopWorker called while running)

• Eine chat_sessions-Zeile wird im Voraus erstellt, damit Audit- + Parent → Worker-Tree-Abfragen aufgelöst werden, auch während der Worker noch läuft.
• Background-Spawns leiten sich vom langlebigen Runtime-Kontext ab, damit ein zu Ende gehender HTTP-Request den Worker nicht mitten im Lauf abreißen kann; Sync-Spawns erben den ctx des Aufrufers.
• Die Session-Zeile wird auf jedem terminalen Pfad geschlossen (closed_at gesetzt), einschließlich Panics — ohne das akkumulieren sich Waisen-Zeilen (die Testumgebung erreichte 161, bevor der Fix landete).

Workers können keine Workers spawnen. SpawnWorker ist nur auf der Runtime exponiert, und der disabledForWorker-Filter entfernt AgentTool aus der Tool-Tasche jedes Workers. Ein Coordinator, N parallele Workers, keine tiefere Verschachtelung.

Was als Nächstes kommt

• Coordinator — die Standard-Persona, ihre drei Steuer-Tools und wann zu dispatchen vs. direkt zu antworten.
• Incident investigator — Grundursache zum „Patient Zero", das 18-Tool-Budget und die F1-Eval.
• Specialists — compute / disk / network / ops / sre, was jeder besitzt, wie der coordinator auswählt.
• Reviewer — das SOP-Double-Sign-Gate auf mutierenden Tools.
• Benutzerdefinierte Agenten — eigene Persona verfassen, Hot-Reload, Debug.