Google의 Agent Development Kit(ADK)은 멀티에이전트 시스템을 다루기 쉽게 만드는 프레임워크입니다. LangChain이나 CrewAI로 AI 에이전트를 만들어보았지만 프레임워크와 싸우는 것처럼 느껴졌다면, 이 Google ADK 튜토리얼은 첫 번째 에이전트부터 Cloud Run에 배포하는 것까지 모든 것을 안내합니다.
Google ADK란 무엇인가? (그리고 왜 신경 써야 하나?)
Google의 Agent Development Kit(ADK)은 AI 에이전트를 구축, 평가, 배포하기 위한 오픈소스 Python 프레임워크입니다. 2025년에 출시되었으며 Gemini에 최적화되어 있지만 LiteLLM을 통해 100개 이상의 모델을 지원합니다. ADK의 핵심 기능은 네이티브 멀티에이전트 오케스트레이션으로, 에이전트가 다른 에이전트에 작업을 위임할 수 있으며 보일러플레이트 코드가 필요 없습니다.
LangChain, CrewAI, 그리고 이제 ADK로 에이전트를 만들어본 결과, ADK가 돋보이는 이유는 이것입니다: ADK는 올바른 위치에서 주관적인 결정을 내립니다. 프로젝트 구조, 내장 개발 UI, 배포 명령어를 제공합니다. 기본적인 에이전트를 실행하기 위해 다섯 개의 라이브러리를 연결할 필요가 없습니다.
LangChain이 범용 멀티도구라면, ADK는 Google의 멀티에이전트 워크플로를 위해 목적에 맞게 만든 도구입니다. CrewAI도 철학적으로 비슷합니다. 역할 기반 에이전트들이 협력하는 방식이지만, ADK는 내장 평가, 네이티브 Gemini 최적화, 한 줄 명령어로 Cloud Run 배포가 가능하다는 점에서 더 나아갑니다. 더 자세한 비교는 에이전트 프레임워크 비교 심층 분석을 확인하세요.
ADK는 누구를 위한 도구인가? 구조화된 멀티에이전트 시스템을 원하는 Python 개발자. 이미 Google Cloud나 Gemini를 사용 중인 팀. 보일러플레이트 오케스트레이션 로직 작성에 지친 누구나.
프레임워크 비교는 다음과 같습니다:
간단히 말해서, "아이디어"에서 "배포된 멀티에이전트 시스템"까지의 가장 빠른 경로를 원한다면, 지금 ADK는 따라가기 힘들 정도로 좋습니다.
사전 요구사항과 Google ADK 설치
Google ADK를 시작하려면 Python 3.9+, Gemini API 키(Google AI Studio에서 무료로 제공), google-adk 패키지가 필요합니다. pip install google-adk로 설치하고, API 키를 환경 변수로 설정하면 5분 이내에 첫 에이전트를 만들 수 있습니다.
설정 체크리스트:
- Python 3.9+ (전체 타입 힌트 지원을 위해 3.10+ 권장)
- Gemini API 키 -- aistudio.google.com에서 무료로 발급받으세요. 무료 요금제는 분당 15개의 요청을 제공하며, 개발에는 충분합니다.
- pip (또는 속도를 선호한다면 uv -- uv pip install google-adk도 작동합니다)
패키지를 설치하고 키를 설정합니다:
ADK는 특정한 폴더 구조를 기대합니다. 각 에이전트는 자신의 패키지 디렉토리에 있어야 합니다:
폴더 이름이 에이전트의 패키지 이름이 되므로 의미 있는 이름을 선택하세요. test나 agent라고 부르지 마세요. Python의 import 시스템을 혼동시킵니다.
팁: uv를 사용 중이라면, uv venv && source .venv/bin/activate로 가상 환경을 먼저 생성하세요. 일반 pip보다 의존성 해결 속도가 눈에 띄게 빠릅니다.
첫 번째 Google ADK 에이전트 만들기
첫 번째 ADK 에이전트는 세 가지만 필요합니다: 이름, 모델(gemini-2.0-flash 같은), 그리고 명령 문자열. agent.py에서 정의하고, init.py가 있는 폴더 안에 놓으세요. 그리고 adk web을 실행하면 브라우저 UI에서 채팅할 수 있습니다. 전체 설정은 약 10줄의 Python으로 끝납니다.
my_agent 폴더를 만들고 두 개의 파일을 추가합니다. 먼저 에이전트 정의입니다:
그 다음 에이전트를 내보내는 init 파일:
그 변수 이름이 중요합니다. ADK는 특히 root_agent를 찾습니다. 이것을 놓치면 왜인지 설명하지 않는 "agent not found" 오류가 나타납니다.
이제 실행합니다. 두 가지 옵션이 있습니다:
adk web 인터페이스는 정말 유용합니다. 전체 대화 추적, 에이전트가 호출한 도구, 모델이 받은 것, 반환한 것을 모두 보여줍니다. 에이전트용 Chrome DevTools라고 생각하세요. 나중에 멀티에이전트 시스템을 만들기 시작하면, 위임 흐름을 이해하는 데 필수가 됩니다.
명령을 수정해서 동작 변화를 보세요. 해적처럼 만들어보세요. 하이쿠로만 답하게 만들어보세요. 명령이 동작을 어떻게 형성하는지 감을 익히는 것이 이 튜토리얼의 모든 것의 기초입니다.
Google ADK 에이전트에 맞춤 도구 추가하기
ADK 에이전트는 도구를 줄 때 유용해집니다. 명확한 docstring을 가진 Python 함수를 정의하면, ADK는 자동으로 이를 에이전트가 호출할 수 있는 도구로 변환합니다. docstring은 중요합니다. 도구가 무엇을 하고 언제 사용하는지 모델에게 알려줍니다. ADK는 또한 Google Search와 코드 실행 같은 내장 도구를 제공합니다.
도구는 에이전트의 손입니다. 없으면 에이전트는 말할 수만 있습니다. 있으면 데이터베이스를 확인하고, API를 호출하고, 계산을 실행하고, 외부 시스템과 상호작용할 수 있습니다. 함수 호출이 내부적으로 어떻게 작동하는지 이해하고 싶다면, 이에 대한 별도의 심층 분석이 있습니다.
맞춤 함수 도구
주식 가격을 조회하는 도구의 실제 예시입니다:
타입 힌트와 docstring에 주목하세요. 이들은 선택 사항이 아닙니다. ADK는 이들을 사용해서 모델이 보는 도구 스키마를 생성합니다. docstring을 건너뛰면 모델은 함수를 호출해야 할 때를 알 수 없습니다. 타입 힌트를 건너뛰면 서명 오류가 발생합니다.
내장 도구 (Google Search, Code Execution)
ADK는 코드를 작성하지 않고도 바로 사용할 수 있는 도구들과 함께 제공됩니다:
google_search를 사용하면 에이전트가 실시간으로 웹을 쿼리할 수 있습니다. code_execution은 계산을 실행할 수 있는 샌드박스 Python 환경을 제공합니다. 이 두 가지만 해도 놀랍도록 많은 사용 사례를 다룹니다.
멀티에이전트 시스템: Google ADK 에이전트는 어떻게 작업을 위임하는가?
ADK의 멀티에이전트 시스템은 루트 에이전트를 사용하여 작업을 특화된 서브에이전트에게 위임합니다. 각 서브에이전트는 하나의 도메인(연구, 작성, 코딩)을 처리합니다. 루트 에이전트는 사용자의 요청을 기반으로 어느 서브에이전트를 호출할지 결정합니다. 에이전트를 도구로 사용하는 에이전트-도구 패턴을 사용할 수도 있습니다. 하나의 에이전트가 다른 에이전트를 함수인 것처럼 호출합니다. Google의 멀티에이전트 시스템에 대한 공식 블로그는 아키텍처 패턴을 더 깊이 다룹니다.
프로젝트 매니저가 전문가에게 일을 위임하는 것처럼 생각해보세요. 루트 에이전트는 사용자의 요청을 읽고, 어느 전문가가 처리해야 하는지 파악하고, 그에 따라 라우팅합니다. 전문가들은 서로를 알지 못합니다. 그들은 자신의 일을 하고 결과만 보고합니다.
루트 에이전트 + 서브에이전트 패턴
루트 에이전트가 연구 에이전트와 작성 에이전트에게 위임하는 실제 작동 예시입니다:
각 서브에이전트의 description 필드는 루트 에이전트가 서브에이전트가 무엇을 할 수 있는지 이해하는 방법입니다. 명확한 설명을 작성하세요. 모호한 설명은 잘못된 라우팅 결정을 초래합니다.
에이전트-도구 패턴
때로는 한 에이전트가 다른 에이전트를 호출하는 방식을 더 많이 제어하고 싶을 수도 있습니다. 에이전트-도구 패턴은 서브에이전트를 호출 가능한 도구로 래핑합니다:
루트 에이전트가 완전히 제어권을 위임하고 싶을 때는 서브에이전트를 사용하세요. 호출 에이전트가 주도권을 유지하고 서브에이전트의 출력을 입력으로만 사용하고 싶을 때는 에이전트-도구를 사용하세요. 에이전트가 공유 컨텍스트가 필요한 시스템을 만들고 있다면, 에이전트 메모리 아키텍처에 대한 종합 가이드를 참조하세요.
워크플로우 에이전트: 순차, 병렬, 루프
LLM 기반 위임을 넘어서, ADK는 결정론적 오케스트레이션을 위한 세 가지 워크플로우 에이전트 타입을 제공합니다: SequentialAgent는 서브에이전트를 하나씩 실행하고, ParallelAgent는 동시에 실행하고, LoopAgent는 조건이 충족될 때까지 시퀀스를 반복합니다. 이들은 LLM이 결정하는 것보다 예측 가능한 실행 순서가 필요할 때 유용합니다.
이 구분이 중요합니다. LLM 기반 위임(위의 sub_agents 패턴)은 모델이 누구를 호출할지 선택하게 합니다. 워크플로우 에이전트는 프로그래매틱 제어를 제공합니다. 실행 순서가 미리 알려져 있을 때 워크플로우 에이전트를 사용하세요.
동시에 실행할 수 있는 독립적인 작업을 위해서는 ParallelAgent가 실제 시간을 절약합니다:
상태와 메모리 관리
...