google-adk 2.0 정식 버전 출시: 워크플로 런타임, 주요 변경 사항 및 마이그레이션 방법

google-adk 2.0의 변경 사항

1. 워크플로 런타임 (Workflow Runtime) (가장 중요한 변화)

2.0 버전의 가장 큰 구조적 변화는 새로운 그래프 기반 워크플로 실행 엔진(graph-based workflow execution engine)입니다. 1.x 버전에서는 에이전트 오케스트레이션(agent orchestration)이 주로 LLM 주도 방식이었습니다. 즉, 도구(tools)를 정의하면 모델이 이를 언제 사용할지 결정하도록 했습니다. 2.0에서는 LLM의 결정과 관계없이 실행되는 **결정론적 워크플로 (deterministic workflows)**를 정의할 수 있습니다.

from google.adk.workflow import Workflow, node

# @node 데코레이터를 사용하여 워크플로 노드 정의
...

이는 LangGraph의 StateGraph와 직접적으로 경쟁하는 기능입니다. 핵심적인 차이점은 ADK의 워크플로 런타임(Workflow Runtime)이 Google 네이티브이며, 내장된 A2A 프로토콜 지원을 갖추고 있고, 세션/상태 지속성 계층(session/state persistence layer)을 자동으로 처리한다는 점입니다.

지원되는 패턴:

순차적 파이프라인 (Sequential pipelines)
팬아웃 / 팬인 (Fan-out / fan-in, 병렬 서브에이전트 실행)
재시도 로직이 포함된 루프 (Loops with retry logic)
노드 출력에 기반한 동적 라우팅 (Dynamic routing based on node output)
인간 참여형 중단점 (Human-in-the-loop breakpoints)
중첩된 워크플로 (Nested workflows)

2. 이벤트 모델의 완전한 변화

1.x 버전에서는 에이전트 구성 요소 간에 도구 호출 결과(tool call results)와 프롬프트 컨텍스트(prompt context)를 통해 데이터가 전달되었습니다. 2.0에서는 **이벤트(Events)가 주요 데이터 기본 단위(primary data primitive)**입니다. 모든 것은 이벤트로 흐릅니다.

from google.adk.sessions import InMemorySessionService
from google.adk.sessions.state import State

...

이벤트 내의 state 필드는 워크플로 노드 전반에 걸쳐 자동으로 유지됩니다. 사용자가 수동으로 관리할 필요가 없습니다. 이것이 1.x의 세션 관리(session management)를 대체하는 메커니즘입니다.

3. 에이전트 간 위임을 위한 Task API

2.0은 멀티 에이전트 시스템을 위한 구조화된 Task API를 도입합니다. 에이전트가 우연히 다른 에이전트를 호출하게 되는 도구를 호출하는 대신, 이제 명시적인 작업 위임(task delegation) 의미론을 가집니다.

from google.adk.agents import LlmAgent
from google.adk.runners import Runner

...

이는 A2A 프로토콜과 통합되어, ADK 에이전트가 표준 A2A 와이어 포맷(wire format)을 통해 ADK가 아닌 에이전트에게 작업을 위임할 수 있습니다.

2.0에서 중단되는 사항 (Breaking Changes)

저장소 호환성 문제 (심각함)

ADK 2.0 스토리지를 ADK 1.x 데이터베이스와 함께 사용하지 마십시오. 이는 단순히 "문제가 발생할 수도 있음"을 알리는 경고가 아닙니다. Google은 이를 데이터 손실(data loss) 위험 영역으로 명시적으로 분류했습니다. 세션 스키마(session schema), 메모리 시스템(memory systems), 그리고 평가 데이터 저장소(evaluation data storage)는 버전 간에 모두 호환되지 않습니다.

만약 운영 환경(production)에서 1.x를 실행 중이라면, 다음 조치가 필요합니다:

모든 마이그레이션 작업을 시작하기 전에 세션 데이터를 백업하십시오.
1.x와 2.0 프로젝트를 완전히 분리된 스토리지 환경에서 실행하십시오.
제자리 업그레이드(in-place upgrade)가 아닌, 마이그레이션 기간(migration window)을 계획하십시오.

Agent API 변경 사항

최상위 에이전트 API(top-level agent API) 전반에 걸쳐 중단되는 변경 사항(breaking changes)이 있습니다. 1.x에서 에이전트는 도구 호출(tool calls)과 계층적 실행(hierarchical execution)을 중심으로 구조화되었습니다. 2.0에서는 전체 실행 모델이 명시적인 노드 정의(node definitions)와 이벤트 라우팅(event routing)을 갖춘 그래프 기반 워크플로(graph-based workflows)로 전환됩니다. 주요 API 변경 사항은 다음과 같습니다:

에이전트 초기화 (Agent initialization): 1.x의 Agent() 생성자 시그니처(constructor signature)가 변경되었습니다. 2.0 에이전트는 반드시 WorkflowRuntime 노드로 래핑(wrapped)되거나 배포되어야 합니다.
도구 정의 (Tool definition): 1.x의 @tool 데코레이터(decorators)는 @WorkflowNode 패턴으로 대체됩니다. 도구 호출(tool invocation)은 이제 LLM 주도가 아닌 이벤트 라우팅(event-routed) 방식으로 이루어집니다.
세션 상태 (Session state): .state 속성을 가진 1.x 세션 객체는 이벤트 기반 상태 지속성(Event-based state persistence)으로 교체되었습니다. 모든 상태는 반드시 Event.with_state()를 통해 흘러야 합니다.
응답 형식 (Response format): 1.x 에이전트 응답(직접 반환 또는 텍스트)은 이제 output 및 node_info 필드를 가진 구조화된 이벤트(Event) 객체를 반환합니다.

