ADK 2.0가 뭔지, 결론부터

Google ADK(Agent Development Kit)는 AI 에이전트를 코드 중심으로 만들 수 있는 오픈소스 Python 프레임워크입니다. 2025년 4월에 1.0이 출시됐고, 불과 약 11개월 만에 구조적으로 다른 2.0 알파가 나왔습니다. PyPI 등록일은 2026년 3월 18일이고(출처: PyPI google-adk 2.0.0a1), 같은 달 25일 ADK Community Call에서 처음 공개 발표가 이뤄졌습니다.

1.0에서 에이전트를 만들 때 핵심은 “LLM에게 긴 프롬프트를 주고 스텝을 따라가게 하는 것”이었습니다. 그런데 프롬프트가 길어질수록 에이전트가 스텝을 건너뛰거나 순서를 바꾸는 일이 생겼습니다. 2.0은 그 문제를 “프롬프트 대신 코드로 실행 흐름을 고정”하는 Graph 워크플로우로 해결하는 방향을 잡았습니다.

2.0의 핵심 신기능 3가지는 공식 문서 기준으로 다음과 같습니다. ① Graph 기반 워크플로우(결정론적 실행 흐름 제어), ② 협업 에이전트(코디네이터+서브에이전트 팀 구성), ③ 동적 워크플로우(루프·조건 분기를 코드로 정의). 이 3가지가 ADK 2.0을 1.0과 다른 버전으로 만드는 실질적 이유입니다. (출처: Google ADK 2.0 공식 문서, google.github.io/adk-docs/2.0/)

▲ 목차로 돌아가기

Graph 워크플로우 — 프롬프트를 코드로 대체하는 방식

Graph 워크플로우의 핵심은 Workflow 클래스의 edges 배열입니다. 실행 순서를 코드에서 명시적으로 지정하기 때문에 LLM이 스텝을 임의로 건너뛸 수 없습니다. 더 중요한 점은, AI 없이 파이썬 함수만 실행하는 노드를 에이전트 사이에 자유롭게 끼워 넣을 수 있다는 것입니다. 이 부분은 기존 블로그 대부분이 지나치는 대목입니다.

예를 들어 아래 구조처럼 도시 생성(LLM) → 시간 조회(파이썬 함수) → 리포트(LLM) 순으로 실행할 수 있습니다. 중간의 시간 조회 함수는 LLM 없이 코드만 동작합니다.

from google.adk import Agent, Workflow
city_agent = Agent(model="gemini-2.5-flash", ...)  # LLM 노드
def lookup_time(node_input: str):  # 파이썬 함수 노드 (LLM 없음)
return CityTime(time_info="10:10 AM", city=node_input)
report_agent = Agent(model="gemini-2.5-flash", ...)  # LLM 노드
root_agent = Workflow(
name="root_agent",
edges=[("START", city_agent, lookup_time, report_agent)]
)

가운데 lookup_time은 LLM 호출이 없습니다. LLM 비용이 스텝마다 발생하지 않아도 됩니다.

▲ 목차로 돌아가기

협업 에이전트 3가지 모드와 실제 쓸 수 있는 조건

ADK 2.0에서 서브에이전트에게 mode를 지정할 수 있습니다. 공식 문서가 제시하는 3가지 모드는 다음과 같습니다.

(출처: ADK Collaboration 공식 문서, google.github.io/adk-docs/workflows/collaboration/)

병렬 실행이 되는 모드는 single_turn뿐입니다. 여러 서브에이전트를 동시에 돌려서 시간을 단축하고 싶다면 이 모드여야 합니다. 단, single_turn과 task 모드는 각자 독립된 세션 브랜치에서 실행되기 때문에 서로의 진행 상황을 실시간으로 볼 수 없습니다. 병렬로 실행된 결과는 모두 완료된 뒤에 부모 에이전트가 취합합니다.

주의할 점이 하나 더 있습니다. 공식 문서는 mode 설정을 루트 에이전트에 적용하면 안 된다고 명시합니다. 서브에이전트 전용 기능입니다. (출처: ADK Collaboration 공식 문서)

▲ 목차로 돌아가기

1.0 프로젝트와 섞으면 안 되는 진짜 이유

ADK 2.0 공식 문서는 상단에 굵은 글씨로 이렇게 경고합니다.

“DO NOT allow ADK 2.0 projects to share storage with ADK 1.0 projects, including, but not limited to, session storage, memory systems, and evaluation data. Doing so may result in loss of data or make the data unusable in ADK 1.0 projects.”

출처: ADK 2.0 공식 문서 (google.github.io/adk-docs/2.0/)

“1.0과 호환되도록 설계됐다”는 표현이 앞부분에 있기 때문에, 많은 사람이 기존 1.0 프로젝트 위에 2.0을 올려도 될 것이라고 생각합니다. 하지만 저장소를 공유하는 순간 1.0 데이터가 사용 불가 상태가 되거나 아예 날아갈 수 있다고 공식 문서가 명시합니다. 호환성이 보장되는 건 “에이전트 코드 구조”이지, “저장 데이터 스키마”가 아닙니다.

