Agent-Persona-Format

Eine Agent-Persona ist eine Markdown-Datei, die beschreibt, wie sich ein Agent — ein coordinator, ein incident investigator, ein specialist — verhält: welche Werkzeuge er aufrufen kann, auf welchem Modell er läuft, wie viele ReAct-Turns er bekommt und welchen System-Prompt er trägt.

Source of truth: Agent in internal/manager/biz/aiops/chatruntime/types.go.

On-Disk-Form

---
name: incident_investigator
description: Walk an incident from symptom to root cause, calling host + observability tools.
when_to_use: When the user asks why an alert is firing, or shares an incident link.
tools:
  - expand_topology
  - find_topology_node
  - query_promql
  - search_logs
  - query_traceql
  - host_probe
  - bash
disallowed_tools: []
permission_mode: read-only
max_turns: 24
model: anthropic/claude-sonnet-4-6
critical_reminder: |
  Always show your evidence. Cite the PromQL / LogQL / file path. Never speculate
  beyond what the tools returned.
initial_prompt: |
  You are investigating incident {{ '{{' }}.incident_id{{ '}}' }} on device {{ '{{' }}.device_id{{ '}}' }}.
  Start by reading the incident summary.
background: false
omit_claude_md: false
metadata:
  os: [linux, darwin]
  requires:
    bins: []
    config: []
  ongrid:
    scope: manager
---

# Incident investigator

You are an SRE-grade incident investigator. Given an incident, your job is to:

1. Pull the alert detail and any attached evidence (alert summary, snapshot).
2. Expand the device's topology to understand the blast radius.
3. Query the relevant signal (metric / log / trace) to confirm the symptom.
4. Walk upstream services / underlying resources until you find the root cause.
5. Return an evidence-backed answer in plain language.

When the user asks a follow-up, stay grounded in tool output. If you cannot
verify a claim with a tool call, say so explicitly and stop.

Der Frontmatter ist YAML. Der Body (nach ---) ist der System-Prompt, den das Worker-LLM sieht. Whitespace und Markdown-Formatierung im Body bleiben wortgetreu erhalten.

Frontmatter-Felder

Feld	Typ	Pflicht	Beschreibung
name	string	ja	Agent-Bezeichner, der beim Spawn verwendet wird (/v1/agents/{name}).
description	string	ja	Menschenlesbarer Listing-String, der im Agent-Picker angezeigt wird.
when_to_use	string	ja	Hinweis für die Spawn-Entscheidung des Coordinators. Der Coordinator liest dies bei der Entscheidung, welchen Specialist aufzurufen.
tools	string[]	nein	Explizite Werkzeug-Whitelist. Leer = von der Policy erben (jedes Werkzeug, das die Rolle des Benutzers sehen kann).
disallowed_tools	string[]	nein	Blacklist, die nach der Whitelist angewendet wird. Schwarz gewinnt gegen Weiß.
permission_mode	enum	nein (Standard read-only)	read-only, mutating-with-confirm, dual-sign-required. Steuert, welche Werkzeugklassen ohne Bestätigung laufen dürfen.
max_turns	int	nein	Begrenzt die interne ReAct-Schleife des Workers. Bei null gilt der Coordinator-Default.
model	string	nein	LLM-Bezeichner (anthropic/claude-sonnet-4-6, openai/gpt-5.4, zhipu/glm-4.7 usw.). Leer = vom Coordinator-Default erben.
critical_reminder	string	nein	system-reminder-Block, der bei jedem Turn injiziert wird. Anti-Drift-Mechanismus.
initial_prompt	string	nein	Wird der ersten Benutzernachricht beim Spawn vorangestellt. Unterstützt Go-Template-Syntax über den Spawn-Kontext ({{.incident_id}}, {{.device_id}}).
background	bool	nein	true erzwingt asynchrone Ausführung (langlaufende Worker).
omit_claude_md	bool	nein	Überspringt das Erben des globalen System-Kontexts. Verwendet für eng eingegrenzte Reviewer-Agenten.
metadata	object	nein	OS-Gate, erforderliche Binaries / Config-Keys, ongrid-Erweiterungen (scope, edge_runtime, edge_capabilities).

Unbekannte Frontmatter-Keys werden beibehalten (der Parser speichert sie unter UnknownFields), sodass künftige Felder aus openclaw / claude-code den Loader nicht brechen.

Source-Feld

Wenn die SPA einen Agenten zurückliest, enthält die API zusätzlich ein source-Feld, das nicht Teil des On-Disk-Frontmatters ist:

