dha-sleep-app-web → agentz-studio 통합 아키텍처 변경 계획

Status: Approved Date: 2025-12-19 Author: bok@weltcorp.com Tags: agentz-studio, mcp-server, streamable-http, architecture-change

1. 개요 (Executive Summary)

1.1 변경 목적

dha-sleep-app-web의 채팅 기능이 agentz-studio 플랫폼에서 제공하는 Agent API를 사용하도록 전환
dha-sleep-api가 MCP Server 역할을 수행하여 medication, sleep, questionnaire 도메인 데이터 제공
대화에서 구조화된 데이터 추출 및 저장 기능 유지

1.2 현재 vs 목표 아키텍처

현재:

dha-sleep-app-web → dha-sleep-api(/chat/messages) → MAO Domain → LLM

목표:

dha-sleep-app-web → agentz-studio API → Agent Team → MCP → dha-sleep-api
                                                           ↓
                                    ← Conversation Webhook ← (대화 맥락 구독)

1.3 참조 문서

2. Phase 1: dha-sleep-api MCP Server 구현 (2주)

2.1 신규 모듈 생성

경로: apps/dha-sleep-api/src/app/mcp/

mcp/
├── mcp.module.ts                    # NestJS 모듈
├── mcp.controller.ts                # Streamable HTTP 단일 엔드포인트 (POST/GET/DELETE)
├── mcp-server.service.ts            # JSON-RPC 요청 라우팅 + 세션 관리
├── mcp-session.service.ts           # Mcp-Session-Id 관리 (생성, 검증, 만료)
├── mcp-tools.service.ts             # 도구 등록/실행 (tools/list, tools/call)
├── mcp-resources.service.ts         # 리소스 제공 (resources/list, resources/read)
├── interfaces/
│   ├── mcp-message.interface.ts     # JSON-RPC 메시지 타입
│   └── mcp-tool.interface.ts        # Tool 정의 인터페이스
├── guards/
│   └── mcp-auth.guard.ts            # agentz-studio API Key 인증
└── tools/
    ├── medication-tools.ts          # 약물 도메인 (4개 tools)
    ├── sleep-tools.ts               # 수면 도메인 (5개 tools)
    └── questionnaire-tools.ts       # 설문 도메인 (4개 tools)

2.2 MCP 엔드포인트 (Streamable HTTP - 2025-03-26 스펙)

중요: MCP 2025-03-26 스펙에서 SSE는 deprecated. Streamable HTTP가 새로운 표준.

Endpoint	Method	Description
`/v1/mcp`	POST	JSON-RPC 요청 처리 (단일 엔드포인트)
`/v1/mcp`	GET	SSE 스트림 열기 (서버→클라이언트 메시지 수신)
`/v1/mcp`	DELETE	세션 종료
`/v1/mcp/health`	GET	헬스 체크 (비MCP)

Streamable HTTP 핵심 특징:

단일 엔드포인트에서 POST/GET/DELETE 모두 처리
Mcp-Session-Id 헤더로 세션 관리
POST 응답: application/json 또는 text/event-stream
Accept: application/json, text/event-stream 헤더 필수

세션 라이프사이클:

POST /v1/mcp (initialize) → Response + Mcp-Session-Id 헤더
POST /v1/mcp (tools/list, tools/call) + Mcp-Session-Id
GET /v1/mcp + Mcp-Session-Id → SSE 스트림 (서버 푸시용)
DELETE /v1/mcp + Mcp-Session-Id → 세션 종료

2.3 도메인별 Tool 정의

Medication (4개)

get_medication_profile - 사용자 약물 프로필 조회
get_medication_guidance - 약물 권고 조회
get_medication_interaction_score - 상호작용 점수
register_medication - 약물 등록 (대화에서 추출 시)

Sleep (5개)

get_sleep_log_range - 수면 로그 범위 조회
get_latest_sleep_goal - 최신 수면 목표
get_sleep_goal_adherence - 목표 달성도
get_rtib_recommendation - rTIB 추천
create_sleep_log - 수면 로그 생성

