Formato de persona de agent

Uma persona de agent é um arquivo markdown que descreve como um agent — um coordinator, um incident investigator, um specialist — se comporta: quais tools pode chamar, em qual modelo roda, quantos turns ReAct ganha, e qual system prompt carrega.

Fonte de verdade: Agent em internal/manager/biz/aiops/chatruntime/types.go.

Formato em 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.

O frontmatter é YAML. O corpo (após ---) é o system prompt que o worker LLM vê. Whitespace e formatação markdown no corpo são preservados verbatim.

Campos do frontmatter

Campo	Tipo	Obrigatório	Descrição
name	string	sim	Identificador do agent usado no momento do spawn (/v1/agents/{name}).
description	string	sim	String de listagem humana mostrada no picker de agent.
when_to_use	string	sim	Dica de decisão de spawn do coordinator. O coordinator lê isso ao decidir qual specialist invocar.
tools	string[]	não	Whitelist explícita de tool. Vazio = herda da política (toda tool que a role do usuário pode ver).
disallowed_tools	string[]	não	Blacklist aplicada depois da whitelist. Black vence sobre white.
permission_mode	enum	não (padrão read-only)	read-only, mutating-with-confirm, dual-sign-required. Gateia quais classes de tool podem rodar sem confirmação.
max_turns	int	não	Cap do loop ReAct interno do worker. Padrão do coordinator se aplica se zero.
model	string	não	Identificador LLM (anthropic/claude-sonnet-4-6, openai/gpt-5.4, zhipu/glm-4.7, etc.). Vazio = herda default do coordinator.
critical_reminder	string	não	Bloco system-reminder injetado em cada turn. Mecanismo anti-drift.
initial_prompt	string	não	Prepended à primeira mensagem de usuário no spawn. Suporta sintaxe template Go sobre o contexto de spawn ({{.incident_id}}, {{.device_id}}).
background	bool	não	true força execução async (workers de longa duração).
omit_claude_md	bool	não	Pula herdar o contexto de sistema global. Usado para agents reviewer com escopo apertado.
metadata	object	não	Gate de OS, binários / chaves de config requeridos, extensões ongrid (scope, edge_runtime, edge_capabilities).

Chaves de frontmatter desconhecidas são preservadas (o parser as armazena sob UnknownFields) para que campos futuros do openclaw / claude-code não quebrem o loader.

Campo source

Quando o SPA lê de volta um agent, a API também inclui um campo source que não é parte do frontmatter on-disk:

Valor	Significado
builtin	distribuído no binário (Add programático). Read-only na UI.
disk	carregado de agents/*.md ao lado do binário ou sob um dir externo. Read-only na UI.
user	criado pelo usuário via POST /v1/agents/custom. Editável e deletável da UI.

Permission modes

O campo permission_mode gateia quais classes de tool a persona pode rodar.

Modo	Classes permitidas	Confirmação requerida
read-only	read (alias safe)	nunca
mutating-with-confirm	read + write	uma vez por chamada write
dual-sign-required	read + write + destructive	SOP de dois passos para destructive; uma vez para write

Uma persona pode restringir mais via tools (whitelist) e disallowed_tools (blacklist). O runtime os aplica nesta ordem:

1. Pega o conjunto global de tools que a role do usuário pode ver.
2. Intersecta com tools se não-vazio.
3. Remove qualquer coisa em disallowed_tools.
4. Para cada tool restante, cheque permission_mode contra sua class.

Fluxo de registro

Personas built-in
  ↳ Add() programático em cmd/ongrid/main.go no startup. Não pode ser deletada.

Personas on-disk
  ↳ ./agents/*.md (relativo ao working dir do manager) scaneadas no boot.
  ↳ ONGRID_AGENTS_EXTERNAL_DIRS adiciona mais.
  ↳ O loader percorre cada .md, parseia frontmatter via skill_parser.go / agent_parser.go.
  ↳ Cada agent é registrado com Source="disk".
  ↳ Não pode ser editada ou deletada via UI; remova o arquivo e reinicie.

User personas
  ↳ POST /v1/agents/custom com o frontmatter como JSON body.
  ↳ Armazenado na tabela agents (DB), não em disco.
  ↳ Source="user"; totalmente editável via PATCH /v1/agents/custom/{name}.

A ordem de merge no startup é builtin → disk → user. Uma persona user com o mesmo name que uma persona built-in ou disk sombreia-a.

Spawning um agent

O coordinator escolhe um specialist casando a query do usuário contra o when_to_use de cada persona. Para fazer spawn programaticamente (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 }
}

Se agent é omitido, o coordinator escolhe. context é templated no initial_prompt da persona.

Critical reminders

O bloco critical_reminder é injetado como uma mensagem system-reminder no topo de cada turn, não só no primeiro. Esse é o mecanismo anti-drift padrão do claude-code — quando o modelo vagueia mid-conversation (ex.: para de citar evidência depois do turn 8), o reminder o puxa de volta.

Use com parcimônia. Um parágrafo curto por persona é o suficiente. O agent kernel já injeta reminders a nível de framework (locale, nome do modelo, tools disponíveis); seu critical_reminder deve adicionar apenas comportamento específico da persona.

Exemplos

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 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.

Veja também

• Agents → Visão geral — tour voltado ao operador das personas built-in.
• Capacidades → Skills — o catálogo de tool de onde uma persona escolhe.
• Manifesto de skill — definindo novas tools que uma persona pode chamar.
• REST API → aiops — endpoints para gerenciar personas em runtime.