Wert	Bedeutung
builtin	im Binary ausgeliefert (programmatisches Add). Schreibgeschützt in der UI.
disk	geladen aus agents/*.md neben dem Binary oder unter einem externen Verzeichnis. Schreibgeschützt in der UI.
user	vom Benutzer via POST /v1/agents/custom erstellt. In der UI editierbar und löschbar.

Berechtigungsmodi

Das Feld permission_mode steuert, welche Werkzeugklassen die Persona ausführen darf.

Modus	Erlaubte Klassen	Bestätigung erforderlich
read-only	read (Alias safe)	nie
mutating-with-confirm	read + write	einmal pro write-Aufruf
dual-sign-required	read + write + destructive	zweistufige SOP für destructive; einmal für write

Eine Persona kann weiter einschränken über tools (Whitelist) und disallowed_tools (Blacklist). Die Laufzeit wendet sie in dieser Reihenfolge an:

1. Globale Werkzeugmenge nehmen, die die Rolle des Benutzers sehen kann.
2. Mit tools schneiden, falls nicht-leer.
3. Alles in disallowed_tools entfernen.
4. Für jedes verbleibende Werkzeug permission_mode gegen seine class prüfen.

Registrierungsfluss

Built-in personas
  ↳ programmatic Add() in cmd/ongrid/main.go at startup. Cannot be deleted.

On-disk personas
  ↳ ./agents/*.md (relative to manager working dir) scanned at boot.
  ↳ ONGRID_AGENTS_EXTERNAL_DIRS adds more.
  ↳ The loader walks every .md, parses frontmatter via skill_parser.go / agent_parser.go.
  ↳ Each agent is registered with Source="disk".
  ↳ Cannot be edited or deleted via the UI; remove the file and restart.

User personas
  ↳ POST /v1/agents/custom with the frontmatter as a JSON body.
  ↳ Stored in agents table (DB), not on disk.
  ↳ Source="user"; fully editable via PATCH /v1/agents/custom/{name}.

Die Merge-Reihenfolge beim Start ist builtin → disk → user. Eine user-Persona mit demselben name wie eine eingebaute oder Disk-Persona überschattet diese.

Einen Agenten spawnen

Der Coordinator wählt einen Specialist, indem er die Anfrage des Benutzers mit dem when_to_use jeder Persona abgleicht. Zum programmatischen Spawnen (Chat-API):

POST /api/v1/chat/sessions/{id}/messages
Content-Type: application/json
Authorization: Bearer ...

{
  "content": "Investigate incident 4217.",
  "agent": "incident_investigator",
  "context": { "incident_id": 4217, "device_id": 102 }
}

Wenn agent weggelassen wird, wählt der Coordinator. context wird in den initial_prompt der Persona templatisiert.

Critical Reminders

Der critical_reminder-Block wird als system-reminder-Nachricht am Anfang jedes Turns injiziert, nicht nur des ersten. Dies ist der standardmäßige claude-code-Anti-Drift-Mechanismus — wenn das Modell mitten in der Konversation abdriftet (z. B. nach Turn 8 aufhört, Belege zu zitieren), holt der Reminder es zurück.

Verwenden Sie ihn sparsam. Ein kurzer Absatz pro Persona reicht. Der Agent-Kernel injiziert bereits framework-level Reminders (Locale, Modellname, verfügbare Werkzeuge); Ihr critical_reminder sollte nur persona-spezifisches Verhalten hinzufügen.

Beispiele

Minimaler Specialist

---
name: disk_specialist
description: Diagnose disk pressure issues — usage, IO, mount points.
when_to_use: When the user asks about disk-full, slow IO, or mount errors.
tools: [host_probe, bash, query_promql]
permission_mode: read-only
model: zhipu/glm-4.7
---

# Disk specialist

Focus exclusively on disk-related questions. ...

Reviewer (lässt globalen Kontext weg)

---
name: change_reviewer
description: Review a proposed config change for blast radius.
when_to_use: When the user wants a second opinion on a destructive action.
tools: [expand_topology, read_repo, search_knowledge]
permission_mode: read-only
omit_claude_md: true
max_turns: 8
model: anthropic/claude-opus-4-7
critical_reminder: |
  Be a skeptic. Default to "do not proceed" unless evidence is overwhelming.
---

# Change reviewer

You are reviewing a proposed change. Your job is to find reasons the change
should NOT proceed. Approve only when you cannot find a reason to block.

Siehe auch

• Agenten → Überblick — operator-orientierte Tour durch die eingebauten Personas.
• Fähigkeiten → Skills — der Werkzeugkatalog, aus dem eine Persona wählt.
• Skill-Manifest — neue Werkzeuge definieren, die eine Persona aufrufen kann.
• REST API → aiops — Endpunkte zum Verwalten von Personas zur Laufzeit.