Coordinator

Coordinator — это персона, с которой пользователь фактически разговаривает. Каждая чат-сессия (веб-интерфейс, Slack, Telegram, Feishu) принадлежит одному экземпляру coordinator. Это не воркер — это долгоживущий цикл ReAct, который ведёт разговор, решает, когда отвечать напрямую, и решает, когда диспетчировать задачу specialist через AgentTool.

Идентичность

Поле	Значение
Имя персоны	default
Может ли быть воркером	Нет — каталог агентов исключает default
Модель сессии	Одна долгоживущая строка chat_sessions на (user, chat thread)
Набор инструментов	Широкий: query_*, AgentTool, SendMessage, TaskStop, redirect-заглушки
Тело персоны	Поставляется в образе manager; переопределение на org через монтированный файл

Если вы хотите изменить поведение coordinator на уровне всего флота, смонтируйте свой default.md поверх встроенного (см. Кастомные агенты). Шов AgentRegistry.Replace питает UI редактирования user-agent; файл-переопределение использует тот же путь кода при старте.

Что он может делать напрямую

Набор инструментов coordinator включает все read-only query-инструменты, работающие в области manager:

• query_promql, query_logql, query_traceql — телеметрия. На coordinator заглушены (перенаправляют на incident-investigator) для известных случаев галлюцинаций — см. ниже.
• query_knowledge — RAG поверх vault + загруженных файлов.
• query_incidents, get_incident_detail, query_alert_rules, query_devices — алерты / инвентарь.
• query_change_events — недавние мутации конфигов / правил / устройств.
• expand_topology, find_topology_node — граф сервисов.
• get_active_incidents — текущие открытые алерты.
• BC-handler инструменты — всё, что org/user-админ сделал бы из UI.

Он сознательно не несёт host-shell или per-host инструменты инспекции. Они живут на specialist.

Тройка управляющих инструментов

Три специальных инструмента живут только на coordinator. Они управляют мультиагентной оркестрацией; они ничего не запрашивают.

AgentTool

Диспетчирует воркера. Синхронно. Полная схема, поведение дедупликации и правило «не делегировать тривиальное» задокументированы в Обзоре агентов. Форма:

{
  "description": "Find which process is OOM-ing on node-01",
  "subagent_type": "specialist-compute",
  "prompt": "On device_id=7 we saw mem_used_pct=98 at 14:02. Find the top RSS processes and check dmesg for oom-killer hits. The user originally asked: 'who's eating memory on node-01?'"
}

Системное напоминание инъецирует каталог персон, чтобы LLM знал допустимые значения subagent_type. Напоминание поворотное — даже после смещения внимания в длинных сессиях LLM никогда не забывает, какие specialist существуют.

SendMessage

Отправляет промежуточное сообщение пользователю без завершения хода. Используется, когда coordinator хочет сказать «диспетчирую specialist-network — дайте минуту» до того, как диспетчеризация устаканится. Воркеры этот инструмент не несут — только coordinator разговаривает с пользователем.

IM-мост использует это, чтобы обновить placeholder-сообщение в чате (chat.update в Slack, editMessageText в Telegram, PUT /messages в Feishu). Веб-интерфейс использует это, чтобы стримить промежуточный текст в транскрипт перед финальным ответом.

TaskStop

Вежливо отменяет работающего воркера. Coordinator вызывает TaskStop, когда, например, пользователь меняет тему посреди диспетчеризации и ответ работающего воркера больше не релевантен.

Внутри это вызывает Runtime.StopWorker, который дёргает context.CancelFunc воркера. Воркер замечает ctx.Done() на следующем вызове инструмента и ставит Status = killed.

Когда диспетчировать, а когда отвечать напрямую

Промпт персоны coordinator кодирует правило:

AgentTool — не вариант по умолчанию. Если можно ответить за 1-2 шага локальными инструментами, отвечай сам. Сложные глубокие разборы (нужно 5+ шагов / межхостовые / межсигнальные) — отправляй.

Иначе: диспетчируйте только когда задача

