docs/Google-ADK.md

Google ADK 핵심 개념 완전 가이드

이 문서는 Google Agent Development Kit (ADK)의 핵심 개념들을 체계적으로 설명합니다. 샘플 코드에서 사용된 모든 중요 요소들을 이해할 수 있도록 구성했습니다.

---

📚 목차

1. 전체 아키텍처 개요
2. Session (세션)
3. State (상태)
4. Event (이벤트)
5. Context (컨텍스트)
6. Runner (러너)
7. Memory (메모리)
8. Callbacks (콜백)
9. Tools (도구)
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은 사용자와 에이전트 간의 단일 대화 스레드를 나타냅니다. 전화 통화에 비유하면, 하나의 통화가 하나의 세션입니다.

주요 속성

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

세션의 생명주기를 관리하는 서비스입니다.

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에서만 유지, 호출 종료 시 삭제

# 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)

from google.adk.agents import LlmAgent

# 에이전트 응답이 자동으로 state['analysis_result']에 저장됨
agent = LlmAgent(
    name="Analyzer",
    instruction="데이터를 분석하세요.",
    output_key="analysis_result"  # ← 자동 저장
)

2. Instruction 템플릿에서 읽기

agent = LlmAgent(
    name="Reporter",
    instruction="""
    이전 분석 결과: {analysis_result}
    위 결과를 바탕으로 보고서를 작성하세요.
    """  # ← {key} 형식으로 자동 주입
)

3. Tool/Callback에서 직접 접근

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 수정 시 주의사항

# ❌ 잘못된 방법: 세션 객체 직접 수정
session = await session_service.get_session(...)
session.state["key"] = "value"  # 추적되지 않음!

# ✅ 올바른 방법: Context를 통해 수정
def my_callback(context: CallbackContext):
    context.state["key"] = "value"  # 자동 추적됨

---

4. Event (이벤트)

개념

Event는 세션 내에서 발생하는 모든 활동의 기록 단위입니다. 사용자 메시지, 에이전트 응답, 도구 호출, 상태 변경 등 모든 것이 이벤트입니다.

Event 구조

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)**를 정의합니다:

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 (호출 컨텍스트)

가장 상위 레벨의 컨텍스트로, 하나의 사용자 요청 처리 전체를 관장합니다.

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의 서브셋입니다.

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) 함수에서 사용되며, 도구 실행에 필요한 추가 기능을 제공합니다.

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는 에이전트 실행의 중앙 오케스트레이터입니다. 사용자 입력을 받아 에이전트를 실행하고, 이벤트를 처리하며, 서비스들을 조율합니다.

기본 사용법

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,  # 옵션
)

에이전트 실행

# 비동기 실행 (일반적인 방법)
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 사용

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가 검색 결과를 참고하여 응답

에이전트에서 메모리 사용

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

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 (가드레일)

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

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

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 함수를 도구로 변환합니다.

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 (에이전트를 도구로)

다른 에이전트를 도구처럼 호출할 수 있습니다.

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에 접근하여 다양한 기능을 사용할 수 있습니다.

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 공식 문서
• ADK GitHub (Python)
• Vertex AI Agent Engine