Update docs/agent-architecture.md

docs/agent-architecture.md

@@ -7,7 +7,7 @@
 1. `bootstrap.py`에서 환경변수와 런타임 데이터 경로를 준비
 2. `retrieval.py`에서 FAISS 인덱스와 메타데이터를 로드
 3. `agent.py`에서 Google ADK `LlmAgent`와 retrieval tool 구성
-4. `chat.py`에서 세션 실행과 대화 요약 관리
+4. `chat.py`에서 세션 실행, 스트리밍 응답, 대화 요약 관리
 5. `app_gradio.py`에서 PC/모바일 반응형 채팅 UI 제공
 
 ## 파일별 역할
@@ -46,7 +46,7 @@
 
 - 메구밍 페르소나 프롬프트 정의
 - `retrieve_megumin_examples` tool 정의
-- 페르소나용 top-3, 사실용 top-3를 각각 수집
+- 페르소나용 top-2, 사실용 top-2를 각각 수집
 - ADK callback으로 대화 요약, 최근 질의, RAG 흔적을 state에 기록
 
 tool 반환 핵심:
@@ -59,7 +59,8 @@ tool 반환 핵심:
 ### `megumin_agent/chat.py`
 
 - `Runner`와 `InMemorySessionService` 생성
-- `chat_once()`로 질문 1회 실행과 최종 응답 수집
+- `stream_chat()`으로 ADK SSE 스트리밍 응답 생성
+- `chat_once()`는 스트리밍 결과를 모아 최종 문자열만 필요할 때 사용하는 래퍼
 - 최근 6턴을 남기고, 그 이전 대화는 `conversation_summary_map` key-value 구조로 압축
 - 압축된 요약은 짧은 문자열 형태의 `conversation_summary`로도 함께 렌더링
 
@@ -78,13 +79,21 @@ tool 반환 핵심:
 - `create_chat_services()`는 import 시점이 아니라 첫 질문 시점에 lazy init
 - 첫 질문 전에는 `서비스 준비 중...`, 이후 응답 생성 중에는 `답변 생성 중...` 상태 표시
 - 작은 규칙 기반 상태 배지를 추가해 메구밍의 현재 분위기를 표시
+- ADK의 SSE partial event를 받아 답변을 점진적으로 스트리밍 표시
 - `launch(..., ssr_mode=False)`로 서버 사이드 렌더링을 끄고 초기 기동 부담을 줄임
 - 모바일에서는 좌우 glass panel을 숨기고, 제목, 최소 설명, 이미지, 채팅창만 보이도록 단순화
 
+### `app_gradio_messenger.py`
+
+- 기존 agent/chat 로직을 그대로 재사용하는 메신저형 UI
+- 좌측 3, 우측 7 비율의 2섹터 레이아웃
+- 좌측: 캐릭터 프로필 목록과 최근 대화 미리보기
+- 우측: 캐릭터 좌측 말풍선, 사용자 우측 말풍선 구조의 대화창
+
 ### `app.py`
 
 - Hugging Face Spaces 진입점
-- `app_gradio.py`의 `demo`를 그대로 로드
+- `MEGUMIN_UI` 환경변수로 기본 UI와 메신저 UI 중 하나를 선택해 로드
 
 ## 대화 흐름
 
@@ -92,13 +101,13 @@ tool 반환 핵심:
 
 1. `app_gradio.py`가 상태 문구를 먼저 갱신
 2. 첫 질문이면 `get_services()`가 lazy init으로 서비스 준비
-3. `chat.py`가 ADK `run_async(...)`로 세션을 실행
+3. `chat.py`의 `stream_chat()`이 ADK `run_async(..., RunConfig(streaming_mode=SSE))`로 실행
 4. `agent.py`의 tool이 retrieval 수행
 5. `retrieval.py`가
-   - 페르소나 데이터 top-3
-   - 사실 데이터 top-3
+   - 페르소나 데이터 top-2
+   - 사실 데이터 top-2
    를 각각 검색
-6. 최종 assistant 답변을 UI에 한 번에 반영
+6. ADK partial event가 들어올 때마다 UI가 assistant 답변을 점진적으로 갱신
 7. 세션 종료 후 오래된 이벤트를 key-value summary로 압축
 
 ## 세션과 메모리