Upload 3 files

docs/Google-ADK.md

@@ -0,0 +1,1127 @@
+# Google ADK 핵심 개념 완전 가이드
+
+이 문서는 Google Agent Development Kit (ADK)의 핵심 개념들을 체계적으로 설명합니다.
+샘플 코드에서 사용된 모든 중요 요소들을 이해할 수 있도록 구성했습니다.
+
+---
+
+## 📚 목차
+
+1. [전체 아키텍처 개요](#1-전체-아키텍처-개요)
+2. [Session (세션)](#2-session-세션)
+3. [State (상태)](#3-state-상태)
+4. [Event (이벤트)](#4-event-이벤트)
+5. [Context (컨텍스트)](#5-context-컨텍스트)
+6. [Runner (러너)](#6-runner-러너)
+7. [Memory (메모리)](#7-memory-메모리)
+8. [Callbacks (콜백)](#8-callbacks-콜백)
+9. [Tools (도구)](#9-tools-도구)
+10. [핵심 개념 간의 관계](#10-핵심-개념-간의-관계)
+
+---
+
+## 1. 전체 아키텍처 개요
+
+### ADK의 핵심 철학
+
+ADK는 **"에이전트 개발을 소프트웨어 개발처럼"** 만드는 것을 목표로 합니다.
+복잡한 AI 에이전트 시스템을 모듈화하고, 테스트 가능하며, 유지보수하기 쉽게 만듭니다.
+
+### 핵심 컴포넌트 다이어그램
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        사용자 (User)                             │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                     Runner (러너/오케스트레이터)                   │
+│  - 실행 루프 관리                                                 │
+│  - 이벤트 처리 및 라우팅                                          │
+│  - 서비스 조율                                                    │
+└─────────────────────────────────────────────────────────────────┘
+            │                    │                    │
+            ▼                    ▼                    ▼
+┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐
+│  SessionService  │  │  MemoryService   │  │ ArtifactService  │
+│  (세션 관리)      │  │  (장기 기억)      │  │  (파일/데이터)    │
+└──────────────────┘  └──────────────────┘  └──────────────────┘
+            │
+            ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                      Session (세션)                              │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐ │
+│  │   State     │  │   Events    │  │  Metadata (ID, User)    │ │
+│  │  (상태)     │  │  (이벤트들)  │  │                         │ │
+│  └─────────────┘  └─────────────┘  └─────────────────────────┘ │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                      Agent (에이전트)                            │
+│  ┌─────────────────────────────────────────────────────────┐   │
+│  │  InvocationContext (호출 컨텍스트)                        │   │
+│  │  - session, state, services 접근                        │   │
+│  └─────────────────────────────────────────────────────────┘   │
+│                              │                                   │
+│              ┌───────────────┼───────────────┐                  │
+│              ▼               ▼               ▼                  │
+│        ┌─────────┐     ┌─────────┐     ┌─────────┐             │
+│        │ Tools   │     │ LLM     │     │Callbacks│             │
+│        │ (도구)  │     │ (모델)  │     │ (콜백)  │             │
+│        └─────────┘     └─────────┘     └─────────┘             │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 2. Session (세션)
+
+### 개념
+
+**Session**은 사용자와 에이전트 간의 **단일 대화 스레드**를 나타냅니다.
+전화 통화에 비유하면, 하나의 통화가 하나의 세션입니다.
+
+### 주요 속성
+
+```python
+from google.adk.sessions import Session
+
+# Session의 주요 속성
+session.id           # 세션 고유 ID
+session.app_name     # 애플리케이션 이름
+session.user_id      # 사용자 ID
+session.state        # 상태 딕셔너리 (State)
+session.events       # 이벤트 히스토리 리스트
+session.last_update_time  # 마지막 업데이트 시간
+```
+
+### SessionService
+
+세션의 생명주기를 관리하는 서비스입니다.
+
+```python
+from google.adk.sessions import InMemorySessionService
+
+# 세션 서비스 생성
+session_service = InMemorySessionService()
+
+# 새 세션 생성
+session = await session_service.create_session(
+    app_name="my_app",
+    user_id="user_123",
+    state={"initial_key": "initial_value"}  # 초기 상태 설정 가능
+)
+
+# 기존 세션 조회
+session = await session_service.get_session(
+    app_name="my_app",
+    user_id="user_123",
+    session_id="session_abc"
+)
+
+# 세션 목록 조회
+sessions = await session_service.list_sessions(
+    app_name="my_app",
+    user_id="user_123"
+)
+
+# 세션 삭제
+await session_service.delete_session(
+    app_name="my_app",
+    user_id="user_123",
+    session_id="session_abc"
+)
+```
+
+### SessionService 구현체 종류
+
+| 구현체                   | 저장 위치    | 영속성                 | 용도          |
+| ------------------------ | ------------ | ---------------------- | ------------- |
+| `InMemorySessionService` | 메모리       | ❌ (앱 재시작 시 소멸) | 개발/테스트   |
+| `DatabaseSessionService` | SQL DB       | ✅                     | 프로덕션      |
+| `VertexAISessionService` | Google Cloud | ✅                     | 클라우드 배포 |
+
+### 세션 생명주기
+
+```
+┌─────────────┐     ┌─────────────┐     ┌─────────────┐
+│   CREATE    │ ──▶ │   UPDATE    │ ──▶ │   DELETE    │
+│  (생성)     │     │ (이벤트 추가)│     │   (종료)    │
+└─────────────┘     └─────────────┘     └─────────────┘
+                          │
+                          ▼
+                    ┌─────────────┐
+                    │   State     │
+                    │   변경      │
+                    └─────────────┘
+```
+
+---
+
+## 3. State (상태)
+
+### 개념
+
+**State**는 세션 내에서 데이터를 저장하는 **키-값 저장소**입니다.
+에이전트의 "메모장" 역할을 하며, 대화 중 필요한 정보를 기억합니다.
+
+### State의 범위 (Prefix)
+
+ADK에서 State는 **prefix**로 범위를 구분합니다:
+
+| Prefix  | 범위         | 설명                                          |
+| ------- | ------------ | --------------------------------------------- |
+| (없음)  | 세션 전체    | 기본값, 세션 동안 유지                        |
+| `app:`  | 애플리케이션 | 같은 앱의 모든 세션에서 공유                  |
+| `user:` | 사용자       | 같은 사용자의 모든 세션에서 공유              |
+| `temp:` | 현재 호출    | 현재 invocation에서만 유지, 호출 종료 시 삭제 |
+
+```python
+# State 사용 예시
+ctx.session.state["user_name"] = "홍길동"           # 세션 범위
+ctx.session.state["app:settings"] = {"theme": "dark"}  # 앱 전체 공유
+ctx.session.state["user:preferences"] = {"lang": "ko"} # 사용자 공유
+ctx.session.state["temp:current_step"] = 3         # 현재 호출만
+```
+
+### State 읽기/쓰기
+
+#### 1. output_key를 통한 자동 저장 (LlmAgent)
+
+```python
+from google.adk.agents import LlmAgent
+
+# 에이전트 응답이 자동으로 state['analysis_result']에 저장됨
+agent = LlmAgent(
+    name="Analyzer",
+    instruction="데이터를 분석하세요.",
+    output_key="analysis_result"  # ← 자동 저장
+)
+```
+
+#### 2. Instruction 템플릿에서 읽기
+
+```python
+agent = LlmAgent(
+    name="Reporter",
+    instruction="""
+    이전 분석 결과: {analysis_result}
+    위 결과를 바탕으로 보고서를 작성하세요.
+    """  # ← {key} 형식으로 자동 주입
+)
+```
+
+#### 3. Tool/Callback에서 직접 접근
+
+```python
+from google.adk.tools import ToolContext
+
+def my_tool(context: ToolContext, query: str) -> dict:
+    # 읽기
+    user_name = context.state.get("user_name", "Unknown")
+
+    # 쓰기 (자동으로 state_delta에 추적됨)
+    context.state["last_query"] = query
+    context.state["query_count"] = context.state.get("query_count", 0) + 1
+
+    return {"result": f"Hello {user_name}, processed: {query}"}
+```
+
+### ⚠️ State 수정 시 주의사항
+
+```python
+# ❌ 잘못된 방법: 세션 객체 직접 수정
+session = await session_service.get_session(...)
+session.state["key"] = "value"  # 추적되지 않음!
+
+# ✅ 올바른 방법: Context를 통해 수정
+def my_callback(context: CallbackContext):
+    context.state["key"] = "value"  # 자동 추적됨
+```
+
+---
+
+## 4. Event (이벤트)
+
+### 개념
+
+**Event**는 세션 내에서 발생하는 **모든 활동의 기록 단위**입니다.
+사용자 메시지, 에이전트 응답, 도구 호출, 상태 변경 등 모든 것이 이벤트입니다.
+
+### Event 구조
+
+```python
+from google.adk.events import Event, EventActions
+
+event = Event(
+    # 식별 정보
+    id="event_123",              # 고유 ID
+    invocation_id="inv_456",     # 소속 invocation ID
+    author="MyAgent",            # 생성자 (에이전트명)
+
+    # 내용
+    content=types.Content(       # 실제 메시지/데이터
+        parts=[types.Part(text="안녕하세요!")]
+    ),
+
+    # 액션/변경사항
+    actions=EventActions(
+        state_delta={"key": "value"},  # 상태 변경
+        artifact_delta={},              # 아티팩트 변경
+        escalate=False,                 # 루프 종료 신호
+        transfer_to_agent="OtherAgent", # 에이전트 전환
+    ),
+
+    # 메타데이터
+    timestamp=1234567890.0,
+    partial=False,               # 스트리밍 중간 결과 여부
+)
+```
+
+### Event 유형
+
+| 유형          | 설명                 | 식별 방법                        |
+| ------------- | -------------------- | -------------------------------- |
+| 사용자 메시지 | 사용자 입력          | `event.content.role == "user"`   |
+| 텍스트 응답   | 에이전트 텍스트 응답 | `event.content.parts[0].text`    |
+| 도구 호출     | LLM이 도구 호출 요청 | `event.get_function_calls()`     |
+| 도구 결과     | 도구 실행 결과       | `event.get_function_responses()` |
+| 상태 변경     | State 업데이트       | `event.actions.state_delta`      |
+| 스트리밍 청크 | 부분 응답            | `event.partial == True`          |
+
+### EventActions
+
+이벤트에 연결된 **부수 효과(side effects)**를 정의합니다:
+
+```python
+from google.adk.events import EventActions
+
+actions = EventActions(
+    # 상태 변경
+    state_delta={"new_key": "new_value"},
+
+    # 루프 종료 신호 (LoopAgent에서 사용)
+    escalate=True,
+
+    # 에이전트 전환 (LLM Transfer)
+    transfer_to_agent="TargetAgentName",
+
+    # 아티팩트(파일) 변경
+    artifact_delta={"file.txt": "content"},
+)
+```
+
+### Event 처리 흐름
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│                     Event 생성 및 처리 흐름                    │
+└──────────────────────────────────────────────────────────────┘
+
+1. Event 생성
+   Agent/Tool/Callback → yield Event(...)
+
+2. Runner 수신
+   Runner가 이벤트를 받음
+
+3. SessionService 처리
+   - state_delta를 session.state에 병합
+   - artifact_delta 처리
+   - events 히스토리에 추가
+
+4. 클라이언트 전달
+   - UI/API로 이벤트 스트리밍
+```
+
+---
+
+## 5. Context (컨텍스트)
+
+### 개념
+
+**Context**는 현재 실행 상황에 대한 **모든 정보를 담은 컨테이너**입니다.
+에이전트, 도구, 콜백이 실행될 때 필요한 모든 정보에 접근할 수 있게 합니다.
+
+### Context 유형
+
+#### 1. InvocationContext (호출 컨텍스트)
+
+가장 상위 레벨의 컨텍스트로, 하나의 사용자 요청 처리 전체를 관장합니다.
+
+```python
+from google.adk.agents import BaseAgent
+from google.adk.agents.invocation_context import InvocationContext
+
+class MyAgent(BaseAgent):
+    async def _run_async_impl(self, ctx: InvocationContext):
+        # 세션 정보 접근
+        session_id = ctx.session.id
+        user_id = ctx.session.user_id
+
+        # 상태 접근
+        state_value = ctx.session.state.get("key")
+
+        # 서비스 접근
+        memory_service = ctx.memory_service
+        artifact_service = ctx.artifact_service
+
+        # 현재 에이전트 정보
+        agent_name = ctx.agent.name
+
+        # 호출 제어
+        ctx.end_invocation = True  # 호출 종료 신호
+
+        yield Event(author=self.name, content=...)
+```
+
+#### 2. CallbackContext (콜백 컨텍스트)
+
+콜백 함수에서 사용되며, InvocationContext의 서브셋입니다.
+
+```python
+from google.adk.agents.callback_context import CallbackContext
+
+def my_before_agent_callback(ctx: CallbackContext):
+    # 에이전트 정보
+    agent_name = ctx.agent_name
+    invocation_id = ctx.invocation_id
+
+    # 상태 읽기/쓰기
+    ctx.state["processed"] = True
+
+    # 사용자 입력 확인
+    user_content = ctx.user_content
+
+    return None  # 계속 진행 (또는 Content 반환 시 에이전트 건너뜀)
+```
+
+#### 3. ToolContext (도구 컨텍스트)
+
+도구(Tool) 함수에서 사용되며, 도구 실행에 필요한 추가 기능을 제공합니다.
+
+```python
+from google.adk.tools import ToolContext
+
+def my_tool(context: ToolContext, query: str) -> dict:
+    # 상태 접근 (CallbackContext와 동일)
+    context.state["last_query"] = query
+
+    # 도구 전용 기능
+    function_call_id = context.function_call_id  # 현재 함수 호출 ID
+
+    # 메모리 검색
+    results = await context.search_memory("검색어")
+
+    # 아티팩트 목록
+    artifacts = context.list_artifacts()
+
+    # 인증 요청 (OAuth 등)
+    credential = await context.get_auth_response(auth_config)
+
+    return {"result": "success"}
+```
+
+### Context 계층 구조
+
+```
+InvocationContext (최상위)
+├── session
+│   ├── state
+│   └── events
+├── agent (현재 에이전트)
+├── services (memory, artifact, session)
+└── invocation_id
+
+    ▼ 파생
+
+CallbackContext (콜백용)
+├── state (읽기/쓰기)
+├── agent_name
+├── user_content
+└── invocation_id
+
+    ▼ 확장
+
+ToolContext (도구용)
+├── (CallbackContext의 모든 것)
+├── function_call_id
+├── search_memory()
+├── list_artifacts()
+└── request_credential()
+```
+
+---
+
+## 6. Runner (러너)
+
+### 개념
+
+**Runner**는 에이전트 실행의 **중앙 오케스트레이터**입니다.
+사용자 입력을 받아 에이전트를 실행하고, 이벤트를 처리하며, 서비스들을 조율합니다.
+
+### 기본 사용법
+
+```python
+from google.adk.runners import InMemoryRunner, Runner
+from google.adk.sessions import InMemorySessionService
+
+# 방법 1: InMemoryRunner (간단한 테스트용)
+runner = InMemoryRunner(
+    agent=my_agent,
+    app_name="my_app"
+)
+
+# 방법 2: Runner (커스터마이징 필요 시)
+session_service = InMemorySessionService()
+runner = Runner(
+    agent=my_agent,
+    app_name="my_app",
+    session_service=session_service,
+    # memory_service=my_memory_service,  # 옵션
+    # artifact_service=my_artifact_service,  # 옵션
+)
+```
+
+### 에이전트 실행
+
+```python
+# 비동기 실행 (일반적인 방법)
+async for event in runner.run_async(
+    user_id="user_123",
+    session_id="session_456",  # 새 세션이면 자동 생성
+    new_message="안녕하세요!"
+):
+    if event.content and event.content.parts:
+        for part in event.content.parts:
+            if hasattr(part, 'text') and part.text:
+                print(f"[{event.author}]: {part.text}")
+
+# 실시간 스트리밍 (음성/영상)
+async for event in runner.run_live(...):
+    ...
+```
+
+### Runner 실행 흐름
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                      Runner.run_async() 흐름                     │
+└─────────────────────────────────────────────────────────────────┘
+
+1. 세션 준비
+   ┌─────────────────┐
+   │ get/create      │ ← 세션 조회 또는 생성
+   │ Session         │
+   └─────────────────┘
+          │
+          ▼
+2. 사용자 메시지를 이벤트로 추가
+   ┌─────────────────┐
+   │ append_event    │ ← 사용자 입력을 세션 히스토리에 추가
+   │ (user message)  │
+   └─────────────────┘
+          │
+          ▼
+3. InvocationContext 생성
+   ┌─────────────────┐
+   │ Create          │ ← 실행에 필요한 모든 정보 준비
+   │ InvocationContext│
+   └─────────────────┘
+          ��
+          ▼
+4. 에이전트 실행 루프
+   ┌─────────────────────────────────────────────┐
+   │  ┌─────────────────┐                        │
+   │  │ Agent.run()     │ ← 에이전트 실행        │
+   │  └─────────────────┘                        │
+   │          │                                   │
+   │          ▼                                   │
+   │  ┌─────────────────┐                        │
+   │  │ yield Event     │ ← 이벤트 생성          │
+   │  └─────────────────┘                        │
+   │          │                                   │
+   │          ▼                                   │
+   │  ┌─────────────────┐                        │
+   │  │ Process Event   │ ← 이벤트 처리          │
+   │  │ - state_delta   │   (상태 업데이트 등)    │
+   │  │ - append to     │                        │
+   │  │   session       │                        │
+   │  └─────────────────┘                        │
+   │          │                                   │
+   │          ▼                                   │
+   │  ┌─────────────────┐                        │
+   │  │ yield to caller │ ← 호출자에게 전달      │
+   │  └─────────────────┘                        │
+   │          │                                   │
+   │          ▼                                   │
+   │  [더 많은 이벤트?] ──Yes──▶ (반복)           │
+   │          │                                   │
+   │         No                                   │
+   │          │                                   │
+   └──────────┼───────────────────────────────────┘
+              │
+              ▼
+5. 실행 완료
+```
+
+### Invocation vs Agent Call vs Step
+
+```
+Invocation (호출)
+│  사용자 메시지 → 최종 응답까지의 전체 사이클
+│
+├── Agent Call 1 (에이전트 호출)
+│   │  하나의 에이전트가 실행되는 단위
+│   │
+│   ├── Step 1 (스텝)
+│   │   └── LLM 호출 1회 + 도구 실행
+│   │
+│   ├── Step 2
+│   │   └── LLM 호출 1회 + 도구 실행
+│   │
+│   └── (transfer_to_agent 발생)
+│
+├── Agent Call 2 (다른 에이전트로 전환)
+│   │
+│   ├── Step 1
+│   │   └── LLM 호출 + 최종 응답
+│   │
+│   └── (완료)
+│
+└── Invocation 종료
+```
+
+---
+
+## 7. Memory (메모리)
+
+### 개념
+
+**Memory**는 **장기 기억 저장소**입니다.
+세션이 종료된 후에도 유지되며, 여러 세션에 걸쳐 정보를 검색할 수 있습니다.
+
+### Session State vs Memory 비교
+
+| 특성      | Session State            | Memory          |
+| --------- | ------------------------ | --------------- |
+| 범위      | 현재 세션 내             | 여러 세션 걸쳐  |
+| 수명      | 세션 종료 시 (보통) 삭제 | 영구 저장       |
+| 접근 방식 | Key-Value 직접 접근      | 검색 쿼리       |
+| 용도      | 대화 중 임시 데이터      | 과거 정보 참조  |
+| 비유      | 대화 중 메모장           | 도서관 아카이브 |
+
+### MemoryService 사용
+
+```python
+from google.adk.memory import InMemoryMemoryService
+
+# 메모리 서비스 생성
+memory_service = InMemoryMemoryService()
+
+# 세션을 메모리에 저장 (대화 종료 후)
+await memory_service.add_session_to_memory(session)
+
+# 메모리 검색
+results = await memory_service.search_memory(
+    app_name="my_app",
+    user_id="user_123",
+    query="이전에 추천받은 음식점"
+)
+
+for result in results.memories:
+    print(result.content)
+```
+
+### MemoryService 구현체
+
+| 구현체                      | 저장 방식 | 검색 방식   | 용도        |
+| --------------------------- | --------- | ----------- | ----------- |
+| `InMemoryMemoryService`     | 메모리    | 키워드 매칭 | 개발/테스트 |
+| `VertexAIMemoryBankService` | Vertex AI | 시맨틱 검색 | 프로덕션    |
+
+### 메모리 워크플로우
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│                    Memory 워크플로우                          │
+└───────────────────────────────────────────────���──────────────┘
+
+1. 세션 대화 진행
+   User ↔ Agent (Session에 Events 축적)
+
+2. 세션 종료 시 메모리 저장
+   memory_service.add_session_to_memory(session)
+   └── 세션의 주요 정보를 메모리에 저장
+
+3. 이후 세션에서 메모리 검색
+   results = memory_service.search_memory(query)
+   └── 과거 대화에서 관련 정보 검색
+
+4. 검색 결과를 현재 대화에 활용
+   Agent가 검색 결과를 참고하여 응답
+```
+
+### 에이전트에서 메모리 사용
+
+```python
+from google.adk.tools import preload_memory_tool
+
+# 메모리 검색 도구 추가
+agent = LlmAgent(
+    name="MemoryAgent",
+    instruction="사용자의 과거 대화를 참고하여 답변하세요.",
+    tools=[preload_memory_tool.PreloadMemoryTool()]
+)
+
+# 세션 종료 시 자동 저장 콜백
+async def auto_save_to_memory(callback_context):
+    await callback_context._invocation_context.memory_service.add_session_to_memory(
+        callback_context._invocation_context.session
+    )
+
+agent = LlmAgent(
+    name="AutoSaveAgent",
+    after_agent_callback=auto_save_to_memory
+)
+```
+
+---
+
+## 8. Callbacks (콜백)
+
+### 개념
+
+**Callback**은 에이전트 실행 중 **특정 시점에 개입**할 수 있는 훅(hook)입니다.
+가드레일, 로깅, 수정 등 다양한 용도로 사용됩니다.
+
+### 콜백 종류 및 실행 시점
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                      콜백 실행 시점                              │
+└─────────────────────────────────────────────────────────────────┘
+
+사용자 입력
+    │
+    ▼
+┌───────────────────────┐
+│ before_agent_callback │  ← 에이전트 실행 전
+└───────────────────────┘
+    │
+    ▼
+┌───────────────────────┐
+│ before_model_callback │  ← LLM 호출 전
+└───────────────────────┘
+    │
+    ▼
+[LLM 호출]
+    │
+    ▼
+┌───────────────────────┐
+│ after_model_callback  │  ← LLM 응답 후
+└───────────────────────┘
+    │
+    ▼
+┌───────────────────────┐
+│ before_tool_callback  │  ← 도구 실행 전
+└───────────────────────┘
+    │
+    ▼
+[도구 실행]
+    │
+    ▼
+┌───────────────────────┐
+│ after_tool_callback   │  ← 도구 실행 후
+└───────────────────────┘
+    │
+    ▼
+┌───────────────────────┐
+│ after_agent_callback  │  ← 에이전트 실행 후
+└───────────────────────┘
+    │
+    ▼
+최종 응답
+```
+
+### 콜백 정의 및 사용
+
+#### before_agent_callback
+
+```python
+from google.adk.agents import LlmAgent
+from google.adk.agents.callback_context import CallbackContext
+from google.genai import types
+
+def check_access(ctx: CallbackContext) -> types.Content | None:
+    """에이전트 실행 전 접근 제어"""
+    user_id = ctx.session.user_id
+
+    # 차단할 사용자 체크
+    if user_id in BLOCKED_USERS:
+        # Content 반환 시 에이전트 실행 건너뜀
+        return types.Content(
+            parts=[types.Part(text="접근이 거부되었습니다.")]
+        )
+
+    # None 반환 시 정상 진행
+    return None
+
+agent = LlmAgent(
+    name="SecureAgent",
+    before_agent_callback=check_access
+)
+```
+
+#### before_model_callback (가드레일)
+
+```python
+from google.adk.models import LlmRequest, LlmResponse
+
+def content_guardrail(ctx: CallbackContext, request: LlmRequest) -> LlmResponse | None:
+    """LLM 호출 전 입력 검사"""
+    user_text = ctx.user_content.parts[0].text
+
+    # 금지어 체크
+    if any(word in user_text for word in FORBIDDEN_WORDS):
+        return LlmResponse(
+            content=types.Content(
+                parts=[types.Part(text="부적절한 내용이 감지되었습니다.")]
+            )
+        )
+
+    # 프롬프트 수정
+    # request.contents를 수정하여 시스템 지시 추가 가능
+
+    return None  # 정상 진행
+
+agent = LlmAgent(
+    name="GuardedAgent",
+    before_model_callback=content_guardrail
+)
+```
+
+#### after_model_callback
+
+```python
+def post_process_response(ctx: CallbackContext, response: LlmResponse) -> LlmResponse | None:
+    """LLM 응답 후처리"""
+    # 응답 로깅
+    print(f"LLM Response: {response.content}")
+
+    # 응답 수정 (필요시)
+    # return modified_response
+
+    return None  # 원본 응답 유지
+
+agent = LlmAgent(
+    name="LoggingAgent",
+    after_model_callback=post_process_response
+)
+```
+
+#### before_tool_callback / after_tool_callback
+
+```python
+def tool_guardrail(ctx: ToolContext, tool_name: str, args: dict) -> dict | None:
+    """도구 실행 전 검사"""
+    if tool_name == "delete_file" and not ctx.state.get("admin"):
+        return {"error": "권한이 없습니다."}  # 도구 실행 건너뜀
+    return None
+
+def log_tool_result(ctx: ToolContext, tool_name: str, result: dict) -> dict | None:
+    """도구 실행 후 로깅"""
+    print(f"Tool {tool_name} returned: {result}")
+    return None  # 결과 유지
+
+agent = LlmAgent(
+    name="ToolAuditAgent",
+    before_tool_callback=tool_guardrail,
+    after_tool_callback=log_tool_result
+)
+```
+
+### 콜백 반환값의 의미
+
+| 콜백         | 반환값        | 효과                                 |
+| ------------ | ------------- | ------------------------------------ |
+| before_agent | `None`        | 에이전트 정상 실행                   |
+| before_agent | `Content`     | 에이전트 건너뜀, 반환된 Content 사용 |
+| before_model | `None`        | LLM 정상 호출                        |
+| before_model | `LlmResponse` | LLM 호출 건너뜀, 반환된 응답 사용    |
+| before_tool  | `None`        | 도구 정상 실행                       |
+| before_tool  | `dict`        | 도구 실행 건너뜀, 반환된 결과 사용   |
+
+---
+
+## 9. Tools (도구)
+
+### 개념
+
+**Tool**은 에이전트에게 **외부 기능을 제공**하는 컴포넌트입니다.
+API 호출, 계산, 데이터베이스 조회 등을 수행할 수 있습니다.
+
+### Tool 유형
+
+#### 1. FunctionTool (함수 도구)
+
+Python 함수를 도구로 변환합니다.
+
+```python
+from google.adk.tools import FunctionTool
+
+def get_weather(city: str, unit: str = "celsius") -> dict:
+    """
+    특정 도시의 날씨를 조회합니다.
+
+    Args:
+        city: 조회할 도시 이름
+        unit: 온도 단위 (celsius 또는 fahrenheit)
+
+    Returns:
+        날씨 정보 딕셔너리
+    """
+    # 실제 API 호출 또는 시뮬레이션
+    return {"city": city, "temp": 20, "unit": unit}
+
+# 함수를 도구로 변환
+weather_tool = FunctionTool(func=get_weather)
+
+# 에이전트에 도구 추가
+agent = LlmAgent(
+    name="WeatherAgent",
+    tools=[weather_tool]
+)
+```
+
+#### 2. AgentTool (에이전트를 도구로)
+
+다른 에이전트를 도구처럼 호출할 수 있습니다.
+
+```python
+from google.adk.tools import agent_tool
+
+# 전문 에이전트 정의
+translator = LlmAgent(
+    name="Translator",
+    description="텍스트를 번역합니다."
+)
+
+# 에이전트를 도구로 래핑
+translator_tool = agent_tool.AgentTool(agent=translator)
+
+# 다른 에이전트에서 도구로 사용
+main_agent = LlmAgent(
+    name="MainAgent",
+    tools=[translator_tool]
+)
+```
+
+### ToolContext 활용
+
+도구 함수 내에서 Context에 접근하여 다양한 기능을 사용할 수 있습니다.
+
+```python
+from google.adk.tools import ToolContext
+
+def advanced_tool(context: ToolContext, query: str) -> dict:
+    # 1. 상태 읽기/쓰기
+    context.state["last_query"] = query
+    previous = context.state.get("history", [])
+
+    # 2. 메모리 검색
+    memory_results = await context.search_memory(query)
+
+    # 3. 아티팩트 목록 조회
+    artifacts = context.list_artifacts()
+
+    # 4. 인증 처리
+    if needs_auth:
+        cred = await context.get_auth_response(oauth_config)
+
+    return {"result": "processed"}
+```
+
+### 도구 실행 흐름
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│                      도구 실행 흐름                           │
+└──────────────────────────────────────────────────────────────┘
+
+1. LLM이 도구 호출 결정
+   LLM Response: FunctionCall(name="get_weather", args={"city": "서울"})
+
+2. ADK가 도구 찾기
+   tools 목록에서 "get_weather" 찾음
+
+3. before_tool_callback 실행 (있으면)
+   가드레일, 로깅 등
+
+4. 도구 함수 실행
+   result = get_weather(city="서울")
+
+5. after_tool_callback 실행 (있으면)
+   결과 후처리, 로깅 등
+
+6. FunctionResponse 이벤트 생성
+   Event(content=FunctionResponse(name="get_weather", response=result))
+
+7. LLM에게 결과 전달
+   LLM이 결과를 보고 다음 응답 생성
+```
+
+---
+
+## 10. 핵심 개념 간의 관계
+
+### 전체 관계도
+
+```
+┌────────────────────────���────────────────────────────────────────────────┐
+│                          ADK 핵심 개념 관계도                            │
+└─────────────────────────────────────────────────────────────────────────┘
+
+                    ┌─────────────────────┐
+                    │      Runner         │
+                    │   (오케스트레이터)   │
+                    └─────────────────────┘
+                              │
+              ┌───────────────┼───────────────┐
+              ▼               ▼               ▼
+     ┌─────────────┐  ┌─────────────┐  ┌─────────────┐
+     │ SessionSvc  │  │  MemorySvc  │  │ ArtifactSvc │
+     └─────────────┘  └─────────────┘  └─────────────┘
+              │               │
+              ▼               │
+     ┌─────────────────┐      │
+     │    Session      │      │
+     │  ┌───────────┐  │      │
+     │  │   State   │◀─┼──────┼──── 에이전트가 읽고/씀
+     │  └───────────┘  │      │
+     │  ┌───────────┐  │      │
+     │  │  Events   │  │      │
+     │  └───────────┘  │      │
+     └─────────────────┘      │
+              │               │
+              ▼               ▼
+     ┌─────────────────────────────────────────┐
+     │          InvocationContext              │
+     │  ┌─────────────────────────────────┐   │
+     │  │ session, state, services, agent │   │
+     │  └─────────────────────────────────┘   │
+     └─────────────────────────────────────────┘
+                        │
+          ┌─────────────┼─────────────┐
+          ▼             ▼             ▼
+   ┌────────────┐ ┌──────────┐ ┌──────────┐
+   │ Callbacks  │ │  Agent   │ │  Tools   │
+   │            │ │          │ │          │
+   │ Callback   │ │          │ │  Tool    │
+   │ Context    │ │          │ │ Context  │
+   └────────────┘ └──────────┘ └──────────┘
+          │             │             │
+          └─────────────┼─────────────┘
+                        ▼
+                 ┌────────────┐
+                 │   Event    │
+                 │  ┌──────┐  │
+                 │  │Actions│ ──▶ state_delta
+                 │  └──────┘  │    escalate
+                 └────────────┘    transfer
+```
+
+### 데이터 흐름 요약
+
+```
+1. 사용자 입력
+   └──▶ Runner.run_async(message)
+
+2. 세션 준비
+   └──▶ SessionService.get_session() → Session
+
+3. 컨텍스트 생성
+   └──▶ InvocationContext(session, services, ...)
+
+4. 콜백 실행
+   └──▶ before_agent_callback(CallbackContext)
+
+5. 에이전트 실행
+   └──▶ Agent.run(InvocationContext)
+        │
+        ├──▶ before_model_callback
+        ├──▶ LLM 호출
+        ├──▶ after_model_callback
+        │
+        ├──▶ [도구 호출 시]
+        │    ├──▶ before_tool_callback
+        │    ├──▶ Tool 실행(ToolContext)
+        │    └──▶ after_tool_callback
+        │
+        └──▶ yield Event
+
+6. 이벤트 처리
+   └──▶ SessionService.append_event(event)
+        └──▶ state_delta 적용
+        └──▶ events 히스토리 추가
+
+7. 콜백 실행
+   └──▶ after_agent_callback(CallbackContext)
+
+8. 결과 반환
+   └──▶ yield event to caller
+```
+
+### 핵심 포인트 정리
+
+| 개념         | 역할           | 비유                |
+| ------------ | -------------- | ------------------- |
+| **Session**  | 대화 컨테이너  | 전화 통화 한 건     |
+| **State**    | 대화 중 메모   | 메모장/스크래치패드 |
+| **Event**    | 활동 기록 단위 | 대화 기록의 한 줄   |
+| **Context**  | 실행 정보 묶음 | 업무 문맥/배경 정보 |
+| **Runner**   | 실행 조율자    | 지휘자              |
+| **Memory**   | 장기 기억      | 도서관 아카이브     |
+| **Callback** | 실행 중 개입점 | 체크포인트/관문     |
+| **Tool**     | 외부 기능      | 도구 상자           |
+
+---
+
+## 부록: 자주 묻는 질문 (FAQ)
+
+### Q1: State와 Memory의 차이는?
+
+- **State**: 현재 세션 내에서만 유효, 키-값 직접 접근
+- **Memory**: 여러 세션에 걸쳐 유지, 검색 쿼리로 접근
+
+### Q2: output_key가 없으면 어떻게 되나요?
+
+에이전트의 응답이 state에 자동 저장되지 않습니다.
+다음 에이전트에서 이전 응답을 참조하려면 output_key를 설정하거나,
+직접 콜백/도구에서 state를 업데이트해야 합니다.
+
+### Q3: InMemorySessionService는 프로덕션에서 쓸 수 있나요?
+
+권장하지 않습니다. 앱 재시작 시 모든 데이터가 손실됩니다.
+프로덕션에서는 Database-backed 또는 Cloud-based 구현체를 사용하세요.
+
+### Q4: 콜백에서 Content를 반환하면 무슨 일이 일어나나요?
+
+before_agent_callback에서 Content를 반환하면 에이전트 실행이 건너뛰어지고,
+반환된 Content가 에이전트의 응답으로 사용됩니다.
+이를 통해 조건부 단축(short-circuit)을 구현할 수 있습니다.
+
+### Q5: LoopAgent의 escalate는 어떻게 동작하나요?
+
+sub_agent가 Event를 생성할 때 `actions=EventActions(escalate=True)`를 설정하면,
+LoopAgent가 이를 감지하고 즉시 루프를 종료합니다.
+max_iterations에 도달하기 전에 조건부로 종료할 때 사용합니다.
+
+---
+
+## 참고 자료
+
+- [ADK 공식 문서](https://google.github.io/adk-docs/)
+- [ADK GitHub (Python)](https://github.com/google/adk-python)
+- [Vertex AI Agent Engine](https://cloud.google.com/vertex-ai/docs/agents)

docs/agent-architecture.md

@@ -0,0 +1,108 @@
+# Agent Architecture
+
+## 개요
+
+현재 메구밍 챗봇은 아래 흐름으로 동작합니다.
+
+1. `bootstrap.py`에서 환경변수와 런타임 데이터 경로를 준비
+2. `retrieval.py`에서 FAISS 인덱스와 메타데이터를 로드
+3. `agent.py`에서 Google ADK `LlmAgent`와 retrieval tool 구성
+4. `chat.py`에서 세션 실행과 대화 요약 관리
+5. `app_gradio.py`에서 PC용 채팅 UI 제공
+
+## 파일별 역할
+
+### `megumin_agent/bootstrap.py`
+
+- `.env` 로드
+- 로컬 `adk-python/src` 경로 등록
+- Hugging Face dataset repo에서 데이터 파일 다운로드
+- 다운로드 실패 시 로컬 `data/processed`를 fallback으로 사용
+
+다운로드 대상:
+
+- `megumin_qa_dataset.json`
+- `megumin_questions.faiss`
+- `megumin_question_answer.faiss`
+- `megumin_questions_meta.json`
+- `namuwiki_qa.json`
+- `namuwiki_questions.faiss`
+- `namuwiki_question_answer.faiss`
+- `namuwiki_questions_meta.json`
+
+### `megumin_agent/retrieval.py`
+
+- QA JSON 레코드 로드
+- Gemini 임베딩 기반 FAISS 검색
+- question-only 인덱스와 question+answer 인덱스를 둘 다 조회
+- 두 검색 결과를 합쳐 점수가 높은 후보 top-k를 반환
+
+데이터 계층:
+
+- 페르소나 계층: `megumin_qa_dataset.json`
+- 사실 계층: `namuwiki_qa.json`
+
+### `megumin_agent/agent.py`
+
+- 메구밍 페르소나 프롬프트 정의
+- `retrieve_megumin_examples` tool 정의
+- 페르소나용 top-3, 사실용 top-3를 각각 수집
+- ADK callback으로 대화 요약, 최근 질의, RAG 흔적을 state에 기록
+
+tool 반환 핵심:
+
+- `persona_matches`
+- `fact_matches`
+- `style_notes`
+- `fact_notes`
+
+### `megumin_agent/chat.py`
+
+- `Runner`와 `InMemorySessionService` 생성
+- 질문 1회 실행 단위인 `chat_once()` 제공
+- 최근 6턴을 남기고, 그 이전 대화는 `conversation_summary`로 압축
+
+### `app_gradio.py`
+
+- PC용 3패널 레이아웃 제공
+- 왼쪽: 메구밍 프로필, 페르소나 설명, 예시 질문
+- 가운데: 반투명 채팅 패널
+- 오른쪽: 메구밍 비주얼 패널
+- 배경에는 흐릿한 메구밍 일러스트와 폭렬 분위기 레이어를 배치
+
+### `app.py`
+
+- Hugging Face Spaces 진입점
+- `app_gradio.py`의 `demo`를 그대로 로드
+
+## 대화 흐름
+
+사용자 입력이 들어오면:
+
+1. `app_gradio.py`가 `chat_once()` 호출
+2. `chat.py`가 ADK Runner로 세션 실행
+3. `agent.py`의 tool이 retrieval 수행
+4. `retrieval.py`가
+   - 페르소나 데이터 top-3
+   - 사실 데이터 top-3
+   를 각각 검색
+5. Agent가 두 종류의 근거를 함께 참고해 메구밍 말투로 답변
+6. 세션 종료 후 오래된 이벤트를 요약 상태로 압축
+
+## 세션과 메모리
+
+현재 저장 방식은 `InMemorySessionService`입니다.
+
+- 서버 프로세스가 살아 있는 동안만 유지
+- 재시작 시 초기화
+- 최근 6턴만 유지
+- 오래된 내용은 짧은 summary로 state에 남김
+
+## UI 목적
+
+현재 UI는 모바일 전용이 아니라 PC 화면 기준입니다.
+
+- 캐릭터와 실제로 마주 보고 대화하는 느낌
+- 반투명 유리 패널 중심 구성
+- 메구밍 세계관과 챗봇 사용법을 한 화면에서 안내
+

docs/data-collection-spec.md

@@ -0,0 +1,92 @@
+# Data Collection Spec
+
+## 개요
+
+이 프로젝트는 메구밍 챗봇의 RAG 자원을 두 계층으로 관리한다.
+
+- 스타일/페르소나용 데이터
+  - 예: `megumin_qa_dataset.json`
+- 사실/설정용 데이터
+  - 예: `namuwiki_qa.json`
+
+사실/설정용 데이터는 나무위키 문서를 선별 수집해 QA JSON으로 변환하고, 이후 FAISS 인덱스로 검색한다.
+
+## 수집 대상
+
+나무위키 문서는 별칭으로 입력할 수 있으며, 실제 검색 시에는 정식 문서명으로 변환한다.
+
+예:
+
+- `카즈마` -> `사토 카즈마`
+- `아쿠아` -> `아쿠아(이 멋진 세계에 축복을!)`
+- `다크니스` -> `다크니스(이 멋진 세계에 축복을!)`
+- `세계관` -> `이 멋진 세계에 축복을!/설정`
+- `지역` -> `이 멋진 세계에 축복을!/지역`
+
+저장 시 `source.title`은 짧은 표시명으로 정규화한다.
+
+예:
+
+- `사토 카즈마` -> `카즈마`
+- `아쿠아(이 멋진 세계에 축복을!)` -> `아쿠아`
+- `이 멋진 세계에 축복을!/설정` -> `세계관`
+- `이 멋진 세계에 축복을!/지역` -> `세계관`
+
+## 변환 규칙
+
+- 출력 포맷은 QA JSON 유지
+- `question`은 사용자 질문형이 아니라 검색용 소제목 요약
+- `answer`는 중립 요약형 본문
+- 표, 이미지, 불필요한 장식 요소는 제외
+- chunk 길이는 약 200자 내외
+- chunk overlap은 1~2문장
+
+## 저장 파일
+
+- `data/processed/namuwiki_qa.json`
+  - 나무위키 기반 통합 QA 데이터
+- `data/processed/megumin_qa_dataset.json`
+  - 기존 메구밍 스타일/페르소나 QA 데이터
+- `data/processed/megumin_questions.faiss`
+  - 스타일 데이터 question 인덱스
+- `data/processed/megumin_question_answer.faiss`
+  - 스타일 데이터 question+answer 인덱스
+- `data/processed/megumin_questions_meta.json`
+  - 스타일 데이터 인덱스와 원문 레코드 매핑
+- `data/processed/namuwiki_questions.faiss`
+  - 나무위키 데이터 question 인덱스
+- `data/processed/namuwiki_question_answer.faiss`
+  - 나무위키 데이터 question+answer 인덱스
+- `data/processed/namuwiki_questions_meta.json`
+  - 나무위키 데이터 인덱스와 원문 레코드 매핑
+
+## 병합 저장 규칙
+
+`crawl_namuwiki_to_qa.py`는 출력 파일이 이미 존재하면 기존 `items`와 새 결과를 병합한다.
+
+- 우선 중복 기준: `chunk_id`
+- 보조 기준: `source.url + chunk_index + question`
+
+병합 후 식별자는 다음 규칙으로 정규화한다.
+
+- `chunk_id`
+  - title별 연속 번호 유지
+  - 예: `메구밍_0000`, `카즈마_0185`
+- `chunk_index`
+  - 전체 파일 기준 연속 번호
+  - 예: `0`, `135`, `320`
+
+## 관련 스크립트
+
+- `scripts/crawl_namuwiki_to_qa.py`
+  - 나무위키 문서를 QA JSON으로 변환
+- `scripts/build_faiss_index.py`
+  - 스타일/나무위키 데이터 각각에 대해 question 인덱스와 question+answer 인덱스를 생성
+- `scripts/expand_persona_from_namuwiki.py`
+  - 사실/설정 QA를 메구밍 스타일 QA 초안으로 확장
+
+## 운영 메모
+
+- 나무위키 기반 데이터는 사실/설정 보강용이다.
+- 기존 `megumin_qa_dataset.json`은 메구밍 말투와 감정선 유지에 더 중요하다.
+- 최종 Agent는 두 데이터원을 함께 검색해 사용한다.