Обзор агентов

Ongrid — это мультиагентная ReAct-система. Пользователь всегда разговаривает с coordinator — персоной верхнего уровня на чат-поверхности. Когда задача укладывается в специализированный домен (глубокое исследование корневой причины, ревью мутирующего действия, глубокий разбор сети), coordinator диспетчирует на под-агента («воркера») через AgentTool. Каждый воркер запускает то же графовое ядро поверх фильтрованного набора инструментов и возвращает финальный ответ, который coordinator вплетает в свой ответ.

Эта страница — карта. Страницы по конкретным персонам объясняют каждого агента подробно.

Персоны, а не чат-треды

Персона — это файл на диске, описывающий, что делает агент. Каноническая раскладка — та же форма, что у формата агентов Claude Code с ключами snake_case:

yaml

---
name: specialist-disk
description: 文件系统 / 磁盘容量专家 — du / find / stat / inode / 挂载 / 大文件
when_to_use: |
  When the task is about disk / filesystem health:
    - Disk full / utilization climbing
    - Hunt for large files / large directories
    - inode exhaustion / mount point inspection
tools:
  - query_knowledge
  - host_find_large_files
  - host_du_summary
  - host_stat_file
  - host_bash
  - query_promql
  - get_host_load
permission_mode: read-only
max_turns: 15
---
[markdown body — this becomes the system prompt]

Тело под frontmatter — это SystemPrompt. Два файла персон с одним name конфликтуют, и загрузчик логирует предупреждение. См. справочник формата персоны, где описано каждое поле.

Персоны живут под ./agents/ в образе manager (/app/agents/ внутри контейнера). Ongrid поставляет встроенные персоны в образе и также читает пользовательские персоны из смонтированной директории — см. Кастомные агенты.

Coordinator vs воркер

Аспект	Coordinator	Воркер
Кто говорит с пользователем	Да (через чат-поверхность или IM)	Никогда — вывод воркера идёт coordinator
Набор инструментов	Широкий: query_*, AgentTool, redirect-заглушки	Узкий: whitelist `tools:` персоны
Имя персоны	`default` (или per-org переопределение)	`specialist-*`, `incident-investigator`, `reviewer`
Кем порождён	Рантаймом (один на чат-сессию)	`AgentTool` или декоратор `review_gate`
Может порождать	Да (воркеров)	Нет (воркеры не могут вкладываться by design)
Сессия	Долгоживущая, персистится	Новая сессия на порождение, в пределах одного хода

Работа coordinator — диспетчеризация + триаж + синтез. Инструменты глубокого погружения живут на воркерах. Coordinator несёт RedirectStub слоты для инструментов, которые LLM известно галлюцинирует (host_bash, get_host_load, …); вызов одного из них возвращает redirect-сообщение, которое подталкивает модель перевызвать через AgentTool.

`AgentTool`

Примитив диспетчеризации coordinator. Имя соединения AgentTool (PascalCase для выравнивания с каталогом инструментов Claude Code). Схема, видимая LLM:

json

{
  "type": "object",
  "properties": {
    "description":   {"type": "string"},
    "subagent_type": {"type": "string"},
    "prompt":        {"type": "string"}
  },
  "required": ["description", "subagent_type", "prompt"]
}

description — однострочное резюме задачи, которое использует плитка SPA.
subagent_type — name персоны. Каталог, инъецируемый в системный промпт coordinator, перечисляет допустимые значения (реестр персон минус reviewer и default).
prompt — полное описание задачи. Воркер не видит контекст coordinator — упакуйте каждую необходимую деталь (incident_id, device_id, точную формулировку).

Вызов синхронный с точки зрения coordinator. Он блокирует до достижения воркером completed / failed / killed. Более ранняя ревизия имела асинхронный флаг background: true; слабые модели его брали, отвечали пользователю с pending task_id и никогда не возвращались. Флаг сегодня удалён (см. agent_tool.go для post-mortem комментария). Единственный асинхронный путь — это reviewer — и его управляет декоратор, а не LLM.

Дедупликация встроена

LRU на 120с, ключ sha256(subagent_type + canonical(prompt)), короткозамыкает второй из двух идентичных вызовов AgentTool. LLM видит прежний результат с явной подсказкой «вы это уже диспетчировали». Срезает раздувания цикла coordinator (E2E eval D1 видел 122 вызова инструментов за 240с без дедупликации).

Как составляется системный промпт

