HMM AI 업무 에이전트 유지보수성 모듈화 설계서 (#701)
프로젝트 개요
정식 서비스명은 HMM AI 업무 에이전트이며 현재 소스 경계는 ai-web-agent-console/이다.
과거 poc4_active_source_20260714 스냅샷 경로는 #742에서 제거했다. HMM MCP를 통해 HR 데이터,
표준 용어, 규정 문서를 조회하고 대화 이력과 보안 관리 화면을 제공한다.
목표
기능을 바꾸지 않고 대형 화면 파일의 책임을 분리한다. 설정 해석과 MCP Streamable HTTP 통신은 Streamlit 화면 코드에서 제거해 독립적으로 검증할 수 있게 한다.
현재 문제
ai-web-agent-console/app.py가 화면, 설정, 인증, SQLite 대화 이력, MCP JSON-RPC, Agent 실행을 함께 관리한다.- MCP 설정과 인증 토큰 규칙을 수정할 때 화면 코드까지 함께 읽어야 한다.
- MCP 프로토콜 처리의 단위 검증 지점이 없다.
모듈 경계
| 모듈 | 책임 | Streamlit 의존 |
|---|---|---|
ai-web-agent-console/ai_web_agent_console/profile.py |
제품 프로필과 환경 override 로드 | 없음 |
ai-web-agent-console/ai_web_agent_console/mcp_tool_router.py |
MCP 도구 discovery 결과의 route와 arguments 구성 | 없음 |
ai-web-agent-console/ai_web_agent_console/auth_gateway.py |
로그인·쿠키·세션 경계 | 없음 |
ai-web-agent-console/ai_web_agent_console/audit.py |
감사·증적 조회 경계 | 없음 |
ai-web-agent-console/app.py |
사용자 입력, 상태, 화면 렌더링, 업무 Agent orchestration | 있음 |
재사용 UI Shell과 제품 프로필
공통 화면 shell은 ai-web-agent-console/ai_web_agent_console/에서 제공하고, 특정 고객·PoC의 표현은
config/app_profile.json에 둔다. 다른 프로젝트는 앱 코드를 복사·수정하지 않고 profile JSON을
교체할 수 있다. 실제 배포에서는 AGENT_CONSOLE_NAME, AGENT_CONSOLE_HEADER_DESCRIPTION,
AGENT_CONSOLE_PRIMARY_COLOR 등 AGENT_CONSOLE_* 환경변수가 JSON 기본값보다 우선한다.
따라서 고객별 제품명·설명·색상은 같은 컨테이너 이미지와 코드로 운영할 수 있다.
| 구분 | 공통화 대상 | 제품별 설정 |
|---|---|---|
| 화면 shell | light theme, sidebar, 입력/버튼, 로그인/헤더 renderer | 제품명, 문구, 아이콘, 색상 |
| 데모 질문 | JSON loader와 중복·형식 검증 | config/hmm_demo_scenarios.json의 질문 목록 |
| MCP 연결 | JSON registry와 server token env 참조 | endpoint, allowlist, token env 이름 |
poc4 접두어가 있는 app path, session key, DB 파일명은 배포 호환성을 위한 레거시 경계다.
새 코드에는 서비스/모듈 이름으로 사용하지 않으며, 별도 migration 작업에서만 제거한다.
추적 및 현행화 규칙
이 설계서는 HMM AI 업무 에이전트의 UI shell·제품 profile·데모 시나리오 구조에 대한 기준 문서다.
- 구조나 JSON schema를 변경하면 이 문서의 모듈 경계와 호환성 원칙을 먼저 갱신한다.
- 변경은 Redmine 이슈에 설계·검증 결과와 Git commit SHA를 함께 기록한다.
- Git commit message에는 Redmine 번호를
refs #<번호>:형식으로 포함한다. - 환경별 값과 비밀값은 profile JSON에 넣지 않고
.env또는 secret store에만 둔다. - UI CSS는
ai-web-agent-console/ai_web_agent_console/presentation.py한 곳에서 관리한다. 제품별 색상과 문구는 Python/CSS를 수정하지 않고app_profile.json으로 조정한다.
도메인 로직의 공개 오류는 PublicMcpError로 통일한다. UI는 이 오류를 사람이 이해할 수 있는 메시지로 표시하되 토큰과 HTTP 원문을 출력하지 않는다.
호환성 원칙
- 기존 환경변수, JSON 키, SQLite 테이블과 세션 키를 유지한다.
- HMM MCP의 서버 전용
HMM_MCP_BEARER_TOKEN규칙을 유지한다. - HTTP 400이 발생하는 MCP에 대해 기존 initialize/session fallback을 유지한다.
- 외부 호출은 read-only tool만 사용하며 UI의 요청·응답 형식을 변경하지 않는다.
검증 기준
py_compile및 모듈 import가 성공한다.- 설정 JSON을 읽어 HMM MCP 한 개와 allowlist 세 개가 확인된다.
- HTTP mocking으로 일반 JSON-RPC와 session fallback을 검증한다.
- 운영 서버에서
tools/list로 HMM MCP 세 도구가 발견되고 Streamlit health/UI가 정상 응답한다.
단계
- 설정·MCP transport·대화 저장소를 순수 Python 모듈로 추출한다.
- 화면 파일은 새 공개 API만 사용하도록 교체한다.
- 단위 검증과 운영 smoke test 후 Git/Gitea에 반영한다.