Google ADK 2.0: LLM 에이전트를 그래프 노드로 바꾼 Workflow Runtime

계층 실행기에서 그래프 엔진으로

Google의 Agent Development Kit(ADK)이 2.0을 출시했다. 2026년 5월 19일 Python 2.0.0이, 6월 30일 Go 2.0.0이 GA를 선언했다. 버전 번호 하나가 바뀐 게 아니라 실행 모델의 패러다임이 교체됐다.

ADK 1.x는 계층형 에이전트 실행기(hierarchical agent executor)였다. LLM이 도구를 선택하고, 서브에이전트를 호출하고, 결과를 모아 다음 단계를 결정하는 방식이다. LLM이 실행 흐름을 주도하기 때문에 경로가 비결정적이고, 에이전트가 어떤 노드를 어느 순서로 실행할지 예측하기 어렵다.

ADK 2.0은 이 구조를 뒤집는다. 에이전트, 도구, 함수 모두가 워크플로 그래프의 노드가 된다. 실행 흐름은 개발자가 정의한 엣지(edge)와 라우팅 조건을 따른다. LLM은 여전히 자연어 추론을 담당하지만, 어떤 노드로 갈지는 코드가 결정한다.

결과적으로 ADK 2.0의 워크플로는 에이전트를 포함한 결정론적 실행 경로를 가진다. 재현 가능하고, 디버그 가능하고, 테스트 가능하다.

그래프 아키텍처: 다섯 가지 노드 타입

AgentNode와 ToolNode

AgentNode는 LlmAgent 같은 에이전트 객체를 그래프 노드로 감싼다. LLM이 자연어 추론을 수행하고, 그 출력이 다음 노드로 향하는 라우팅 결정의 근거가 된다.

ToolNode는 단일 Tool을 그래프 스텝으로 변환한다. 입력과 출력이 타입 정의로 명확하므로, 실행 결과가 항상 동일하다.

JoinNode: fan-in 배리어

JoinNode는 여러 선행 노드가 모두 완료될 때까지 기다렸다가 결과를 맵으로 묶어 다음 노드에 넘긴다. 병렬로 실행된 검색 에이전트, DB 쿼리, 외부 API 호출의 결과를 합칠 때 사용한다.

DynamicNode: 런타임 분기

DynamicNode는 Python 코드로 다음 노드를 동적으로 결정한다. while 루프나 재귀 패턴이 필요할 때 쓴다. 코드가 "여기서 다시 LLM을 호출할지, 완료할지"를 제어한다.

WorkflowNode: 그래프 중첩

WorkflowNode는 독립적인 서브 워크플로를 단일 노드처럼 임베드한다. 재사용 가능한 서브 그래프를 컴포넌트처럼 조합할 수 있다.

LLMAgent도 이제 같은 노드 런타임을 탄다

1.x에서 LLM 에이전트와 워크플로는 서로 다른 실행 경로를 가졌다. 그래서 Human-in-the-Loop(HitL) 기능은 워크플로 안에서만 동작했다.

ADK 2.0에서는 단일 에이전트 앱도 동일한 노드 런타임으로 실행된다. runner가 LlmAgent를 내부적으로 노드 실행 경로로 통과시키기 때문에, 평범한 단일 LLM 에이전트도 HitL 일시 정지·재개를 지원한다.

개발자 입장에서는 "단일 에이전트인지 복잡한 워크플로인지"에 따라 HitL 설계를 따로 고민할 필요가 없어진다.

1.x에서 2.0으로: 세 가지 핵심 변화

1. BaseAgent가 BaseNode를 상속

1.x에서 커스텀 에이전트는 BaseAgent를 상속하고 _run_async_impl()이나 generate_content()를 오버라이드했다. 2.0에서 BaseAgent가 BaseNode를 상속하도록 바뀌면서 이 두 메서드 오버라이드는 더 이상 동작하지 않는다.

대신 BeforeAgentCallback과 AfterAgentCallback을 사용한다. 이 콜백은 노드 실행 전후에 후킹 가능하고, 프레임워크가 보장하는 실행 순서를 따른다.

2. Event 스키마에 node_info, output 필드 추가

Event 객체에 node_info(현재 노드 정보)와 output(워크플로 출력 추적)이 추가됐다. 커스텀 세션 저장소를 직접 구현한 경우 DB 스키마를 업데이트해야 한다. 이벤트를 직렬화된 JSON blob으로 저장하는 구현은 영향이 없다.