ComposeSystemPrompt собирает промпт, который получает LLM, в таком порядке:

basePrompt — универсальная преамбула рантайма. Может быть пустой.
agentProfile.SystemPrompt — markdown-тело персоны. Coordinator может его нести (большинство несут); воркеры — всегда.
agentProfile.CriticalReminder — обёрнут в <critical-reminder>...</critical-reminder>. Это уровневая константа персоны; графовый слой также переинъецирует её на каждом ходе как <system-reminder>, чтобы пережить смещение внимания в длинных сессиях.
Для каждого активного скилла: заголовок [能力: <name>] + PromptBody скилла.

Coordinator получает дополнительный блок перед списком скиллов: каталог агентов (buildAgentCatalog) — markdown bullet-list «доступных специалистов» с description и первой строкой when_to_use. Каталог сознательно исключает reviewer (только декоратор ReviewGate может его порождать) и default (виртуальная персона верхнего уровня — перечисление её как порождаемого под-агента позволило бы coordinator рекурсивно порождать самого себя).

Реестр агентов

AgentRegistry держит распарсенные персоны в памяти. Загружается один раз при старте; Reload() делает атомарный своп под одним sync.RWMutex, так что in-flight ход coordinator никогда не наблюдает полузагруженный реестр.

Метод	Когда
`Load(root)`	Старт. Рекурсивно обходит `<root>/*/.md`.
`Reload(root, ...)`	Установка/деинсталляция marketplace. Атомарный своп.
`ByName(name)`	Поиск во время порождения. Возвращает `(nil, false)` при промахе.
`Replace(ag)`	Редактирование user-agent. Upsert на месте — живой реестр, без рестарта.
`Remove(name)`	Удаление user-agent.

Ошибки парсинга на файл приземляются как предупреждения, а не прерывают обход (та же политика, что у реестра скиллов). Несуществующие корни агентов — не ошибка; вы получаете пустой реестр, а не падение при старте.

Reviewer и review gate

Reviewer особенный: coordinator не может его породить. Он гейтится декоратором ReviewGate, который перехватывает любой инструмент с Class равным "write" или "destructive". Декоратор:

Строит payload предложения (action, target, reason, blast_radius, operator).
Порождает воркера reviewer (синхронно с точки зрения внутреннего инструмента) с собственным таймаутом 60с, независимо от 15с внутреннего инструмента.
Если reviewer возвращает Decision: approve, вызов проваливается во внутренний инструмент. Иначе декоратор возвращает ErrReviewRejected, обёрнутый причиной reviewer.

Поэтому каталог агентов опускает reviewer: только декоратор получает право его вызывать. Поместив его в каталог, вы позволили бы coordinator диспетчировать ad-hoc «ревью», которые ничего не гейтят.

См. Reviewer для полной state-машины.

Жизненный цикл воркера

Runtime.SpawnWorker state-машина:

text

pending  → running  → completed
                   ↘ failed
                   ↘ killed     (StopWorker called while running)

Строка chat_sessions создаётся заранее, чтобы аудит + запросы дерева parent → worker разрешались, даже пока воркер ещё работает.
Фоновые порождения берут начало от долгоживущего контекста рантайма, так что завершающийся HTTP-запрос не может снести воркера посреди работы; синхронные порождения наследуют ctx вызывающего.
Строка сессии закрывается (closed_at ставится) на каждом терминальном пути, включая паники — без этого осиротевшие строки накапливаются (тестовая среда добралась до 161 до фикса).

Воркеры не могут порождать воркеров. SpawnWorker выставлен только на Runtime, а disabledForWorker фильтр срезает AgentTool из набора инструментов любого воркера. Один coordinator, N параллельных воркеров, никакого более глубокого вложения.

Что дальше

Coordinator — стандартная персона, её три управляющих инструмента, и когда диспетчировать vs отвечать напрямую.
Incident investigator — корневая причина до «нулевого пациента», бюджет 18 инструментов, и eval F1.
Специалисты — compute / disk / network / ops / sre, что каждый из них владеет, как coordinator выбирает.
Reviewer — гейт двойной подписи SOP на мутирующих инструментах.
Кастомные агенты — авторируйте свою персону, горячая перезагрузка, отладка.

Обзор агентов ​

Персоны, а не чат-треды ​

Coordinator vs воркер ​

AgentTool ​

Как составляется системный промпт ​

Реестр агентов ​

Reviewer и review gate ​

Жизненный цикл воркера ​

Что дальше ​