Files
lolympus-agent/docs/multi-agent-architecture.md
T

9.2 KiB

lolympus-agent Multi-Agent Architecture

Last verified: Iter8 implementation branch, 2026-05-18.

1. 개요

lolympus-agent는 Lolympus 커뮤니티 운영을 돕는 NATS 메시지 드리븐 멀티 skill agent다. 실시간 요청은 Agent.handleRequest()로 들어오고, skill registry가 요청 skill을 찾아 Skill.handle()을 실행한다. 품질 관리는 shadow evaluation, MongoDB archive, human review, proposal/tournament loop로 이어진다.

운영 목표는 세 가지다.

  • 실시간 응답 경로는 짧고 예측 가능하게 유지한다.
  • skill, prompt, intent, resource, tool 정의는 각 src/skills/<name>/ 폴더에 모은다.
  • production과 eval은 같은 dispatch, handoff, budget 규칙을 사용한다.

2. 아키텍처 다이어그램

실시간 메시지 흐름

NATS lolympus-agent.request
  -> src/main.ts
  -> Agent.handleRequest()
  -> src/agent/dispatch.ts
  -> SkillRegistry.get(request.skill)
  -> Skill.handle(request, history)
  -> AgentResponse

Handoff 흐름

Skill response
  -> control token/parser or metadata.handoffRequest
  -> transition-matrix validation
  -> BudgetTracker
  -> buildHandoffPacket()
  -> dispatch target skill
  -> supervisor fallback when blocked

src/agent/dispatch.ts는 production과 eval에서 모두 쓰인다. handoff chain, depth, last request는 metadata와 logger context에 남는다.

Eval 흐름

real-time response
  -> ShadowEvalBus
  -> lolympus-agent:background
  -> ShadowWorker
  -> lolympus-agent:eval:results
  -> aggregation/archive/drift/review
  -> propose/tournament/promote

Operation 흐름

supervisor handoff
  -> lolympus-agent:review-queue
  -> review:list/show/resolve/stats
  -> resolution stream + compatibility hash
  -> Slack/NATS alert

3. Skill 모델

모든 skill은 src/skills/<name>/ 아래에 둔다. 필수 진입점은 다음과 같다.

