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을 추가할 때는 다음 순서로 진행한다.
src/skills/<name>/폴더를 만들고SKILL.md,skill.ts, 필요한intents.ts,prompt-data.ts,tools.ts를 둔다.SKILL.md에name,domain,riskTier,canHandle,cannotHandle,handoffTargets,outputContract,triggers를 작성한다.- factory/registry에 skill을 등록하고 transition matrix가 target을 인식하게 한다.
- 필요한 resource는 skill 폴더의
resources/에 두고 prompt builder가 읽게 한다. - 최소 golden case를
src/eval/golden/<name>/cases.jsonl에 추가한다. npm run lint:skills,npm test, 해당 skill eval smoke를 실행한다.- 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를 참고한다.