2026년 업데이트 요약 (v2 — Python ADK 2.0 마이그레이션)

이번 업데이트된 에디션은 초기 출시 버전 대비 몇 가지 주요 아키텍처 개선 사항, 프로덕션 강화(production hardening), 그리고 종속성(dependency) 업그레이드를 포함하고 있습니다:

• Python ADK 2.0 코어 업그레이드: google-adk>=2.0.0 (google.adk, adk.dev/2.0/에서 GA 출시됨)로 업그레이드되었으며, 통합된 도구 컨텍스트 관리, 세션 상태 격리(session state isolation), 그리고 콜백 실행 파이프라인을 위한 google.adk.Context를 도입했습니다.
• Google Cloud AI Platform 통합: Vertex AI를 위한 네이티브 인증 자동 감지(GOOGLE_GENAI_USE_VERTEXAI=TRUE) 및 Google AI Studio Gemini API Key 폴백(fallback) 기능을 지원합니다.
• Python 툴체인 및 환경: requirements.txt를 통한 구조화된 종속성 관리를 지원하며, 최신 Python 런타임(3.10+에서 3.13까지)을 지원합니다.
• 코드 및 선언적 에이전트 지원: Python 코드로 정의된 에이전트(root_agent를 노출하는 agent.py)와 YAML로 구성된 에이전트(root_agent.yaml)를 모두 네이티브로 지원합니다.
• 통합 실행 컨텍스트 (Unified Execution Context): 도구(Tools)들이 세션 메타데이터, 사용자 식별 정보, 실행 상태를 검사할 수 있도록 tool_context: Optional[Context] = None을 허용합니다.
• 통합 CLI 툴링: 표준 ADK 2.x CLI 명령어(adk run, adk web, adk api_server, adk deploy cloud_run)와 완벽하게 호환됩니다.
• Web UI 및 원격 VM 서버: 로컬 개발(adk web)과 원격 클라우드 인스턴스(adk web --host=0.0.0.0) 모두를 위한 내장 개발자 Web UI 지원을 제공합니다.
• FastAPI API 서버 모드: 마이크로서비스 아키텍처(microservice architectures)에 에이전트 엔드포인트를 임베딩할 수 있도록 adk api_server를 통한 서버 모드를 제공합니다.
• 서버리스 Cloud Run 배포: 내장 Web UI 옵션(--with_ui)을 특징으로 하는 adk deploy cloud_run을 통해 간소화된 Cloud Run 배포를 지원합니다.

ADK 1.x에서 ADK 2.x로의 주요 마이그레이션 변경 사항 (Python)

기존 코드베이스를 ADK 1.x에서 ADK 2.x로 마이그레이션하는 경우, 몇 가지 주요 API 변화와 아키텍처 추가 사항이 도입되었습니다:

1.x -> 2.x 변경 사항 상세 분석:

1. 임포트 네임스페이스 표준화 (Import Namespace Standardization)

ADK 1.x에서는 임포트(import)가 레거시 모듈이나 최상위 adk에 의존했습니다. ADK 2.x에서는 모든 공식 컴포넌트가 google.adk 네임스페이스 아래에 깔끔하게 위치합니다:

# ADK 1.x (Legacy)
# from adk.agents import Agent

...

2. 통합 도구 실행 컨텍스트 (Context, Unified Tool Execution Context)

ADK 1.x에서 도구(tools)는 LLM에서 추출된 함수 인자(arguments)만을 전달받았기 때문에, 세션 격리(session isolation)나 상태 수정(state modification)이 까다로웠습니다. ADK 2.x에서 도구는 선택적 파라미터인 tool_context: Optional[Context] = None을 허용합니다:

# ADK 2.x 도구 시그니처 (Tool Signature)
def my_tool(param1: str, tool_context: Optional[Context] = None) -> Dict[str, Any]:
    # 세션 상태, 실행 메타데이터 또는 사용자 식별 정보에 접근
...

3. 그래프 및 워크플로우 지원 (Workflow, Graph & Workflow Support)

ADK 2.x는 표준 에이전트와 함께 네이티브 Workflow 그래프 정의를 도입했습니다. 개발자는 다단계 에이전트 파이프라인(multi-step agent pipelines), 병렬 실행 경로(parallel execution paths), 상태 변환 노드(state transformation nodes)를 위한 유향 비순환 그래프 (DAG, Directed Acyclic Graphs)를 구축할 수 있습니다.

4. 선언적 YAML 에이전트 사양 (Declarative YAML Agent Specifications)

ADK 2.x는 프롬프트 엔지니어(prompt engineers)와 시스템 설정자(system configurators)를 위해 코드 작성이 필요 없는 선언적 YAML 정의(root_agent.yaml)를 추가하였으며, 이는 프로그래밍 방식의 Python 에이전트(agent.py)와 병행하여 지원됩니다.

