Формат персоны агента

Персона агента — это markdown-файл, описывающий, как ведёт себя один агент — coordinator, incident investigator, specialist: какие инструменты он может вызывать, на какой модели он работает, сколько ReAct-ходов он получает и какой системный промпт он несёт.

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

On-disk форма

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

Frontmatter — это YAML. Тело (после ---) — это системный промпт, который видит worker LLM. Whitespace и markdown-форматирование в теле сохраняются дословно.

Поля Frontmatter

Поле	Тип	Обязательно	Описание
name	string	да	Идентификатор агента, используемый во время spawn (/v1/agents/{name}).
description	string	да	Строка human-listing, показанная в agent-picker.
when_to_use	string	да	Подсказка решения spawn для coordinator. Coordinator читает это, решая, какого specialist'а вызвать.
tools	string[]	нет	Явный whitelist инструментов. Пусто = наследовать из политики (каждый инструмент, который роль пользователя может видеть).
disallowed_tools	string[]	нет	Blacklist, применяемый после whitelist. Чёрный побеждает над белым.
permission_mode	enum	нет (по умолчанию read-only)	read-only, mutating-with-confirm, dual-sign-required. Гейтит, какие tool-классы могут запускаться без подтверждения.
max_turns	int	нет	Cap'ит внутренний ReAct-цикл воркера. Coordinator default применяется, если 0.
model	string	нет	LLM-идентификатор (anthropic/claude-sonnet-4-6, openai/gpt-5.4, zhipu/glm-4.7 и т.д.). Пусто = наследовать coordinator default.
critical_reminder	string	нет	system-reminder блок, инъецируемый на каждом ходе. Anti-drift механизм.
initial_prompt	string	нет	Дописывается перед первым user-сообщением при spawn. Поддерживает синтаксис Go template поверх spawn-контекста ({{.incident_id}}, {{.device_id}}).
background	bool	нет	true форсит async-выполнение (long-running workers).
omit_claude_md	bool	нет	Пропустить наследование global system context. Используется для tightly-scoped reviewer-агентов.
metadata	object	нет	OS gate, required бинари / config-ключи, ongrid-расширения (scope, edge_runtime, edge_capabilities).

Неизвестные frontmatter-ключи сохраняются (парсер хранит их под UnknownFields), так что будущие поля из openclaw / claude-code не ломают loader.

Поле Source

Когда SPA читает обратно агента, API также включает поле source, которое не является частью on-disk frontmatter:

Значение	Значение
builtin	отгружен в бинаре (программный Add). Read-only в UI.
disk	загружен из agents/*.md рядом с бинарём или под external-директорией. Read-only в UI.
user	создан пользователем через POST /v1/agents/custom. Редактируемо и удаляемо из UI.

Режимы permission

Поле permission_mode гейтит, какие tool-классы персона может запускать.

Режим	Allowed-классы	Confirmation required
read-only	read (alias safe)	никогда
mutating-with-confirm	read + write	один раз на write вызов
dual-sign-required	read + write + destructive	two-step SOP для destructive; один раз для write

Персона может дополнительно constrain'ить через tools (whitelist) и disallowed_tools (blacklist). Рантайм применяет их в этом порядке:

1. Взять глобальный tool-set, который роль пользователя может видеть.
2. Пересечь с tools, если непустой.
3. Удалить всё в disallowed_tools.
4. Для каждого оставшегося инструмента проверить permission_mode против его class.

Flow регистрации

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

Merge-порядок при старте — builtin → disk → user. user персона с тем же name, что и встроенная или disk-персона, заслоняет её.

Spawning агента

Coordinator выбирает specialist'а, сопоставляя query пользователя против when_to_use каждой персоны. Чтобы породить программно (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 }
}

Если agent опущен, coordinator выбирает. context шаблонизируется в initial_prompt персоны.

Critical reminders

Блок critical_reminder инъецируется как system-reminder сообщение на верху каждого хода, не только первого. Это стандартный claude-code anti-drift механизм — когда модель блуждает mid-conversation (например, перестаёт цитировать доказательства после хода 8), reminder тянет её обратно.

Используйте экономно. Один короткий параграф на персону — это много. Agent kernel уже инъектит framework-level reminders (locale, model name, available tools); ваш critical_reminder должен добавить только persona-specific поведение.

Примеры

Минимальный 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 (опускает 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.

См. также

• Agents → Обзор — operator-facing тур по встроенным персонам.
• Capabilities → Skills — каталог инструментов, из которого персона выбирает.
• Skill manifest — определение новых инструментов, которые персона может вызывать.
• REST API → aiops — эндпоинты для управления персонами в рантайме.