파일 역할
SKILL.md 사람이 읽는 capability card와 운영 설명
skill.ts Skill 구현체
intents.ts skill이 해석하는 intent 종류
prompt-data.ts 또는 prompts/* prompt layer, 예시, resource 연결
tools.ts 또는 resources/* skill 전용 tool/resource 정의

src/skills/skill-loader.ts가 SKILL.md를 읽어 SkillManifest로 만들고, src/skills/validate-manifests.ts가 문서와 코드의 일관성을 검사한다. handoffTargets는 src/skills/transition-matrix.ts에서 검증되며 self-loop와 unknown target을 막는다.

현재 핵심 skill은 onboarding, moderation, supervisor다. supervisor는 모든 skill의 fallback target이며, specialist가 처리하지 못한 요청을 review queue로 넘긴다.

4. Dispatch 모델

Dispatch는 src/agent/dispatch.ts가 담당한다.

  • 응답 text 안의 control token은 parser가 제거하고 metadata로 구조화한다.
  • skill이 직접 metadata.handoffRequest를 넣어도 같은 path로 처리된다.
  • HandoffPacket은 원 요청, source response, handoff reason, evidence, source chain을 보존한다.
  • BudgetTracker는 최대 handoff 수, 동일 skill 재방문, tool call, 비용 한도를 강제한다.
  • transition matrix가 허용하지 않는 target은 supervisor로 reroute된다.
  • budget이 막히면 same-agent-revisit, max-hop, high-risk-action 같은 reason으로 supervisor fallback이 만들어진다.

이 구조 덕분에 eval handoff golden도 실제 production dispatch와 같은 규칙을 검증한다.

5. Eval 모델

src/eval/은 네 계층으로 나뉜다.

계층 주요 파일 설명
Golden src/eval/golden/*/cases.jsonl 사람이 관리하는 고정 회귀 케이스
Runner runner.ts, handoff-dispatch.ts skill-aware eval 실행
Judges judges/* rule, LLM, process, handoff 판단
Loop archive.ts, promote.ts, loop/* archive 기반 개선 후보와 tournament

Router 학습은 src/eval/router-training.ts가 MongoDB archive에서 training sample을 만들고, src/skills/onboarding/runtime/router.ts가 learned model을 저장한다. Iter8에서 추가된 src/eval/router-shadow-report.ts는 supervisor outcome과 shadow eval을 조인해 static router와 learned router의 divergence를 보고한다.

6. Observability

관측성은 세 갈래다.

  • Logger context: requestId, skill, handoff chain, depth를 포함한다.
  • Metrics: src/observability/metrics.ts가 Prometheus text exposition을 제공한다.
  • Alerts: src/observability/alert.ts가 NATS와 Slack으로 운영 이벤트를 발행한다.

대표 metric:

Metric 용도
agent_handoff_total skill 간 handoff rate
agent_handoff_loop_total loop guardrail 발생
agent_human_override_total supervisor/manual review 진입
agent_validator_fail_total validator 실패
agent_time_to_resolution_ms skill별 처리 시간
agent_token_cost_usd model/skill 비용 추정

METRICS_PORT의 /metrics와 /healthz를 scrape할 수 있다. Slack alert는 SLACK_ALERT_WEBHOOK_URL이 있을 때만 전송된다.

7. 데이터 저장소

Garnet/Redis

Key Type 용도
lolympus-agent:background Stream shadow eval과 summary job
lolympus-agent:eval:results Stream shadow eval 결과
lolympus-agent:eval:agg:* Hash slice별 aggregate
lolympus-agent:eval:review:queue Stream eval human review
lolympus-agent:review-queue Stream supervisor review
lolympus-agent:review-resolutions Stream supervisor resolution audit
lolympus-agent:review-resolved:* Hash legacy compatibility read path
lolympus-agent:alert:dedupe:* String alert dedupe/rate limit

MongoDB

Collection 용도
eval_archive shadow eval 장기 archive
eval_review_labels 사람 review label archive
eval_tournaments prompt variant tournament 결과

Conversation, blackboard, summary state는 Garnet key와 TTL로 관리한다.

8. 확장 가이드

새 skill을 추가할 때는 다음 순서로 진행한다.

  1. src/skills/<name>/ 폴더를 만들고 SKILL.md, skill.ts, 필요한 intents.ts, prompt-data.ts, tools.ts를 둔다.
  2. SKILL.md에 name, domain, riskTier, canHandle, cannotHandle, handoffTargets, outputContract, triggers를 작성한다.
  3. factory/registry에 skill을 등록하고 transition matrix가 target을 인식하게 한다.
  4. 필요한 resource는 skill 폴더의 resources/에 두고 prompt builder가 읽게 한다.
  5. 최소 golden case를 src/eval/golden/<name>/cases.jsonl에 추가한다.
  6. npm run lint:skills, npm test, 해당 skill eval smoke를 실행한다.
  7. handoff가 필요한 skill이면 src/eval/golden/handoff/cases.jsonl에 교차 skill 케이스를 추가한다.

9. References

문서 의미
refactor-skill-ssot.md Iter1, skill/prompt/intent SSOT 시작
refactor-skill-ssot-iter2.md Iter2, tool/eval path skill-aware화
refactor-skill-ssot-iter3.md Iter3, eval pipeline과 SKILL.md 검증 강화
refactor-skill-ssot-iter4.md Iter4, 멀티 에이전트 운영 조건 정의
refactor-skill-ssot-iter5.md Iter5, bounded graph와 structured handoff
refactor-skill-ssot-iter6.md Iter6, supervisor review loop와 router training signals
refactor-skill-ssot-iter7.md Iter7, observability와 Slack alert
refactor-skill-ssot-iter8.md Iter8, closing iteration

운영 runbook은 service-evaluation-operations.md, 고도화 trigger는 optimization-roadmap.md, resolution hash sunset은 resolution-hash-sunset-procedure.md를 참고한다.