Questionnaire (4개)

get_questionnaire_results - 설문 결과 (ISI, PHQ-9 등)
get_active_questionnaire_bundle - 활성 설문
get_user_questionnaire_progress - 진행도
submit_questionnaire_response - 응답 제출

2.4 인증

// agentz-studio 전용 API Key 검증
Authorization: Bearer agentz_sk_xxxxx
+ X-User-Id: {userId} // 대상 사용자 컨텍스트

2.5 JSON-RPC 메시지 형식

요청 예시 (tools/call):

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "get_sleep_log_range",
    "arguments": {
      "userId": "user-123",
      "fromDayIndex": 1,
      "toDayIndex": 7
    }
  }
}

응답 예시:

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"logs\": [...], \"summary\": {...}}"
      }
    ]
  }
}

2.6 참조 파일

apps/dta-wide-mcp/src/mcp-server/mcp-server.service.ts (패턴 참조 - 단, Streamable HTTP로 업데이트 필요)
apps/dta-wide-mcp/src/mcp-server/mcp-tools.service.ts (도구 등록 패턴)
MCP 공식 스펙: https://modelcontextprotocol.io/specification/2025-03-26/basic/transports

3. Phase 2: dha-sleep-app-web 채팅 클라이언트 변경 (1주)

3.1 변경 파일

주요 변경:

apps/dha-sleep-app-web/app/api/chat/route.ts

신규 파일:

apps/dha-sleep-app-web/lib/agentz/client.ts
apps/dha-sleep-app-web/lib/agentz/types.ts

3.2 route.ts 변경 내용

// 변경 전: dha-sleep-api 직접 호출
const response = await fetch(`${DHA_SLEEP_API_BASE_URL}/chat/messages`, ...)

// 변경 후: agentz-studio API 호출
const agentzUrl = process.env.AGENTZ_API_URL;
const response = await fetch(`${agentzUrl}/agents/sleepz-council/chat/completions`, {
  headers: {
    'Authorization': `Bearer ${process.env.AGENTZ_API_KEY}`,
    'X-User-Token': authToken,  // 사용자 컨텍스트 전달
  },
  // ...
});

3.3 환경 변수 추가

# .env.dev, .env.prod
AGENTZ_API_URL=https://api.agentz.studio/v1
AGENTZ_API_KEY=agentz_sk_xxxx
AGENTZ_AGENT_ID=sleepz-council

3.4 SSE 스트리밍 유지

기존 JsonToSseTransformStream 로직 재사용하되, agentz-studio의 SSE 형식에 맞게 파싱 로직 조정.

4. Phase 3: 대화 맥락 구독 및 데이터 투영 (1주)

4.1 Webhook 엔드포인트

경로: apps/dha-sleep-api/src/app/webhooks/agentz/

webhooks/agentz/
├── agentz-webhook.module.ts
├── agentz-webhook.controller.ts      # POST /webhooks/agentz/conversation
└── agentz-webhook.service.ts         # 이벤트 처리

4.2 이벤트 처리 흐름

agentz-studio (대화 완료)
    ↓ POST /webhooks/agentz/conversation
    {
      eventType: 'conversation.completed',
      sessionId: string,
      userId: string,
      messages: Message[],
      extractedEntities: Entity[]
    }
    ↓
AgentzWebhookController
    ↓ (서명 검증)
ConversationIngressService.processExternalConversation()
    ↓
ExtractionOrchestratorService (필요시 추가 추출)
    ↓
EntityRouterService → Sleep/Medication/Questionnaire 도메인

4.3 기존 로직 재사용

libs/feature/conversation/: ConversationIngressService, EntityRouterService
libs/feature/multi-agent-orchestration/: ContextAssembler (MCP Tool 응답 포맷)

5. 마이그레이션 전략

5.1 2단계 직접 전환 (확정)

Stage	기간	설명	Feature Flag
Parallel	1-2주	두 경로 모두 구현, 기존 경로 기본값	`AGENTZ_ENABLED=false`
Full	-	agentz 경로만 사용	`AGENTZ_ENABLED=true`

