14 KiB
lolympus-agent Service and Evaluation Operations
이 문서는 lolympus-agent의 운영 흐름과 evaluation 파이프라인을 한 곳에서 보기 위한 runbook이다. 실시간 응답 경로, background worker, shadow evaluation, human review, calibration, closed-loop prompt experiment까지 포함한다.
1. 프로세스 구성
운영 프로세스는 크게 두 개다.
| 프로세스 | 엔트리포인트 | 역할 |
|---|---|---|
| agent | src/main.ts |
NATS request/reply를 받아 실시간 온보딩 응답 생성 |
| worker | src/workers/background.ts |
Redis Stream background job 처리, shadow eval, archive, drift, review routing |
PM2 기준으로는 ecosystem.config.cjs에서 agent와 worker를 함께 띄운다.
npm run pm2:dev
npm run pm2:test
npm run pm2:prod
개발 환경 단독 실행은 기존 스크립트를 사용한다.
npm run start:dev
2. Bootstrap 흐름
src/main.ts의 기동 순서는 다음과 같다.
loadEnvironmentFromNodeEnv()로env-vars/{NODE_ENV}.env로드- logger/tracing 초기화
- NATS 연결
- Garnet/Redis 연결
- LLM endpoint와 provider key 구성
- MongoDB 연결, 가능하면 room context 활성화
Agent생성OnboardingSkill등록lolympus-agent.request구독 시작
중요한 점은 NATS가 가장 먼저 외부 TLS 연결을 시도한다는 것이다. 따라서 bootstrap fatal error가 certificate has expired이고 ✓ NATS connected 로그가 없었다면 1순위 원인은 NATS_ENDPOINT 인증서 만료다.
3. 실시간 응답 흐름
본체는 NATS request/reply로 agent에 요청한다.
lolympus-agent.request
-> Agent.handleRequest
-> OnboardingSkill.handle
-> AgentResponse
OnboardingSkill.handle() 내부 흐름:
- Garnet에서 온보딩 세션 로드
- user message와 trigger 기반 intent classify
- session, trigger, intent로
DerivedState생성 shouldRespond=false면 empty response 반환responseMode=template이면 template fallback 응답- LLM 경로면 prompt build 후 orchestrator 실행
- tier에 따라 planner/responder/critic/tool-loop 사용
- validator로 응답 검증
- 최종 응답 반환
- blackboard 업데이트
- shadow eval event를 background stream에 비동기 발행
실시간 사용자 응답은 9번에서 끝난다. Evaluation은 11번 이후 worker가 비동기로 처리한다.
4. Prompt와 Tool 경로
Prompt는 src/skills/onboarding/prompts/builder.ts가 만든다.
기본 layer:
- persona
- policy
- state
- examples
- context
PROMPT_VARIANT_ID가 설정되면 src/eval/proposals/{variantId}.json manifest를 읽어 prompt layer diff를 적용한다. 운영 반영은 env로 variant를 선택하는 방식이며, proposal 생성과 tournament는 별도 CLI에서 수행한다.
Tool loop는 responseMode=llm-with-tools일 때 작동한다. Built-in tool은 src/tools/builtins/*에 있다.
5. Background Worker 흐름
Worker는 lolympus-agent:background Redis Stream을 consumer group bg-worker로 읽는다.
| Job type | 처리 |
|---|---|
shadow-eval |
실시간 응답을 rule/LLM/process 기준으로 평가 |
summarize |
오래된 대화 일부를 요약해 summary slot에 저장 |
Worker는 pending job을 복구하고, delivery count가 한도를 넘으면 DLQ로 이동한다.
| Stream | 용도 |
|---|---|
lolympus-agent:background |
background job queue |
lolympus-agent:background:dlq |
반복 실패 job 저장 |
6. Shadow Evaluation 흐름
실시간 응답이 만들어지면 ShadowEvalBus가 background stream에 shadow-eval job을 발행한다.
Worker는 이 job을 받아 다음을 수행한다.
- validator 재실행
- LLM judge 실행
- process trace가 있으면 process judge 실행
- latency, tier, intent, phase, judge 결과 저장
결과는 Redis Stream에 저장된다.
lolympus-agent:eval:results
이 Stream이 이후 evaluation 운영의 원천 데이터다.
7. 주기 Evaluation 작업
Worker는 일정 간격으로 eval result를 가공한다.
| 작업 | 기본 주기 | 결과 |
|---|---|---|
| aggregation | EVAL_AGG_TICK_MS 5분 |
slice별 Redis Hash metric |
| archive | EVAL_ARCHIVE_TICK_MS 1시간 |
MongoDB eval_archive |
| drift detection | EVAL_DRIFT_TICK_MS 24시간 |
eval-drift alert |
| promotion | EVAL_PROMOTE_TICK_MS 24시간 |
golden candidate jsonl |
| review routing | EVAL_REVIEW_TICK_MS 5분 |
human review queue |
| review label archive | archive tick과 함께 | MongoDB eval_review_labels |
Slice 정의:
tier × intent × phase
예:
0:photo-question:photo-pending
1:discord-question:step1-completed
8. Redis Key Schema
주요 Redis/Garnet key:
| Key | Type | 용도 |
|---|---|---|
lolympus-agent:background |
Stream | worker job queue |
lolympus-agent:background:dlq |
Stream | worker dead-letter queue |
lolympus-agent:eval:results |
Stream | shadow eval 결과 |
lolympus-agent:eval:baseline |
String | 최근 안정 baseline report |
lolympus-agent:eval:agg:{tier}:{intent}:{phase} |
Hash | slice별 count/score/latency/process metric |
lolympus-agent:eval:agg:cursor |
String | aggregation cursor |
lolympus-agent:eval:archive:cursor |
String | eval archive cursor |
lolympus-agent:eval:review:queue |
Stream | human review 대기 큐 |
lolympus-agent:eval:review:labeled |
Stream | human review label |
lolympus-agent:eval:review:cursor |
String | review routing cursor |
lolympus-agent:eval:review:dedupe:{evalStreamId} |
String | 동일 eval result 중복 라우팅 방지 |
lolympus-agent:eval:review:label-archive:cursor |
String | review label archive cursor |
lolympus-agent:alert:dedupe:{kind} |
String | alert rate limit |
9. MongoDB Collections
| Collection | 생성/사용 모듈 | 용도 |
|---|---|---|
eval_archive |
src/eval/archive.ts |
shadow eval 결과 장기 보관 |
eval_review_labels |
src/eval/review/label-archive.ts |
사람 라벨 장기 보관 |
eval_tournaments |
src/eval/loop/tournament.ts |
prompt variant tournament 결과 |
eval_archive는 evaluatedAt 기준 TTL index를 가진다. 기본 보관 기간은 EVAL_ARCHIVE_TTL_DAYS=30이다.
10. Human Review 흐름
Review routing은 eval result 중 사람이 봐야 할 케이스를 큐에 넣는다.
조건:
- LLM judge overall이 낮음
- validator와 LLM judge가 불일치
- validator soft-warn
- rare slice
큐:
lolympus-agent:eval:review:queue
라벨링:
npm run eval:review -- --limit=20
특정 reason만 보기:
npm run eval:review -- --reason=low-score --limit=10
stale pending item을 다시 큐에 넣기:
npm run eval:review -- --reset-pending
세션 라벨을 JSONL로 저장:
npm run eval:review -- --limit=20 --export-labeled=eval-reports/review-labels.jsonl
라벨 결과는 lolympus-agent:eval:review:labeled Stream에 쌓이고 archive tick에서 eval_review_labels로 영속화된다.
11. Calibration 흐름
Calibration은 사람 점수와 LLM judge 점수의 상관을 계산한다.
npm run eval:calibrate
CI나 수동 gate로 쓰려면:
npm run eval:calibrate -- --check
pairs < 10이면 표본이 부족하므로 경고만 출력하고 실패 처리하지 않는다. 충분한 라벨이 쌓이면 EVAL_CALIBRATION_MIN_CORR 기준으로 LLM judge 신뢰도를 감시한다.
12. Report와 Promotion
Slice별 약한 영역 확인:
npm run eval:report -- --worst=20
최근 7일 대신 다른 window:
npm run eval:report -- --worst=20 --since=24h
npm run eval:report -- --top=20 --since=30d
Golden candidate 확인:
npm run eval:promote -- --dry-run
Candidate 파일에 추가:
npm run eval:promote
기본 출력:
src/eval/golden/onboarding.candidate.jsonl
Promotion 우선순위:
- human-labeled fail
- low-score
- rule/LLM disagree
- rare-slice
candidate는 바로 golden으로 승격되는 것이 아니라 사람이 직접 검토해 onboarding.jsonl로 옮긴다.
13. Closed Loop 흐름
Phase 9의 closed loop는 prompt/tool 개선안을 만들고 tournament로 비교하는 흐름이다.
13.1 Proposal 생성
약한 slice를 지정한다.
npm run eval:propose -- --slice=tier=1,intent=photo-question,phase=photo-pending
archive case 수가 부족해도 강제로 실행하려면:
npm run eval:propose -- --slice=tier=1,intent=photo-question,phase=photo-pending --force
결과는 git-tracked proposal manifest로 저장된다.
src/eval/proposals/{variantId}.json
13.2 Tournament 실행
Control과 variant를 비교한다.
npm run eval:tournament -- --variants=control,<variantId>
특정 archive case만 지정:
npm run eval:tournament -- --variants=control,<variantId> --case-ids=1-0,2-0
결과 조회:
npm run eval:tournament-results
npm run eval:tournament-results -- --variant=<variantId>
Tournament는 A/B 위치 편향을 줄이기 위해 variant 순서를 바꾼 match도 실행하고 ELO를 갱신한다. 결과는 MongoDB eval_tournaments에 저장된다.
13.3 운영 반영
운영 prompt에 variant를 반영하려면 env를 설정한다.
PROMPT_VARIANT_ID=<variantId>
반영 전에는 반드시 다음을 확인한다.
npm run typecheck
npm run lint
npm run build
npm test
npm run eval -- --skip-llm-judge --no-publish-report
Variant 적용은 자동 머지가 아니다. 사람이 tournament 결과와 sample match를 보고 결정한다.
14. Eval CLI 요약
| 명령 | 용도 |
|---|---|
npm run eval |
golden set 실행 |
npm run eval:capture |
MongoDB events에서 golden scaffold 추출 |
npm run eval:baseline |
안정 baseline 저장 |
npm run eval:report |
archive slice report 출력 |
npm run eval:promote |
golden candidate 추출 |
npm run eval:review |
human review CLI |
npm run eval:calibrate |
사람/LLM judge calibration |
npm run eval:propose |
prompt/tool improvement proposal 생성 |
npm run eval:tournament |
prompt variant A/B tournament 실행 |
npm run eval:tournament-results |
tournament 결과 조회 |
15. 주요 Env
| Env | 기본값 | 용도 |
|---|---|---|
EVAL_STREAM_MAXLEN |
10000 | eval results Stream maxlen |
EVAL_AGG_TICK_MS |
300000 | aggregation tick |
EVAL_AGG_TTL_SEC |
604800 | slice metric TTL |
EVAL_ARCHIVE_TICK_MS |
3600000 | archive tick |
EVAL_ARCHIVE_TTL_DAYS |
30 | archive TTL days |
EVAL_DRIFT_TICK_MS |
86400000 | drift tick |
EVAL_PROMOTE_TICK_MS |
86400000 | promotion tick |
EVAL_REVIEW_TICK_MS |
300000 | review routing tick |
EVAL_REVIEW_QUEUE_MAXLEN |
500 | review queue maxlen |
EVAL_REVIEW_LABEL_MAXLEN |
5000 | review label Stream maxlen |
EVAL_REVIEW_DEDUPE_TTL_SEC |
604800 | review dedupe TTL |
EVAL_CALIBRATION_MIN_CORR |
0.5 | calibration gate |
REVIEWER_ID |
git user.email | human review 식별자 |
LLM_PROPOSE_MODEL |
LLM_JUDGE_MODEL |
proposal model |
LLM_PROPOSE_MAX_TOKENS |
1024 | proposal max tokens |
EVAL_TOURNAMENT_MAX_MATCHES |
50 | tournament match cap |
EVAL_TOURNAMENT_MIN_CASES |
10 | proposal 최소 archive cases |
PROMPT_VARIANT_ID |
unset | 운영 prompt variant 선택 |
16. Alert와 Monitoring
Worker는 다음 종류의 alert를 보낼 수 있다.
| Alert kind | 의미 |
|---|---|
latency |
최근 shadow eval latency p95 초과 |
llm-error-rate |
LLM judge 실패율 상승 |
eval-score-drop |
baseline 대비 eval score 하락 |
eval-drift |
24h vs 7d slice score drift |
endpoint-down |
LLM circuit breaker open |
archive-stalled |
MongoDB archive 연속 실패 |
Alert는 lolympus-agent.alert NATS subject로 발행되고, dedupe key로 rate limit된다.
17. 장애 확인 Runbook
17.1 Bootstrap에서 certificate has expired
증상:
[Bootstrap] Fatal startup error
message: certificate has expired
code: CERT_HAS_EXPIRED
src/main.ts 기준 NATS 연결이 첫 외부 TLS 연결이다. ✓ NATS connected 로그가 없으면 NATS_ENDPOINT 인증서가 1순위 원인이다.
확인:
node --trace-warnings --import tsx src/main.ts
인증서 날짜 확인:
openssl s_client -connect <host>:<port> -servername <host> </dev/null 2>/dev/null \
| openssl x509 -noout -dates -subject
✓ NATS connected 이후 같은 오류가 나면 다음 후보는 Garnet 또는 MongoDB다.
17.2 LLM endpoint warning
증상:
[LLM] Endpoint unavailable via circuit breaker
[LLM] Request error
[LLM] All endpoints failed
확인 순서:
CLI_PROXY_API_URLSOPENROUTER_API_KEY,OPENROUTER_API_URLAGENT_LLM_API_URLSLLAMA_SERVER_API_URL- provider별 API key
npm run eval -- --skip-llm-judge는 LLM judge를 생략하지만 실제 응답 생성 LLM은 여전히 호출될 수 있다. endpoint가 모두 실패하면 template/fallback 경로로 통과할 수 있다.
17.3 MongoDB 미설정
Worker가 다음과 비슷한 로그를 남긴다.
MongoDB connection string missing; eval archive/drift/promote disabled
영향:
- 실시간 응답은 가능
- shadow eval result Stream은 쌓임
- archive, drift, promote, calibration, tournament는 제한됨
필요 env:
MONGODB_CONNECTION_STRING=
MONGODB_PROJECT_ID=
17.4 Review queue가 밀림
확인:
npm run eval:review -- --limit=5
stale pending item 정리:
npm run eval:review -- --reset-pending
같은 케이스가 반복 라우팅되면 dedupe TTL과 cursor를 확인한다.
lolympus-agent:eval:review:cursor
lolympus-agent:eval:review:dedupe:{evalStreamId}
17.5 Archive stalled
archive-stalled alert가 뜨면 MongoDB 연결과 index 생성 권한을 확인한다.
관련 cursor:
lolympus-agent:eval:archive:cursor
lolympus-agent:eval:review:label-archive:cursor
cursor가 진행되지 않으면 worker가 다음 tick에서 재시도한다.
18. 운영 원칙
- 실시간 응답 경로는 가능한 짧게 유지한다.
- Evaluation은 Redis Stream을 통해 비동기로 처리한다.
- Golden set 승격은 사람이 직접 결정한다.
- Prompt variant 운영 반영은 tournament 결과와 eval smoke를 본 뒤 결정한다.
- 자동 rollback이나 자동 merge는 하지 않는다.
- 모든 timestamp는 UTC ISO-8601을 사용한다.