エージェントペルソナフォーマット

エージェントペルソナ は 1 つのエージェント —— coordinator、incident investigator、specialist —— がどう振る舞うかを記述する markdown ファイルです：どのツールを呼べるか、どのモデルで動くか、何 ReAct ターンを得るか、どのシステムプロンプトを持つか。

真実の出所：internal/manager/biz/aiops/chatruntime/types.go の Agent。

ディスク上の形

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

フロントマターは YAML です。本文（--- の後）は worker LLM が見る システムプロンプト です。本文内の空白と markdown フォーマットは逐語に保持されます。

フロントマターフィールド

フィールド	型	必須	説明
name	string	はい	spawn 時に使うエージェント識別子（/v1/agents/{name}）。
description	string	はい	エージェントピッカーに表示されるヒューマンリスト文字列。
when_to_use	string	はい	coordinator の spawn 判断ヒント。どの specialist を呼ぶか決めるときに coordinator がこれを読む。
tools	string[]	いいえ	明示的なツールホワイトリスト。空 = ポリシーから継承（ユーザーロールが見られるすべてのツール）。
disallowed_tools	string[]	いいえ	ホワイトリスト後に適用するブラックリスト。ブラックがホワイトに勝つ。
permission_mode	enum	いいえ（デフォルト read-only）	read-only、mutating-with-confirm、dual-sign-required。確認なしでどのツールクラスが動くかゲート。
max_turns	int	いいえ	worker 内部 ReAct ループのキャップ。ゼロなら 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	いいえ	spawn 時の最初のユーザーメッセージの先頭に付与。spawn コンテキストに対する Go テンプレート構文（{{.incident_id}}、{{.device_id}}）をサポート。
background	bool	いいえ	true で非同期実行を強制（長時間 worker）。
omit_claude_md	bool	いいえ	グローバルシステムコンテキストの継承をスキップ。タイトスコープ reviewer エージェントに使用。
metadata	object	いいえ	OS ゲート、必須バイナリ / 設定キー、ongrid 拡張（scope、edge_runtime、edge_capabilities）。

未知のフロントマターキーは保持されます（パーサーは UnknownFields 下に保存）ので、openclaw / claude-code からの将来のフィールドがローダーを壊しません。

Source フィールド

SPA がエージェントを読み戻すとき、API はディスク上のフロントマターの一部 ではない source フィールドも含めます：

値	意味
builtin	バイナリに出荷（プログラム的 Add）。UI で読み取り専用。
disk	バイナリの隣の agents/*.md または外部 dir からロード。UI で読み取り専用。
user	POST /v1/agents/custom でユーザーが作成。UI から編集・削除可能。

パーミッションモード

permission_mode フィールドはペルソナが走らせられる ツールクラス をゲートします。

モード	許可クラス	確認必須
read-only	read（エイリアス safe）	決してなし
mutating-with-confirm	read + write	write 呼び出しごとに 1 回
dual-sign-required	read + write + destructive	destructive は 2 ステップ SOP、write は 1 回

ペルソナはさらに tools（ホワイトリスト）と disallowed_tools（ブラックリスト）でこの順序で制約できます：

1. ユーザーロールが見られるグローバルツールセットを取る。
2. tools が空でなければ交差。
3. disallowed_tools のものを削除。
4. 残りの各ツールについて、その class に対して permission_mode をチェック。

登録フロー

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。組み込みまたはディスクペルソナと同じ name の user ペルソナはそれをシャドウします。

エージェントの spawn

coordinator はユーザーのクエリを各ペルソナの when_to_use と照合して specialist を選びます。プログラム的に spawn するには（チャット 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_reminder ブロックは最初だけでなく 毎ターンの先頭 に system-reminder メッセージとして注入されます。これは標準の claude-code アンチドリフトメカニズムです —— モデルが会話途中でさまよう（例えばターン 8 以降で証拠引用を停止する）と、リマインダーが引き戻します。

控えめに使ってください。ペルソナごとに 1 つの短い段落で十分です。エージェントカーネルはすでにフレームワークレベルのリマインダー（ロケール、モデル名、利用可能なツール）を注入します。あなたの critical_reminder はペルソナ固有の挙動だけを加えるべきです。

例

最小 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（グローバルコンテキストを省略）

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

関連

• エージェント → 概要 —— 組み込みペルソナの operator 向けツアー。
• 機能 → スキル —— ペルソナが選ぶツールカタログ。
• スキルマニフェスト —— ペルソナが呼べる新ツールの定義。
• REST API → aiops —— ランタイムでペルソナを管理するエンドポイント。