중요한 규칙이 하나 추가됐다: context.session.events.append()로 세션에 직접 이벤트를 추가하면 그래프 결정론이 깨진다. 이벤트는 반드시 노드에서 yield로 방출해야 한다.

3. 세션 호환성 단절

ADK 2.0이 생성한 세션은 ADK 1.28 이상에서 읽을 수 있다(추가 필드를 무시함). 그러나 2.0 스토리지를 1.x 데이터베이스와 함께 쓰면 데이터 손실이 발생한다. Google이 공식 문서에서 "things might break" 수준이 아니라 "data loss territory"로 명시했다.

세션 스키마, 메모리 시스템, 평가 데이터 스토리지가 모두 버전 간 비호환된다. 마이그레이션 전 반드시 1.x 스토리지를 백업하고, 별도 스토리지 엔드포인트로 분리해서 전환한다.

에러 처리에서 놓치기 쉬운 함정

ADK 2.0은 프레임워크 전역에 자동 재시도 메커니즘을 도입했다. 이 메커니즘이 예외를 잡아 재시도를 트리거하는데, 도구 내부에서 넓은 try-except 블록을 쓰면 이 재시도가 비활성화된다.

특히 BaseException을 잡으면 HitL 일시 정지에 사용하는 NodeInterruptedError까지 흡수된다. 이렇게 되면 에이전트가 멈춰야 할 시점에 계속 실행된다. 도구 코드에서는 Exception만 잡고, BaseException catch는 제거한다.

데이터 흐름: 중괄호와 꺾쇠 표기

노드 간 데이터 전달은 입력 스키마의 프로퍼티 셀렉터 문법을 쓴다.

• {property} — 입력 스키마에서 해당 프로퍼티를 선택
• <node_name.property> — 특정 선행 노드의 출력에서 프로퍼티를 선택하고 소스 노드를 한정

JoinNode 이후처럼 여러 노드의 결과가 맵으로 합쳐진 경우, <node_name.property> 표기로 특정 선행 노드의 결과를 명시적으로 꺼낸다.

Go 2.0: import 경로 변경

Go 2.0은 Python과 동시에 GA는 아니었다. 2026년 6월 30일에 Go 2.0.0이 GA 선언됐다. import 경로가 바뀐다:

// 1.x
import "google.golang.org/adk"

// 2.0
import "google.golang.org/adk/v2"

Go 모듈 컨벤션(major version suffix)을 따른 변경이다. Go 1.x 코드베이스는 import 경로만 바꾸는 게 아니라 API 변경에 맞는 구조 조정이 필요하다.

운영 전환 체크리스트

ADK 2.0으로 전환할 때 순서가 중요하다.

• [ ] _run_async_impl() / generate_content() 오버라이드를 콜백(BeforeAgentCallback / AfterAgentCallback)으로 교체
• [ ] 도구 내 BaseException catch 제거
• [ ] context.session.events.append() 직접 호출을 yield 방출로 변경
• [ ] 커스텀 세션 스토리지에 node_info, output 필드 추가
• [ ] 1.x 스토리지 백업 후 2.0 전용 스토리지 엔드포인트 분리
• [ ] HitL 플로가 있다면 NodeInterruptedError 전파 경로 검증
• [ ] Go 코드베이스: import 경로 v2 업데이트 및 API 변경 대응

왜 이 전환이 의미 있는가

LLM 에이전트 시스템의 가장 큰 운영 문제 중 하나는 재현성이다. LLM이 실행 경로를 결정하면 같은 입력에도 다른 노드를 거쳐 다른 결과가 나올 수 있다. 디버그가 어렵고, 회귀 테스트를 작성하기 힘들다.

ADK 2.0의 그래프 기반 워크플로는 이 문제에 대한 구조적 답변이다. LLM의 역할은 각 노드 안에서의 추론으로 한정되고, 노드 간 이동은 코드가 제어한다. 에이전트 시스템을 "LLM이 모든 것을 결정하는 블랙박스"에서 "LLM이 각 단계를 담당하는 투명한 그래프"로 바꾼다.

현재 버전은 2.4.0(2026년 7월 7일 릴리스)이며, 약 2주 간격의 릴리스 케이던스를 유지하고 있다.

References

• https://pypi.org/project/google-adk/
• https://github.com/google/adk-python
• https://github.com/google/adk-docs/blob/main/docs/2.0/index.md
• https://developers.googleblog.com/announcing-adk-go-20/
• https://adk.dev/graphs/
• https://atalupadhyay.wordpress.com/2026/03/28/google-adk-2-0-alpha-1-building-deterministic-ai-agents-with-graph-based-workflows/