Formato de persona de agente
Una persona de agente es un archivo markdown que describe cómo se comporta un agente — un coordinator, un incident investigator, un specialist —: qué herramientas puede invocar, sobre qué modelo corre, cuántos turnos ReAct se le permiten y qué system prompt lleva.
Fuente de verdad: Agent en internal/manager/biz/aiops/chatruntime/types.go.
Forma en disco
---
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.El frontmatter es YAML. El cuerpo (tras ---) es el system prompt que ve el LLM worker. Los espacios en blanco y el formato markdown del cuerpo se preservan textualmente.
Campos del frontmatter
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
name | string | sí | Identificador del agente usado en el momento de spawn (/v1/agents/{name}). |
description | string | sí | Cadena humana mostrada en el selector de agentes. |
when_to_use | string | sí | Pista de decisión de spawn para el coordinator. El coordinator lee esto al decidir a qué specialist invocar. |
tools | string[] | no | Whitelist explícita de herramientas. Vacía = se hereda de la policy (cada herramienta que el rol del usuario puede ver). |
disallowed_tools | string[] | no | Blacklist aplicada después de la whitelist. La blacklist gana sobre la whitelist. |
permission_mode | enum | no (por defecto read-only) | read-only, mutating-with-confirm, dual-sign-required. Filtra qué clases de herramientas pueden ejecutarse sin confirmación. |
max_turns | int | no | Limita el bucle ReAct interno del worker. Si es cero se aplica el default del coordinator. |
model | string | no | Identificador del LLM (anthropic/claude-sonnet-4-6, openai/gpt-5.4, zhipu/glm-4.7, etc.). Vacío = se hereda del default del coordinator. |
critical_reminder | string | no | Bloque system-reminder inyectado en cada turno. Mecanismo anti-drift. |
initial_prompt | string | no | Se antepone al primer mensaje del usuario en el spawn. Soporta sintaxis de templates de Go sobre el contexto del spawn ({{.incident_id}}, {{.device_id}}). |
background | bool | no | true fuerza ejecución asíncrona (workers de larga duración). |
omit_claude_md | bool | no | Omite la herencia del contexto global del sistema. Se usa para agentes reviewer con alcance estricto. |
metadata | object | no | Gate de SO, binarios / claves de config requeridos, extensiones de ongrid (scope, edge_runtime, edge_capabilities). |
Las claves desconocidas del frontmatter se preservan (el parser las guarda bajo UnknownFields) de modo que campos futuros de openclaw / claude-code no rompan el loader.
Campo Source
Cuando la SPA lee de vuelta un agente, la API también incluye un campo source que no forma parte del frontmatter en disco:
| Valor | Significado |
|---|---|
builtin | embebido en el binario (Add programático). Solo lectura en la UI. |
disk | cargado desde agents/*.md junto al binario o bajo un directorio externo. Solo lectura en la UI. |
user | creado por el usuario vía POST /v1/agents/custom. Editable y eliminable desde la UI. |
Modos de permiso
El campo permission_mode filtra qué clases de herramientas puede ejecutar la persona.
| Modo | Clases permitidas | Confirmación requerida |
|---|---|---|
read-only | read (alias safe) | nunca |
mutating-with-confirm | read + write | una vez por llamada write |
dual-sign-required | read + write + destructive | SOP de dos pasos para destructive; una vez para write |
Una persona puede restringir aún más vía tools (whitelist) y disallowed_tools (blacklist). El runtime los aplica en este orden:
- Toma el conjunto global de herramientas que el rol del usuario puede ver.
- Interseca con
toolssi no está vacía. - Elimina lo que esté en
disallowed_tools. - Para cada herramienta restante, verifica
permission_modecontra suclass.
Flujo de registro
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}.El orden de merge en el arranque es builtin → disk → user. Una persona user con el mismo name que una persona builtin o de disco la oculta.
Spawning de un agente
El coordinator elige un specialist haciendo match de la consulta del usuario contra el when_to_use de cada persona. Para hacer spawn programáticamente (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 }
}Si se omite agent, el coordinator elige. context se templatea dentro del initial_prompt de la persona.
Critical reminders
El bloque critical_reminder se inyecta como mensaje system-reminder al inicio de cada turno, no solo del primero. Este es el mecanismo anti-drift estándar de claude-code — cuando el modelo se desvía a mitad de la conversación (p. ej. deja de citar evidencia tras el turno 8), el recordatorio lo trae de vuelta.
Úsalo con moderación. Un párrafo corto por persona es suficiente. El kernel del agente ya inyecta recordatorios a nivel framework (locale, nombre del modelo, herramientas disponibles); tu critical_reminder solo debería añadir comportamiento específico de la persona.
Ejemplos
Specialist mínimo
---
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 (omite el contexto global)
---
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.Véase también
- Agentes → Resumen — recorrido para operadores por las personas integradas.
- Capacidades → Skills — el catálogo de herramientas del que elige una persona.
- Manifiesto de skill — definir nuevas herramientas que una persona pueda invocar.
- REST API → aiops — endpoints para gestionar personas en runtime.