일반적인 패턴은 도구 중심 API를 사용하던 1.x 에이전트들을 이벤트 모델(Event model)과 WorkflowRuntime 그래프 오케스트레이션(graph orchestration)을 중심으로 재구조화해야 한다는 것입니다.

세션 스키마 (Session Schema)

세션 처리(Session handling)는 이벤트 모델을 중심으로 재구축되었습니다. 1.x에서 세션 상태를 직접 조작했던 모든 코드는 다시 작성해야 합니다.

Python 버전 요구 사항

2.0은 Python 3.11 이상을 요구합니다. 만약 3.10 이하 버전을 사용 중이라면, 2.0.0을 사용하기 전에 환경을 업그레이드해야 합니다.

보안 참고 사항: LiteLLM

2.0.0a2 버전은 LiteLLM 버전을 1.82.6으로 명시적으로 고정(pin)하며, 1.82.7 및 1.82.8 버전은 제외합니다. 해당 두 버전은 공급망 공격(supply chain incident)으로 인해 보안이 침해되었습니다. 만약 귀하의 1.x 설정에서 LiteLLM을 사용 중이고 고정된 버전을 확인하지 않았다면, ADK 마이그레이션 여부와 상관없이 지금 즉시 확인하십시오.

# 현재 LiteLLM 버전 확인
pip show litellm | grep Version

...

마이그레이션 전략 (Migration Strategy)

스프린트(sprint) 도중에 마이그레이션을 진행하지 마십시오. 다음과 같은 순서로 진행하는 것이 합리적입니다.

1단계: 1.x 사용 현황 감사 (Audit your 1.x footprint)

# 코드베이스 내의 모든 ADK 임포트(import) 검색
grep -r "from google.adk" . --include="*.py"
grep -r "import google.adk" . --include="*.py"

2단계: 스토리지 격리 (Isolate storage)
2.0 코드를 건드리기 전에 새로운 스토리지(storage)를 갖춘 별도의 개발 환경을 구축하십시오. 귀하의 1.x 세션 데이터와 2.0 개발 환경은 절대로 동일한 데이터베이스를 공유해서는 안 됩니다.

3단계: 2.0.0 안정화 버전 설치 (Install 2.0.0 stable)
이제 표준 pip install google-adk 명령어를 사용하면 기본적으로 2.0.0 버전이 설치됩니다. 명시적으로 버전을 고정하는 것은 선택 사항이지만 권장됩니다.

pip install "google-adk==2.0.0"

이미 2.0 알파(alpha) 버전을 사용 중이라면 다음과 같이 업데이트하십시오.

pip install --upgrade "google-adk==2.0.0"

4단계: 에이전트를 이벤트 모델로 이식 (Port your agents to the Event model)
워크플로(workflow)는 다음과 같습니다: 에이전트가 전달하는 상태(state)가 무엇인지 식별 → 이벤트 상태 필드(Event state fields)로 변환 → 툴 체인(tool chains) 대신 워크플로 런타임(WorkflowRuntime)을 사용하여 오케스트레이션(orchestration) 로직 재구축.

5단계: A2A 통합 업데이트 (Update your A2A integrations)
A2A 프로토콜을 사용 중이라면, 2.0의 태스크 API(Task API)가 1.x 방식보다 더 깔끔한 통합 경로를 제공합니다. 단순히 패치(patch)하기보다는 의도적으로 코드를 다시 작성할 가치가 있습니다.

마이그레이션 시점

2.0.0은 현재 안정화되었습니다 (2026년 5월 19일 출시). 마이그레이션 기간이 시작되었습니다. 1.x 기반의 프로덕션 워크로드(production workloads)에 대해 마이그레이션 준비 상태를 평가해야 합니다. 서두를 필요는 없지만, 이를 더 이상 "먼 미래의 일"로 취급해서는 안 됩니다. 대부분의 팀은 코드 복잡도와 스토리지 요구 사항에 따라 향후 2~4주 이내에 마이그레이션을 계획해야 합니다.

이것이 귀하의 툴링(Tooling)에 의미하는 바

Workflow Runtime (워크플로 런타임)의 도입으로 ADK 2.0은 Python 에이전트 오케스트레이션 (Agent Orchestration) 분야에서 LangGraph의 직접적인 경쟁자가 되었습니다. 가장 큰 차이점은 ADK가 Vertex AI, Cloud Run, 그리고 A2A 통합 기능이 내장된 Google 네이티브 (Google-native) 방식이라는 점입니다. 이미 Google Cloud를 깊이 있게 사용하고 있다면, 이를 진지하게 검토해 볼 가치가 있습니다.

만약 Google Cloud를 사용하지 않는다면, LangGraph가 여전히 더 성숙한 생태계를 보유하고 있으며, ADK 2.0의 새로운 A2A Task API가 도입되었다고 해서 그 계산법이 크게 바뀌지는 않습니다.

주요 에이전트 프레임워크 마이그레이션을 검토 중이라면, the AI Dev Toolkit에는 프레임워크 비교, 마이그레이션 계획, 멀티 에이전트 (Multi-agent) 설계 검토 등 에이전트 아키텍처 결정을 위한 30개 이상의 전용 프롬프트가 준비되어 있습니다. 이는 컨텍스트 스위칭 (Context-switching)으로 허비하는 오후 시간보다 훨씬 저렴합니다.

요약

변경 사항	영향
Workflow Runtime (그래프 기반)	결정론적 에이전트 흐름 (Deterministic agent flows)을 위한 새로운 아키텍처 — 2.0.0 안정화 버전 기준
...

이 글과 현재의 ADK 2.0 안정화 버전 사이에 변경된 사항을 발견하셨나요? 댓글로 알려주세요 — 이 분야는 매우 빠르게 변화합니다.