# 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//` 폴더에 모은다. - production과 eval은 같은 dispatch, handoff, budget 규칙을 사용한다. ## 2. 아키텍처 다이어그램 ### 실시간 메시지 흐름 ```text NATS lolympus-agent.request -> src/main.ts -> Agent.handleRequest() -> src/agent/dispatch.ts -> SkillRegistry.get(request.skill) -> Skill.handle(request, history) -> AgentResponse ``` ### Handoff 흐름 ```text 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 흐름 ```text real-time response -> ShadowEvalBus -> lolympus-agent:background -> ShadowWorker -> lolympus-agent:eval:results -> aggregation/archive/drift/review -> propose/tournament/promote ``` ### Operation 흐름 ```text supervisor handoff -> lolympus-agent:review-queue -> review:list/show/resolve/stats -> resolution stream + compatibility hash -> Slack/NATS alert ``` ## 3. Skill 모델 모든 skill은 `src/skills//` 아래에 둔다. 필수 진입점은 다음과 같다. | 파일 | 역할 | | --------------------------------- | --------------------------------------- | | `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//` 폴더를 만들고 `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//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](refactor-skill-ssot.md) | Iter1, skill/prompt/intent SSOT 시작 | | [refactor-skill-ssot-iter2.md](refactor-skill-ssot-iter2.md) | Iter2, tool/eval path skill-aware화 | | [refactor-skill-ssot-iter3.md](refactor-skill-ssot-iter3.md) | Iter3, eval pipeline과 SKILL.md 검증 강화 | | [refactor-skill-ssot-iter4.md](refactor-skill-ssot-iter4.md) | Iter4, 멀티 에이전트 운영 조건 정의 | | [refactor-skill-ssot-iter5.md](refactor-skill-ssot-iter5.md) | Iter5, bounded graph와 structured handoff | | [refactor-skill-ssot-iter6.md](refactor-skill-ssot-iter6.md) | Iter6, supervisor review loop와 router training signals | | [refactor-skill-ssot-iter7.md](refactor-skill-ssot-iter7.md) | Iter7, observability와 Slack alert | | [refactor-skill-ssot-iter8.md](refactor-skill-ssot-iter8.md) | Iter8, closing iteration | 운영 runbook은 [service-evaluation-operations.md](service-evaluation-operations.md), 고도화 trigger는 [optimization-roadmap.md](optimization-roadmap.md), resolution hash sunset은 [resolution-hash-sunset-procedure.md](resolution-hash-sunset-procedure.md)를 참고한다.