MAO Prompt & Observability 모듈 설계

1. 범위

• 대상: Multi-Agent Orchestration 도메인의 Supervisor 및 7개 Specialized Agent 프롬프트, 라우팅 실험, KPI 모니터링
• Admin 라우트: apps/dha-sleep-web/app/(admin)/prompt-console/*
• 목표: 프롬프트 라이프사이클(작성→리뷰→배포), Observability(CTA/KPI, Guardrail), LLM 모델 선택/폴백 구성, 실험/롤백을 하나의 UI로 제공해 빠른 반복 개선을 가능하게 함

2. 사용자 플로우

1. 탐색 & 상태 확인
   • Prompt Architect가 Prompt Library에서 Agent/버전/상태를 필터링
   • Routing/CTA KPI를 대시보드에서 확인하고 문제 버전을 식별
2. 프롬프트 수정
   • 템플릿 복제 또는 신규 작성 → Slot Checklist(컨텍스트 패키징, Data Readiness, TimeMachine 메타) 충족 여부 검증
   • Draft 저장 후 리뷰 요청: Reviewer가 Diff Viewer로 변경 사항 확인, 코멘트 남김
3. LLM 모델 선택/검증
   • Agent/Template Detail에서 Model Profile Drawer를 열어 Provider(Vertex/OpenAI/Anthropic) + Model + Max Tokens + Fallback 순서를 지정
   • Model Profile 변경 시 Guardrail 시뮬레이션(토큰 사용량/보안 정책) 실행 후 승인 요청
4. 배포 & 실험
   • 승인 시 Canary 롤아웃 생성(세션 비율, KPI 가드 기준 입력)
   • Canary 성공 시 Prod 승격. 실패 시 롤백 버튼으로 이전 버전 복귀
5. Observability & Guardrail
   • KPI 패널에서 Intent Routing 정확도, CTA Conversion, Latency, 토큰 사용량 등 실시간 확인
   • Guardrail 이벤트(정책 위반, Content filter fail)를 Drill-down하여 Prompt 버전과 샘플 페이로드 확인 → 재수정 루프

3. 화면 설계

화면	목적	주요 컴포넌트
Prompt Dashboard	KPI와 경보 요약, 최근 배포	PromptKpiChart, AlertFeed, RecentDeployments
Prompt Library	프롬프트 목록/검색	PromptListTable, VersionBadge, FilterPanel
Template Detail	편집/리뷰/Diff	MonacoPromptEditor, SlotChecklist, DiffViewer, CommentThread
Deployment Center	배포 파이프라인 관리	RolloutTimeline, CanaryConfigForm, RollbackButton
Experiments	A/B & Bucket 관리	ExperimentTable, BucketConfig, GuardrailThresholdForm
Observability	라우팅/CTA/Latency	RoutingChart, CtaConversionFunnel, LatencyHeatmap, TokenUsageTrend
Model Profiles	Provider/Model/Quota 설정	ModelProfileDrawer, ProviderBadge, FallbackChainEditor, QuotaUsagePanel

4. 데이터 & API 계약

리소스	필드	설명
PromptTemplate	id, agentType, version, content, slotMeta, status, modelProfileId, updatedBy, updatedAt	slotMeta에는 Data Readiness, Context Packaging, CTA tone 등이 포함
PromptReview	id, templateId, reviewer, status, comments	리뷰 플로우 관리
Deployment	id, templateId, environment, rolloutPlan, metricsGate, state	rolloutPlan: 비율/기간, metricsGate: KPI 임계값
Experiment	id, name, targetAgents, bucketConfig, status, owner	bucketConfig는 트래픽 분배/종료 조건
PromptKpiSnapshot	timestamp, agentType, routingAccuracy, ctaConversion, latencyP95, tokenUsage	Observability 그래프용
GuardrailEvent	id, promptVersion, policyId, severity, samplePayload, timestamp	Prompt/CTA 공통 정책 위반 정보
ModelProfile	id, name, provider, modelName, maxOutputTokens, temperature, fallback	Provider/모델·파라미터 조합 정의, fallback은 [{ provider, modelName }] 배열
ModelQuota	provider, dailyTokenLimit, tokenCost, currentUsage	Admin이 토큰 비용/한도 상태를 모니터링
ModelBinding	agentType, environment, modelProfileId, effectiveFrom	Agent별 Model Profile 적용 내역

API 패턴:

• GET /api/admin/prompt-console/templates : 필터링/페이지네이션
• POST /api/admin/prompt-console/templates : Draft 생성
• POST /api/admin/prompt-console/templates/{id}/reviews : 리뷰 요청
• POST /api/admin/prompt-console/deployments : Canary 생성
• POST /api/admin/prompt-console/deployments/{id}/promote : Prod 승격
• POST /api/admin/prompt-console/deployments/{id}/rollback : 롤백
• GET /api/admin/prompt-console/metrics : KPI/Guardrail 집계 (SSE 지원)

5. 검증 & 테스트 전략

1. Prompt Lint Spec: slotMeta가 필수 필드를 모두 채웠는지, TimeMachine context를 참조하는지 자동 검사
2. Integration Test: Next.js Route Handler를 통해 Prompt Service mock과 상호작용하는 테스트 작성
3. Canary Simulation: Experiment/Deployment config를 JSON fixture로 저장 후 Cypress로 UI-API 플로우 검증
4. Telemetry Replay: Observability mock 데이터를 사용해 차트 렌더링/경보 로직 검증

6. 보안 & 권한

• 권한 스코프: prompt.read, prompt.write, prompt.deploy, prompt.observability
• 민감 데이터(사용자 대화 샘플)는 마스킹된 형태로만 표출. 세부 payload 확인은 Guardrail 이벤트 모달에서 별도 권한 필요
• 모든 배포/롤백 이벤트는 Audit Trail과 Slack 알림으로 전파

7. 오픈 이슈

1. Prompt Service가 Git 기반일 경우, Commit Hash와 템플릿 버전을 어떻게 동기화할지 결정 필요
2. Observability SSE 채널의 샘플링 주기(실시간 vs 배치) 확정
3. Guardrail 이벤트에 포함되는 샘플 페이로드의 PII 마스킹 정책 정의
4. Prompt Review 코멘트와 Backlog task 간 링크 방식 표준화

---

이 문서는 MAO 모듈의 0.1 설계 문서이며, 와이어프레임 및 API 세부 스펙은 추후 docs/application/dha-sleep-web/admin-console/mao/* 하위 파일로 확장한다.