에이전트 persona 포맷

에이전트 persona 는 하나의 에이전트 — coordinator, incident investigator, specialist — 가 어떻게 행동하는지를 기술하는 markdown 파일입니다: 어떤 도구를 호출할 수 있는지, 어떤 모델 위에서 도는지, ReAct 턴이 몇 번 주어지는지, 그리고 어떤 시스템 프롬프트를 들고 다니는지.

소스 오브 트루스: internal/manager/biz/aiops/chatruntime/types.go 의 Agent.

디스크 모양

markdown

---
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 입니다. body (--- 이후) 는 worker LLM 이 보는 시스템 프롬프트 입니다. body 의 공백과 markdown 포맷은 그대로 보존됩니다.

frontmatter 필드

필드	타입	필수	설명
`name`	string	예	스폰 시점에 쓰이는 에이전트 식별자 (`/v1/agents/{name}`).
`description`	string	예	에이전트 선택기에 표시되는 사람용 문자열.
`when_to_use`	string	예	coordinator 의 스폰 결정 힌트. coordinator 가 어떤 specialist 를 호출할지 결정할 때 이를 읽습니다.
`tools`	string[]	아니오	명시적 도구 화이트리스트. 비어 있으면 정책에서 상속 (사용자 role 이 볼 수 있는 모든 도구).
`disallowed_tools`	string[]	아니오	화이트리스트 이후에 적용되는 블랙리스트. 블랙이 화이트를 이깁니다.
`permission_mode`	enum	아니오 (기본 `read-only`)	`read-only`, `mutating-with-confirm`, `dual-sign-required`. 어떤 도구 클래스가 확인 없이 실행될 수 있는지를 게이팅합니다.
`max_turns`	int	아니오	worker 의 내부 ReAct 루프를 제한. 0 이면 coordinator 기본값 적용.
`model`	string	아니오	LLM 식별자 (`anthropic/claude-sonnet-4-6`, `openai/gpt-5.4`, `zhipu/glm-4.7` 등). 비어 있으면 coordinator 기본값 상속.
`critical_reminder`	string	아니오	매 턴마다 주입되는 system-reminder 블록. 드리프트 방지 메커니즘.
`initial_prompt`	string	아니오	스폰 시 첫 사용자 메시지에 prepend. 스폰 컨텍스트에 대해 Go 템플릿 문법 지원 (`{{.incident_id}}`, `{{.device_id}}`).
`background`	bool	아니오	`true` 면 비동기 실행 강제 (장기 실행 worker).
`omit_claude_md`	bool	아니오	글로벌 시스템 컨텍스트 상속을 건너뜀. 좁게 한정된 reviewer 에이전트에 사용.
`metadata`	object	아니오	OS 게이트, 필요 바이너리 / config 키, ongrid 확장 (scope, edge_runtime, edge_capabilities).

알려지지 않은 frontmatter 키는 보존됩니다 (파서가 UnknownFields 에 저장) — openclaw / claude-code 의 미래 필드가 로더를 깨뜨리지 않게 합니다.

Source 필드

SPA 가 에이전트를 읽어 올 때, API 는 디스크 frontmatter 의 일부가 아닌 source 필드도 함께 포함합니다:

값	의미
`builtin`	바이너리에 실린 (프로그램적 Add). UI 에서 읽기 전용.
`disk`	바이너리 옆 `agents/*.md` 또는 외부 디렉터리에서 로드. UI 에서 읽기 전용.
`user`	사용자가 `POST /v1/agents/custom` 을 통해 생성. UI 에서 편집 / 삭제 가능.

권한 모드

permission_mode 필드는 persona 가 실행할 수 있는 도구 클래스 를 게이팅합니다.

모드	허용 클래스	확인 필요
`read-only`	`read` (별칭 `safe`)	절대 안 함
`mutating-with-confirm`	`read` + `write`	`write` 호출당 한 번
`dual-sign-required`	`read` + `write` + `destructive`	`destructive` 는 2단계 SOP; `write` 는 한 번

persona 는 tools (화이트리스트) 와 disallowed_tools (블랙리스트) 로 더 제약할 수 있습니다. 런타임은 다음 순서로 적용합니다:

사용자 role 이 볼 수 있는 글로벌 도구 집합을 가져온다.
tools 가 비어 있지 않으면 교집합.
disallowed_tools 의 모든 항목을 제거.
남은 각 도구에 대해 permission_mode 를 그 class 와 대조해 확인.

등록 흐름

text

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

기동 시 머지 순서는 builtin → disk → user 입니다. 빌트인 또는 디스크 persona 와 같은 name 을 가진 user persona 는 그것을 그림자처럼 가립니다.

에이전트 스폰

coordinator 는 사용자의 질의를 각 persona 의 when_to_use 와 매칭해 specialist 를 고릅니다. 프로그램적으로 스폰하려면 (chat API):

http

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 는 persona 의 initial_prompt 에 템플릿됩니다.

Critical reminders

critical_reminder 블록은 첫 턴만이 아니라 매 턴의 상단 에 system-reminder 메시지로 주입됩니다. 이는 표준 claude-code 의 드리프트 방지 메커니즘입니다 — 모델이 대화 중간에 흩어질 때 (예: 8턴 이후 증거 인용을 멈출 때) 이 reminder 가 끌어다 잡습니다.

아껴 쓰십시오. persona 당 짧은 단락 하나면 충분합니다. 에이전트 커널은 이미 프레임워크 수준 reminder (locale, 모델 이름, 사용 가능한 도구) 를 주입합니다. 당신의 critical_reminder 는 persona 고유의 행동만 추가해야 합니다.

예시

최소 specialist

markdown

---
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 (글로벌 컨텍스트 생략)

markdown

---
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 → Overview — 빌트인 persona 들의 운영자 시점 투어.
Capabilities → Skills — persona 가 선택하는 도구 카탈로그.
Skill manifest — persona 가 호출할 수 있는 새 도구의 정의.
REST API → aiops — 런타임에서 persona 를 관리하는 엔드포인트.

에이전트 persona 포맷 ​

디스크 모양 ​

frontmatter 필드 ​

Source 필드 ​

권한 모드 ​

등록 흐름 ​

에이전트 스폰 ​

Critical reminders ​

예시 ​

최소 specialist ​

Reviewer (글로벌 컨텍스트 생략) ​

함께 보기 ​

에이전트 persona 포맷

디스크 모양

frontmatter 필드

Source 필드

권한 모드

등록 흐름

에이전트 스폰

Critical reminders

예시

최소 specialist

Reviewer (글로벌 컨텍스트 생략)

함께 보기