현재 ADK 1.0 기반으로 운영 중인 서비스가 있다면, 2.0으로의 전환은 별도 가상환경과 별도 저장소에서 처음부터 시작해야 합니다. 1.0 프로젝트 폴더에서 pip install google-adk --pre를 실행하는 방식은 피해야 합니다.

▲ 목차로 돌아가기

설치 방법과 1.0과의 호환성 현실

ADK 2.0을 설치하려면 반드시 --pre 플래그가 필요합니다. pip install google-adk만으로는 2.0이 설치되지 않고 1.x 최신 버전이 설치됩니다.

# 새 가상환경 먼저 생성 (필수)
python -m venv .venv-adk2
source .venv-adk2/bin/activate  # macOS/Linux
# ADK 2.0 알파 설치
pip install google-adk --pre
# 또는 버전 핀 방식
pip install google-adk==2.0.0a1

기존 1.0 환경이 있다면 --force 옵션으로 강제 설치할 수 있지만, 공식 문서는 이 방법으로 업그레이드할 경우 1.0 프로젝트 백업을 먼저 만들도록 경고합니다. (출처: ADK 2.0 공식 문서)

실제 설치 필요 사항은 Python 3.11 이상입니다. Python 3.10 이하 환경에서는 동작하지 않습니다. (출처: PyPI google-adk 2.0.0a1, 2026.03.18)

ADK 2.0은 현재 Python 전용 알파입니다. Java·TypeScript 버전의 공식 2.0 출시 일정은 공식 문서에서 별도로 밝히지 않은 상태입니다.

▲ 목차로 돌아가기

Graph 워크플로우가 안 되는 기능 목록

Graph 기반 워크플로우는 강력하지만, 기존 ADK 기능 전부와 호환되지 않습니다. 공식 Known limitations 섹션에 직접 명시된 내용입니다.

Live Streaming 제한은 실시간 음성 대화, 영상 처리 에이전트를 만드는 경우라면 치명적입니다. 이 용도라면 Graph 워크플로우 대신 기존 방식의 에이전트를 유지해야 합니다.

또한 ADK 1.0에서 built-in 툴과 structured output을 동시에 쓰려면 번거로운 래핑이 필요한데, 이 제한은 2.0에서도 공식적으로 해결됐다는 발표가 없습니다. 커뮤니티 수준의 우회법이 존재하지만 공식 해법은 아직입니다.

▲ 목차로 돌아가기

ADK 2.0 지금 써야 할 사람 vs 기다려야 할 사람

알파 버전이라는 레이블 하나에 “아직 아니다”로 결론 내리는 건 정확하지 않습니다. 용도에 따라 지금 시작해도 되는 경우와 기다려야 하는 경우가 분명히 나뉩니다.

솔직히 말하면, ADK 2.0에서 가장 매력적인 기능인 Graph 워크플로우는 LangGraph가 이미 비슷한 개념으로 먼저 내놓은 것이기도 합니다. 차이는 Google Cloud, Gemini, A2A 프로토콜과의 네이티브 연동입니다. 특히 Google Cloud Run 배포가 adk deploy cloud_run 한 줄로 된다는 점은 LangGraph에는 없는 실질적 이점입니다.

▲ 목차로 돌아가기

자주 묻는 것들 — Q&A

▲ 목차로 돌아가기

마치며

ADK 2.0에서 가장 실질적인 변화는 “프롬프트로 흐름을 제어하던 것”에서 “코드로 그래프를 고정하는 것”으로의 전환입니다. 이게 단순한 기능 추가가 아니라, 에이전트가 얼마나 예측 가능하게 동작하느냐의 문제를 구조적으로 바꾸는 접근입니다.

다만 알파는 알파입니다. 공식 문서가 “데이터 날아간다”고 직접 쓴 경고를 가볍게 보면 안 됩니다. 기존 서비스에 올리기 전에 반드시 별도 환경에서 충분히 테스트하고, GitHub 이슈 트래커를 주기적으로 확인하는 것이 현실적인 접근 방법입니다.

개인적으로는 지금 당장 새 프로젝트를 시작한다면 ADK 2.0으로 시작할 것입니다. 1.0으로 쌓아온 게 있다면 조금 더 기다리겠습니다.

▲ 목차로 돌아가기

📚 본 포스팅 참고 자료

1. Google ADK 2.0 공식 문서 — google.github.io/adk-docs/2.0/
2. Google ADK Workflows 공식 문서 — google.github.io/adk-docs/workflows/
3. PyPI google-adk 2.0.0a1 (2026.03.18) — pypi.org/project/google-adk/2.0.0a1/
4. ADK Collaboration 공식 문서 — google.github.io/adk-docs/workflows/collaboration/
5. DLabs.ai ADK Production Challenges (2025.12) — dlabs.ai 원문 링크