5. 통합 adk CLI 툴링 (Unified adk CLI Tooling)

ADK 1.x는 커스텀 스크립트나 모듈 실행 명령에 의존했습니다. ADK 2.x는 표준화된 작업을 지원하는 통합 adk 바이너리를 도입했습니다:

• adk run <agent_path>: 터미널 실행 모드
• adk web: 8000번 포트의 로컬 그래픽 채팅 UI
• adk web --host=0.0.0.0: 클라우드 VM / 원격 바인딩 모드
• adk api_server <agent_path>: FastAPI 마이크로서비스 서버 모드
• adk deploy cloud_run: 프로덕션 Cloud Run 컨테이너 배포

6. 비동기 세션 프로바이더 (Asynchronous Session Providers)

ADK 2.x는 SQLite (sqlite://), PostgreSQL (asyncpg), 그리고 인메모리 저장소 (memory://)와 같은 지속성 백엔드 드라이버 (persistent backend drivers)를 지원하는 비동기 세션 어댑터 (async session adapters) 기능을 제공합니다.

7. 프레임워크 관리형 재시도 및 Human-in-the-Loop (HITL)

ADK 2.x는 RetryConfig를 통한 자동 예외 인식 재시도 (exception-aware retries) 기능과 Human-in-the-Loop (HITL) 도구 권한 부여 흐름을 위한 일급 일시 중지/재개 (pause/resume) 메커니즘을 제공합니다.

Python ADK를 활용한 네이티브 Python 에이전트 개발

이 튜토리얼은 Python과 공식 Google Agent Development Kit (ADK) (google-adk)를 사용하여 네이티브 AI 에이전트를 구축, 실행 및 배포하는 방법에 대한 종합적인 가이드를 제공합니다.

Python ADK 2.x란 무엇인가?

Python Agent Development Kit (ADK 2.0) (google-adk>=2.0.0)는 Gemini 모델을 기반으로 하는 지능형 AI 에이전트를 설계, 테스트 및 배포하기 위해 Google에서 제작한 코드 우선 (code-first) 프레임워크입니다.

주요 특징:

• 모델 불가지론적 (Model-Agnostic) 및 클라우드 네이티브 (Cloud-Native): Google Cloud Vertex AI 또는 Google AI Studio의 Gemini 모델에 최적화되어 있습니다.
• 통합 컨텍스트 및 도구 상태 (Unified Context & Tool State): google.adk.Context를 사용하여 통합된 세션 상태, 자격 증명, 그리고 Human-in-the-Loop (HITL) 컨텍스트를 도구에 전달합니다.
• 그래프 및 워크플로우 지원: google.adk 내에서 DAG 실행 및 Workflow 그래프를 네이티브로 지원합니다.
• 유연한 선언적 및 코드 패러다임: Python (agent.py)에서 프로그래밍 방식으로 에이전트를 정의하거나, YAML (root_agent.yaml)을 통해 선언적으로 정의할 수 있습니다.
• 내장 개발자 CLI 및 Web UI: 대화형 디버깅, 웹 채팅 인터페이스, API 서버를 즉시 사용할 수 있도록 제공합니다.

공식 저장소 및 문서:

• ADK 문서 및 GA 포털: https://adk.dev/2.0/
• ADK Python 1.x에서 2.x로의 마이그레이션 가이드: https://adk.dev/2.0/#adk-python-1x-compatibility
• ADK Python GitHub 저장소: https://github.com/google/adk-python

주요 의존성 및 디렉토리 구조

requirements.txt

스타터 스택 (starter stack)은 Python 3.10+ 및 최신 google-adk 릴리스를 기반으로 합니다:

# Dev environment
pip
autopep8
...

Project Layout (프로젝트 레이아웃)

adk-hello-world/
├── Makefile                                                    # run, test, lint, web, deploy를 위한 Make 타겟
├── README.md                                                   # 프로젝트 문서
...

Checking the Developer Environment (개발 환경 확인)

저장소를 클론(Clone)하고 환경 자격 증명(credentials)을 설정하세요:

git clone https://github.com/xbill9/adk-hello-world
cd adk-hello-world

1. Project & Credential Initialization (프로젝트 및 자격 증명 초기화)

init.sh를 실행하여 Google Cloud 프로젝트 ID와 Gemini API Key를 구성하세요:

$ ./init.sh
--- Setting Google Cloud Project ID File ---
Please enter your Google Cloud project ID: my-gcp-project-id
...

2. Loading Shell Environment Variables (셸 환경 변수 로드)

set_env.sh를 소스(source)하여 활성 환경 설정을 로드하세요:

$ source ./set_env.sh
--- Setting Google Cloud Environment Variables ---
Checking gcloud authentication status...
...

Building Python Agents with ADK 2.x (ADK 2.x를 활용한 Python 에이전트 구축)

1. Code-Defined Agent (코드로 정의된 에이전트, agent.py)

ADK 2.x에서 Python 함수 도구(function tools)는 함수의 인자(arguments)와 선택 사항인 tool_context: Optional[Context] = None을 전달받습니다. ADK는 Gemini를 위한 도구의 OpenAPI 스키마(schema)를 생성하기 위해 docstring과 타입 어노테이션(type annotations)을 자동으로 검사합니다.

다음은 src/agents/adk_hello_world/agent.py 파일의 내용입니다:

import datetime
from typing import Any
from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
...

2. Declarative YAML Agent (선언적 YAML 에이전트, root_agent.yaml)

ADK 2.x는 src/agents/Agent1/root_agent.yaml과 같이 YAML을 이용한 선언적 에이전트 정의(declarative agent definitions)도 지원합니다:

name: Agent1
model: gemini-2.5-flash
agent_class: LlmAgent
...

Running the ADK Agent Locally (ADK 에이전트 로컬 실행)

Option A: Interactive Terminal CLI (대화형 터미널 CLI, cli.sh / run.sh)

cli.sh 또는 make run을 사용하여 코드로 정의된 에이전트와 함께 대화형 터미널 세션을 시작하세요:

$ source ./cli.sh
/home/user/adk-hello-world/src/agents/adk_hello_world
adk run .
...

YAML로 설정된 에이전트 Agent1을 실행하려면:

$ source ./Agent1_cli.sh
/home/user/adk-hello-world/src/agents/Agent1
adk run .

옵션 B: 로컬 웹 UI (web.sh / webvm.sh)

내장된 시각적 웹 인터페이스 (visual web interface)를 실행합니다:

$ source ./web.sh
/home/user/adk-hello-world/src/agents
adk web

브라우저에서 http://localhost:8000을 열어 그래픽 채팅 UI (graphical chat UI)에 접속하고, 도구 호출 페이로드 (tool call payloads)를 검사하며, 실시간 에이전트 실행 트레이스 (agent execution traces)를 확인할 수 있습니다.

원격 클라우드 VM (Cloud VMs) 또는 헤드리스 설정 (headless setups)의 경우, webvm.sh를 사용하여 모든 네트워크 인터페이스에 바인딩하십시오:

$ source ./webvm.sh
Running ADK from Cloud VM
/home/user/adk-hello-world/src/agents
...

옵션 C: FastAPI API 서버 (api_server.sh)

에이전트를 HTTP를 통해 노출하기 위한 API 서버 엔드포인트 (API server endpoint)를 시작합니다:

$ source ./api_server.sh
setting API Server Mode
/home/user/adk-hello-world/src/agents/adk_hello_world
...

Google Cloud Run 배포 (cloudrun.sh)

cloudrun.sh를 사용하여 단 한 번의 명령으로 Python ADK 에이전트를 Google Cloud Run에 직접 배포하십시오:

$ source ./cloudrun.sh
adk deploy cloud_run \
  --project=my-gcp-project-id \
...

CLI는 컨테이너 이미지 (container image)를 빌드하고, 웹 UI가 활성화된 (--with_ui) Cloud Run 상의 완전 관리형 서버리스 엔드포인트 (fully-managed serverless endpoint)를 프로비저닝 (provisions)합니다.

요약 및 다음 단계

이번 업데이트된 2026년 에디션에서는:

1. 에이전트 정의를 **Python 3.10+**에서 실행되는 **Python ADK 2.x (google-adk>=2.0.0)**로 마이그레이션 (migrated)했습니다.
2. 통합된 세션 상태 (session state) 및 실행 파이프라인 (execution pipelines)을 위해 **google.adk.Context**를 활용하도록 커스텀 도구 (custom tools)를 업데이트했습니다.
3. 임포트 네임스페이스 (import namespaces), 비동기 세션 저장소 (async session stores), Workflow DAG 실행, 선언적 YAML 정의 (declarative YAML definitions), 그리고 RetryConfig / HITL 도구를 포함한 1.x에서 2.x로의 주요 마이그레이션 (migration) 변경 사항을 강조했습니다.
4. **코드 정의 에이전트 (agent.py)**와 **선언적 YAML 에이전트 (root_agent.yaml)**를 모두 시연했습니다.
5. 터미널 CLI (adk run), Web UI (adk web), 그리고 **FastAPI 서버 (adk api_server)**를 통한 로컬 실행을 검증했습니다.
6. adk deploy cloud_run을 사용하여 Google Cloud Run으로의 서버리스 배포 (serverless deployment)를 간소화했습니다.

멀티 에이전트 오케스트레이션 (multi-agent orchestration), 커스텀 콜백 미들웨어 (custom callback middleware), 비동기 지속성 어댑터 (async persistence adapters)와 같은 더 고급 기능을 탐색하려면 공식 문서인 adk.dev/2.0/를 방문하세요.