Coordinator

Coordinator 는 사용자가 실제로 대화하는 persona 입니다. 모든 채팅 세션 (웹 UI, Slack, Telegram, Feishu) 은 하나의 coordinator 인스턴스가 소유합니다. worker 가 아닙니다 — 대화를 구동하고, 언제 직접 답할지 결정하고, 언제 AgentTool 을 통해 specialist 로 디스패치 할지 결정하는 장수 ReAct 루프입니다.

정체성

Field	Value
Persona 이름	`default`
Worker 로 스폰 가능	아니오 — 에이전트 카탈로그가 `default` 제외
세션 모델	`(user, chat thread)` 당 하나의 장수 `chat_sessions` 행
도구 가방	넓음: query_*, AgentTool, SendMessage, TaskStop, redirect stubs
Persona body	매니저 이미지에 출하; 조직별 오버라이드는 마운트 파일 경유

Coordinator 의 동작을 전체 함대 차원으로 바꾸려면 내장 위에 커스텀 default.md 를 마운트하세요 (커스텀 에이전트 참고). AgentRegistry.Replace seam 이 사용자 에이전트 편집 UI 를 구동; 오버라이드 파일은 시작 시 같은 코드 경로를 사용.

직접 할 수 있는 것

Coordinator 의 도구 가방은 매니저 범위에서 작동하는 모든 읽기 전용 query 도구를 포함:

query_promql, query_logql, query_traceql — 텔레메트리. 알려진 환각 사례에서 coordinator 에 stub 됨 (incident-investigator 로 redirect) — 아래 참고.
query_knowledge — vault + 업로드 위의 RAG.
query_incidents, get_incident_detail, query_alert_rules, query_devices — 알림 / 인벤토리.
query_change_events — 최근 config / 규칙 / 디바이스 변경.
expand_topology, find_topology_node — 서비스 그래프.
get_active_incidents — 현재 오픈 알림.
BC 핸들러 도구 — 조직/사용자 관리자가 UI 에서 할 모든 것.

의도적으로 호스트 셸이나 호스트별 점검 도구는 갖지 않습니다. 그것들은 specialist 에 있습니다.

컨트롤 도구 트리오

세 특수 도구는 오직 coordinator 에 존재. 멀티 에이전트 오케스트레이션 제어; 무엇도 쿼리하지 않음.

`AgentTool`

Worker 디스패치. 동기. 전체 스키마, dedupe 동작, "사소한 것 위임 금지" 가드레일은 Agents overview 에 문서화. 형태:

json

{
  "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?'"
}

System reminder 가 persona 카탈로그를 주입하여 LLM 이 유효한 subagent_type 값을 알게 합니다. reminder 는 턴별 입니다 — 긴 세션의 attention drift 후에도 LLM 은 어떤 specialist 가 존재하는지 절대 잊지 않습니다.

`SendMessage`

턴을 종료하지 않고 사용자에게 임시 메시지를 보냅니다. coordinator 가 디스패치 정착 전에 "specialist-network 로 디스패치 중 — 잠시 기다려 주세요" 라고 말하고 싶을 때 사용. worker 는 이 도구를 갖지 않습니다 — 사용자와 대화하는 것은 오직 coordinator.

IM 브릿지는 이를 사용해 채팅의 placeholder 메시지를 업데이트 (Slack 의 chat.update, Telegram 의 editMessageText, Feishu 의 PUT /messages). 웹 UI 는 이를 사용해 최종 답변 전에 임시 텍스트를 대화 로그로 스트리밍.

`TaskStop`

실행 중인 worker 를 정중히 취소. 사용자가 디스패치 중간에 주제를 바꿔서 실행 중 worker 의 답이 더 이상 관련 없을 때 같은 경우 coordinator 가 TaskStop 을 발생.

내부적으로 Runtime.StopWorker 호출 — worker 의 context.CancelFunc 를 발화. worker 는 다음 도구 호출 시 ctx.Done() 을 관측하고 Status = killed 설정.

언제 디스패치 vs 직접 답변

Coordinator 의 persona prompt 는 규칙을 인코딩:

AgentTool 不是默认选项。能用本地工具 1-2 步答出来的，自己答。复杂深挖（需要 5+ 步 / 跨主机 / 跨信号面）才派。

