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

179 lines
9.2 KiB
Markdown

# 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. 아키텍처 다이어그램
### 실시간 메시지 흐름
```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/<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](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)를 참고한다.