Update docs/agent-architecture.md

docs/agent-architecture.md

@@ -7,8 +7,8 @@
 1. `bootstrap.py`에서 환경변수와 런타임 데이터 경로를 준비
 2. `retrieval.py`에서 FAISS 인덱스와 메타데이터를 로드
 3. `agent.py`에서 Google ADK `LlmAgent`와 retrieval tool 구성
-4. `chat.py`에서 세션 실행과 대화 요약 관리
-5. `app_gradio.py`에서 PC용 채팅 UI 제공
+4. `chat.py`에서 세션 실행, 스트리밍 응답, 대화 요약 관리
+5. `app_gradio.py`에서 PC/모바일 반응형 채팅 UI 제공
 
 ## 파일별 역할
 
@@ -59,19 +59,27 @@ tool 반환 핵심:
 ### `megumin_agent/chat.py`
 
 - `Runner`와 `InMemorySessionService` 생성
-- 질문 1회 실행 단위인 `chat_once()` 제공
-- 최근 6턴을 남기고, 그 이전 대화는 `conversation_summary`로 압축
+- `stream_chat()`으로 ADK SSE 스트리밍 응답 생성
+- `chat_once()`는 스트리밍 결과를 모아 최종 문자열만 필요할 때 사용하는 래퍼
+- 최근 6턴을 남기고, 그 이전 대화는 `conversation_summary_map` key-value 구조로 압축
+- 압축된 요약은 짧은 문자열 형태의 `conversation_summary`로도 함께 렌더링
+
+요약 구조:
+
+- `user_topics`
+- `assistant_points`
 
 ### `app_gradio.py`
 
 - PC용 3패널 레이아웃 제공
-- 왼쪽: 메구밍 프로필, 페르소나 설명, 예시 질문
-- 가운데: 반투명 채팅 패널
+- 왼쪽: 메구밍 프로필과 예시 질문
+- 가운데: 채팅 패널
 - 오른쪽: 메구밍 비주얼 패널
-- 배경에는 흐릿한 메구밍 일러스트와 폭렬 분위기 레이어를 배치
+- 첫 접속 시 기본 인삿말을 assistant 메시지로 미리 표시
 - `create_chat_services()`는 import 시점이 아니라 첫 질문 시점에 lazy init
 - 첫 질문 전에는 `서비스 준비 중...`, 이후 응답 생성 중에는 `답변 생성 중...` 상태 표시
-- 모바일에서는 별도 페이지가 아니라 같은 페이지를 채팅 중심으로 재배치
+- 작은 규칙 기반 상태 배지를 추가해 메구밍의 현재 분위기를 표시
+- ADK의 SSE partial event를 받아 답변을 점진적으로 스트리밍 표시
 - 모바일에서는 제목, 최소 설명, 이미지, 채팅창만 보이도록 단순화
 
 ### `app.py`
@@ -83,15 +91,16 @@ tool 반환 핵심:
 
 사용자 입력이 들어오면:
 
-1. `app_gradio.py`가 `chat_once()` 호출
-2. `chat.py`가 ADK Runner로 세션 실행
-3. `agent.py`의 tool이 retrieval 수행
-4. `retrieval.py`가
+1. `app_gradio.py`가 상태 문구를 먼저 갱신
+2. 첫 질문이면 `get_services()`가 lazy init으로 서비스 준비
+3. `chat.py`의 `stream_chat()`이 ADK `run_async(..., RunConfig(streaming_mode=SSE))`로 실행
+4. `agent.py`의 tool이 retrieval 수행
+5. `retrieval.py`가
    - 페르소나 데이터 top-3
    - 사실 데이터 top-3
    를 각각 검색
-5. Agent가 두 종류의 근거를 함께 참고해 메구밍 말투로 답변
-6. 세션 종료 후 오래된 이벤트를 요약 상태로 압축
+6. ADK partial event가 들어올 때마다 UI가 assistant 답변을 점진적으로 갱신
+7. 세션 종료 후 오래된 이벤트를 key-value summary로 압축
 
 ## 세션과 메모리
 
@@ -100,12 +109,13 @@ tool 반환 핵심:
 - 서버 프로세스가 살아 있는 동안만 유지
 - 재시작 시 초기화
 - 최근 6턴만 유지
-- 오래된 내용은 짧은 summary로 state에 남김
+- 오래된 내용은 `user_topics`, `assistant_points` 중심의 key-value summary로 state에 남김
 
 ## UI 목적
 
-현재 UI는 모바일 전용이 아니라 PC 화면 기준입니다.
+현재 UI는 체험형 캐릭터 챗봇 화면을 목표로 합니다.
 
 - 캐릭터와 실제로 마주 보고 대화하는 느낌
 - 반투명 유리 패널 중심 구성
-- 메구밍 세계관과 챗봇 사용법을 한 화면에서 안내
+- 메구밍의 기본 소개와 사용 예시 제공
+- 스트리밍 답변과 작은 상태 배지로 생동감 보강