한국어로: 작업이 다음일 때만 디스패치:

깊은 반복 필요 (집중 점검 5+ 도구 호출),
호스트 측 도구 필요 (host_bash, host_probe_*, host_du_summary), 또는
coordinator 가 갖지 않는 도메인 특화 도구 가방 의 이점.

"node-01 의 load 는?" 같은 경우 coordinator 는 get_host_load 한 번으로 직접 답변 (사실 — redirect stub 매개 AgentTool(specialist-compute) 로; 원리는 같음). "order 서비스가 왜 502 를 던지고 어떻게 해야 하지?" 같은 경우 coordinator 는 incident-investigator 로 디스패치.

Redirect stubs (반환각)

Coordinator 의 가방은 LLM 이 환각하는 것으로 알려진 도구 이름 (host_bash, host_du_summary, host_restart_service, get_host_load, correlate_incident, …) 용 RedirectStub 엔트리를 운반. LLM 이 stub 된 이름을 고르면 stub 은:

json

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

이 stub 없이는 eino 의 그래프 런타임이 [NodeRunError] tool X not found in toolsNode indexes 로 중단하여 턴을 낭비합니다. 있으면 LLM 은 결과로부터 배우고 다음 반복에서 올바른 AgentTool 호출로 다시 시도합니다. stub 리스트는 CoordinatorRedirectStubs 에 있습니다; 순수 데이터 — 새 환각이 나타날 때마다 누적 추가.

specialist 가방 전체를 가리지 말 것

각 stub 은 LLM-제시 스키마 리스트의 한 슬롯을 소모. 너무 많이 stub 하면 prompt 예산이 비대해지고 LLM 이 stub 을 고려할 유효 옵션으로 다루기 시작할 수 있습니다. eval 에서 환각이 관측된 도구만 stub.

사용자가 보는 것

매 턴 coordinator 는:

토큰을 직접 스트리밍 — 답이 짧고 자체 완결적일 때.
읽기 전용 query 도구를 인라인 호출 — query_incidents, expand_topology, query_knowledge.
AgentTool 로 worker 디스패치 — worker 실행 중 SPA 는 persona 이름 + 1 줄 설명과 함께 "Agent tile" 을 렌더링. 최종 worker 결과는 타일의 자식으로 안착.
SendMessage 로 임시 메시지 전송 — 보통 느린 디스패치 정착 전 ("검토 중; specialist-network 스폰").
TaskStop 으로 worker 중지 — 드물게, 보통 사용자가 디스패치 중간에 방향을 바꿀 때만.

사용자는 worker 의 원본 대화 로그를 절대 보지 않습니다. coordinator 가 worker 의 Result 를 자신의 답변에 합성.

세션과 감사

Coordinator 세션은 agent_id = "default" 와 parent_session_id = NULL 로 chat_sessions 에 산다.
Worker 세션은 coordinator 의 행을 가리키는 parent_session_id 를 받는다. 감사 UI 가 이 트리를 순회하여 parent → child 실행을 렌더링.
모든 도구 호출은 LLM 의 args 뷰와 잘린 결과로 audit_logs 행을 받음 (self-observability 참고).

Coordinator 커스터마이징

Coordinator persona 파일을 오버라이드 할 수 있습니다. 일반적으로 바꾸고 싶은 것:

디스패치 가이드 (팀이 다른 "언제 위임" 정책을 가짐).
출력 언어 / 톤 (채널의 default_locale 사용 또는 persona body 로 고정).
coordinator 가 디스패치 전에 사용하길 원하는 읽기 전용 인라인 도구 리스트.

바꾸지 않아야 할 것:

에이전트 카탈로그 블록 — 기계 생성. 편집해도 효과 없음; 다음 리로드가 재생성.
redirect-stub 의미 — persona 가 아니라 코드.
default name — 런타임이 이름으로 coordinator 를 조회.

핫 리로드 이야기는 커스텀 에이전트 참고.

Coordinator ​

정체성 ​

직접 할 수 있는 것 ​

컨트롤 도구 트리오 ​

AgentTool ​

SendMessage ​

TaskStop ​

언제 디스패치 vs 직접 답변 ​

Redirect stubs (반환각) ​

사용자가 보는 것 ​

세션과 감사 ​

Coordinator 커스터마이징 ​