Close multi-agent plan and add router shadow reporting
This commit is contained in:
1 parent
f1b30d716d
commit
8156e8c07e
15 files changed
+1303
-204
No files matched your search
@@ -0,0 +1,178 @@
|
||||
# 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)를 참고한다.
|
||||
Reference in new issue
Block a user