Note: Shadow Mode 생략 - 직접 전환 방식 선택

5.2 롤백 조건

Error rate > 5%
P99 latency > 3초
Critical bug 발견

5.3 롤백 절차

Feature flag 비활성화 (AGENTZ_ENABLED=false)
배포 없이 즉시 적용 (환경 변수)
인시던트 분석 후 수정

6. Critical Files Summary

수정 필요

파일	변경 내용
`apps/dha-sleep-app-web/app/api/chat/route.ts`	agentz-studio API 호출로 변경
`apps/dha-sleep-api/src/app/app.module.ts`	McpModule, WebhookModule 추가

신규 생성

파일	용도
`apps/dha-sleep-api/src/app/mcp/*`	MCP Server 구현
`apps/dha-sleep-api/src/app/webhooks/agentz/*`	Webhook 핸들러
`apps/dha-sleep-app-web/lib/agentz/*`	agentz 클라이언트

참조 (패턴)

파일	참조 이유
`apps/dta-wide-mcp/src/mcp-server/*`	MCP Server 기본 패턴 (Streamable HTTP로 업그레이드 필요)
`libs/feature/conversation/src/lib/application/ingress/*`	대화 수신 처리 패턴
MCP 공식 스펙	https://modelcontextprotocol.io/specification/2025-03-26/basic/transports

7. 타임라인 요약

Phase	기간	주요 산출물
Phase 1	2주	dha-sleep-api MCP Server 구현 (직접 추가)
Phase 2	1주	dha-sleep-app-web 채팅 클라이언트 변경
Phase 3	1주	Webhook + Conversation Signal 연동
마이그레이션	1-2주	직접 전환 및 안정화 (Shadow Mode 생략)
합계	5-6주

8. 의존성 확인 필요 사항

agentz-studio API 스펙 확정: SSE 형식, 인증 방식, Webhook 스펙 ✅ 확정됨
agentz-studio 배포 URL: staging/production 엔드포인트
API Key 발급: dha-sleep-app-web용 Project API Key
Webhook 비밀키: 서명 검증용 secret

9. 리스크

리스크	영향	대응
agentz-studio API 장애	High	Circuit breaker + fallback
SSE 형식 불일치	Medium	변환 레이어 구현
대화 맥락 유실	Medium	Webhook retry + 이벤트 저장
인증 토큰 관리	Low	자동 갱신 구현

변경 이력

버전	날짜	작성자	변경 내용
1.0.0	2025-12-19	bok@weltcorp.com	최초 작성
1.1.0	2025-12-20	bok@weltcorp.com	MCP Streamable HTTP (2025-03-26) 스펙 반영

1. 개요 (Executive Summary)​

1.1 변경 목적​

1.2 현재 vs 목표 아키텍처​

1.3 참조 문서​

2. Phase 1: dha-sleep-api MCP Server 구현 (2주)​

2.1 신규 모듈 생성​

2.2 MCP 엔드포인트 (Streamable HTTP - 2025-03-26 스펙)​

2.3 도메인별 Tool 정의​

2.4 인증​

2.5 JSON-RPC 메시지 형식​

2.6 참조 파일​

3. Phase 2: dha-sleep-app-web 채팅 클라이언트 변경 (1주)​

3.1 변경 파일​

3.2 route.ts 변경 내용​

3.3 환경 변수 추가​

3.4 SSE 스트리밍 유지​

4. Phase 3: 대화 맥락 구독 및 데이터 투영 (1주)​

4.1 Webhook 엔드포인트​

4.2 이벤트 처리 흐름​

4.3 기존 로직 재사용​

5. 마이그레이션 전략​

5.1 2단계 직접 전환 (확정)​

5.2 롤백 조건​

5.3 롤백 절차​

6. Critical Files Summary​

수정 필요​

신규 생성​

참조 (패턴)​

7. 타임라인 요약​

8. 의존성 확인 필요 사항​

9. 리스크​

변경 이력​