• требует глубокой итерации (5+ вызовов инструментов сфокусированной инспекции),
• требует host-side инструментов (host_bash, host_probe_*, host_du_summary), или
• выигрывает от доменно-специфичного набора инструментов, который coordinator не несёт.

Для «какая нагрузка на node-01?» coordinator отвечает напрямую одним get_host_load (ну — через перенаправляющий заглушку AgentTool(specialist-compute); принцип тот же). Для «почему order-сервис кидает 502 и что мне с этим делать?» coordinator диспетчирует на incident-investigator.

Redirect-заглушки (анти-галлюцинация)

Набор coordinator несёт записи RedirectStub для имён инструментов, которые LLM известно галлюцинирует (host_bash, host_du_summary, host_restart_service, get_host_load, correlate_incident, …). Когда LLM выбирает заглушенное имя, заглушка возвращает:

{
  "status": "redirect",
  "hint": "This tool is not available in coordinator scope. Re-invoke via AgentTool to dispatch to specialist-disk.",
  "reason": "目录占用分析",
  "suggested_call": "AgentTool(description=\"…\", subagent_type=\"specialist-disk\", prompt=\"<self-contained task>\", background=true)",
  "why_stub_exists": "Coordinator's job is dispatch + triage. Deep-dive tools live on specialist workers; calling them inline is the wrong pattern."
}

Без этих заглушек графовый рантайм eino прерывался бы с [NodeRunError] tool X not found in toolsNode indexes и тратил ход. С ними LLM учится на результате и пробует снова с правильным вызовом AgentTool на следующей итерации. Список заглушек живёт в CoordinatorRedirectStubs; это чистые данные — добавляйте со временем, по мере появления новых галлюцинаций.

Не заслоняйте весь набор specialist

Каждая заглушка занимает слот в списке схем, презентуемом LLM. Заглушите слишком много инструментов — и бюджет промпта раздуется; LLM может начать относиться к заглушкам как к допустимым вариантам. Заглушка достаётся только тем инструментам, которые наблюдались в галлюцинациях на eval.

Что видит пользователь

На каждом ходе coordinator может:

1. Стримить токены напрямую — ответ короткий и самодостаточный.
2. Вызывать read-only query-инструменты инлайн — query_incidents, expand_topology, query_knowledge.
3. Диспетчировать воркера через AgentTool — SPA рендерит «Agent tile» с именем персоны + 1-строчным описанием, пока воркер работает. Финальный результат воркера приземляется как дочерний к плитке.
4. Отправить промежуточное сообщение через SendMessage — обычно перед медленной диспетчеризацией («Разбираюсь; поднимаю specialist-network»).
5. Остановить воркера через TaskStop — редко, обычно только когда пользователь перенаправляет посреди диспетчеризации.

Пользователь никогда не видит сырой транскрипт воркера. Coordinator синтезирует Result воркера в свой ответ.

Сессия и аудит

• Сессия coordinator живёт в chat_sessions с agent_id = "default" и parent_session_id = NULL.
• Сессии воркеров получают parent_session_id, указывающий на строку coordinator. UI аудита обходит это дерево, чтобы отрендерить родитель → дочерние прогоны.
• Каждый вызов инструмента получает строку audit_logs с тем, как LLM видит аргументы, и усечённым результатом (см. self-observability).

Кастомизация coordinator

Вы можете переопределить файл персоны coordinator. Что обычно хочется изменить:

• Руководство по диспетчеризации (у вашей команды другая политика «когда делегировать»).
• Язык/тон вывода (используйте default_locale на канале; или закрепите через тело персоны).
• Список read-only инлайн-инструментов, которые coordinator должен использовать перед диспетчеризацией.

Что не следует менять:

• Блок каталога агентов — он машинно-сгенерирован. Редактирование не имеет эффекта; следующая перезагрузка регенерирует его.
• Семантику redirect-заглушек — это код, а не персона.
• name default — рантайм ищет coordinator по имени.

См. Кастомные агенты для истории горячей перезагрузки.