ADK - Runtime

✅ ADK Runtime 요약

1. ADK Runtime이란?

• ADK Runtime은 에이전트 애플리케이션의 실행 엔진입니다.
• 사용자가 정의한 에이전트, 툴, 콜백을 실행하며, LLM 호출, 상태 변화, 외부 서비스 연동 등 전체 흐름을 관리합니다.

---

2. 핵심 원리: 이벤트 루프 (Event Loop)

ADK Runtime의 중심은 이벤트 기반 루프입니다.

🚀 흐름 요약:

1. Runner가 사용자 입력을 받고 세션 기록에 추가
2. Agent.run_async() 호출하여 실행 시작
3. Agent는 Event를 yield하고 일시 중지
4. Runner는 Event를 처리하고 상태를 커밋
5. 처리 후 Agent 실행을 재개 → 다음 Event 생성
6. Agent가 더 이상 Event를 내보내지 않으면 실행 종료

---

3. 주요 구성 요소 및 역할

구성 요소역할 및 설명

Runner	전체 흐름을 조율하는 오케스트레이터. 세션 상태 기록, 이벤트 처리, 툴 실행, UI 응답 전송 등 담당
Agent	핵심 로직 수행자. 사용자 입력을 해석하고 필요한 툴 호출, 상태 변경 등을 판단
Tool	외부 작업 수행자. API 호출, 계산 작업 등 도구 역할
Callback	실행 흐름의 특정 지점에 삽입되는 사용자 정의 함수
Event	Runner ↔ Logic 사이에서 교환되는 메시지 객체 (내용 + 상태 변화 포함)
Services	세션/아티팩트/메모리 관리 등 지속적 리소스 관리
Session	하나의 사용자 대화 상태 및 이벤트 히스토리를 저장
Invocation	단일 사용자 쿼리에 대한 전체 처리 과정을 의미 (LLM 호출, 툴 실행 등 포함)

 

---

4. 이벤트 루프 실행 흐름 예시

 

---

5. 중요한 런타임 동작 특징

🧠 상태 커밋 타이밍

• 상태 변경은 yield된 Event의 state_delta가 Runner에 의해 처리된 후 비로소 커밋됨
• yield 이후에만 안정적으로 커밋된 상태에 접근 가능

🧪 Dirty Read (비공식 상태 읽기)

• yield 전에도 변경된 상태를 읽을 수 있음 (예: 같은 인보케이션 내의 툴에서 접근 가능)
• 단, 인보케이션이 실패하면 해당 상태는 유실될 수 있으므로 주의 필요

🔄 Streaming Output 처리

• LLM이 Token 단위로 응답할 경우, partial=True인 Event 여러 개 발생
• 최종 Event만이 state/artifact를 커밋함
• UI는 빠르게 응답을 표시할 수 있고, 상태 변경은 마지막에만 반영

⚙️ 비동기 처리

• ADK는 비동기 기반 (Python: asyncio, Java: RxJava)
• run_async()가 기본 실행 방식
• 동기 방식 run()도 존재하지만 내부적으로 run_async()를 호출

---

6. 요약: ADK Runtime의 핵심 구조

---

이 구조는 에이전트 로직과 시스템 상태 변경을 안정적으로 연결해주며, 복잡한 대화 흐름이나 멀티 툴 호출도 예측 가능한 방식으로 처리할 수 있도록 합니다.