Google ADK Samples 시작하기: 30분 안에 첫 AI 에이전트 띄우는 법 (2026)

LangChain 코드가 3,000줄을 넘어가는 순간 멈춰서 다른 길을 찾고 싶어진다. 같은 고민이라면 Google이 공개한 Agent Development Kit, 줄여서 ADK 그리고 그 공식 샘플 모음인 adk-samples 레포가 가장 빠른 출구다. 추상화는 가볍고 패턴은 공식이고 Gemini와 Vertex AI까지 자연스럽게 이어진다.

이 글은 ADK 자체를 광고하려는 글이 아니다. github.com/google/adk-samples 레포를 클론해서 가장 단순한 샘플 하나를 띄우고 그걸 내 도메인에 맞게 개조하는 가장 짧은 길을 보여준다.

📌 핵심 3줄 요약

• ADK는 Google이 2025년에 공개한 Apache 2.0 라이선스의 Python 중심 에이전트 프레임워크다.
• adk-samples 레포의 customer-service 샘플 하나면 도구 호출·멀티턴 대화 기본기를 30분 안에 띄울 수 있다.
• GCP 스택을 쓰고 있거나 LangGraph가 무겁게 느껴진다면 ADK가 실제로 가장 빠른 대안이다.

1. ADK가 뭐고 왜 또 새 프레임워크인가

ADK는 Google이 2025년에 공개한 Apache 2.0 라이선스의 에이전트 개발 키트다. Python SDK가 1차 시민이고 Gemini 모델을 기본 백엔드로 쓰며 Vertex AI Agent Engine에 그대로 배포할 수 있다.

LangGraph가 그래프 상태머신에 집중하고 CrewAI가 역할 기반 협업에 집중한다면 Google ADK는 그 둘 사이 어딘가에서 "프로덕션에 올릴 수 있는 표준 패턴"을 강조한다. 핵심 추상은 Agent와 Tool, 그리고 멀티 에이전트를 묶는 SequentialAgent / ParallelAgent / LoopAgent 같은 컴포지트다.

가장 직관적인 차이는 코드 양이다. 똑같은 "검색 + 요약" 에이전트를 LangChain으로 짜면 체인·메모리·콜백을 다 엮어야 하지만 ADK에서는 Agent 하나에 tools 리스트만 넘기면 끝난다.

2. ADK vs LangGraph vs CrewAI 한눈 비교

세 프레임워크를 동시에 검토 중이라면 이 표만 봐도 결정은 절반쯤 끝난다.

항목	Google ADK	LangGraph	CrewAI
메인 추상	Agent + Tool + Composite	StateGraph + Node	Crew + Agent + Task
1차 LLM	Gemini (다른 모델도 가능)	모델 무관	모델 무관
배포 통합	Vertex AI Agent Engine 네이티브	직접 구축	직접 구축
학습 곡선	낮음	중간	낮음
멀티 에이전트	공식 컴포지트 패턴	그래프로 직접 구현	역할 기반 협업
적합 시나리오	GCP 스택 + 표준 패턴	복잡한 상태 흐름	역할 분담 협업

ADK를 골라야 할 가장 명확한 이유는 두 가지다. 첫째 이미 GCP를 쓰고 있고 Vertex AI에 배포해야 한다. 둘째 LangChain 코드 베이스가 비대해져서 더 단순한 표준 패턴이 필요하다.

3. 사전 준비물 체크리스트

본격 실행 전에 환경부터 정리하자. Python 3.10 이상이 가장 흔한 첫 장애물이다.

• Python 3.10 이상 (3.11 권장)
• pip 또는 uv 패키지 매니저
• Google AI Studio API 키 또는 Vertex AI가 활성화된 GCP 프로젝트
• git CLI

가장 가볍게 시작하려면 Google AI Studio에서 Gemini API 키만 발급받으면 된다. Vertex AI 경로는 결제·서비스 계정·권한 설정이 따라붙어서 처음 한 번은 우회하는 편이 낫다.

python --version
# Python 3.11.x 이상이면 OK

mkdir adk-playground && cd adk-playground
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

가상환경을 따로 두는 이유는 단순하다. ADK가 google-genai, google-cloud-aiplatform 같은 무거운 의존성을 끌고 오기 때문이다. 시스템 파이썬을 더럽히지 말자.

4. adk-samples 레포 클론하고 구조 파악하기

이제 본진으로 들어간다. 공식 샘플 레포를 그대로 받는다.

git clone https://github.com/google/adk-samples.git
cd adk-samples
ls python/agents

레포는 언어별로 나뉘어 있고 Python 트리 안에 도메인별 폴더가 있다. 처음 봤을 때 "이게 다 뭐지" 싶을 수 있는데 폴더 이름만 봐도 의도가 보인다.

폴더	무엇을 보여주는가
customer-service	고객 지원 에이전트, 도구 호출과 대화 흐름의 기본
RAG	벡터 검색 + 생성, Vertex AI Search 또는 별도 인덱스
data-science	데이터 분석·SQL 생성형 에이전트
brand-search-optimization	검색 도구를 조합한 멀티스텝 에이전트
financial-advisor	멀티 에이전트 협업 예시

각 폴더는 거의 동일한 골격을 따른다. agent.py에 Agent 정의가 있고 tools.py에 도구 함수가 있고 prompt.py 또는 인스트럭션 텍스트가 분리돼 있다. 공식 표준 패턴이라는 ADK의 캐치프레이즈가 여기서 체감된다. 한 샘플을 읽으면 나머지 샘플도 거의 같은 구조로 읽힌다.

5. 가장 단순한 샘플 하나 실행하기

샘플 중 학습 곡선이 가장 완만한 customer-service를 골라 띄워보자. 도구 호출과 멀티턴 대화의 기본기를 모두 보여주면서 외부 인프라(벡터DB 등)는 요구하지 않는다.

cd python/agents/customer-service
pip install -r requirements.txt
# 또는 uv pip install -r requirements.txt

# Gemini API 키를 환경 변수로
export GOOGLE_API_KEY="your-key-here"
export GOOGLE_GENAI_USE_VERTEXAI=False  # AI Studio 경로

adk run customer_service

adk run 명령은 ADK CLI가 제공하는 로컬 실행 진입점이다. 터미널에서 바로 대화형 세션이 열리고 질문을 던지면 에이전트가 내부 도구를 호출하면서 답한다. 처음 띄웠을 때 "이미 등록된 주문 상태를 알려달라" 같은 질문을 던지면 가짜 도구가 호출되고 결과가 자연어로 다시 합쳐져 나온다.

웹 UI로 확인하고 싶다면 adk web 명령을 쓴다. 브라우저에서 에이전트 호출 흐름·도구 인자·중간 응답까지 모두 보인다. 디버깅 단계에서 이 UI가 없었다면 LangChain 콜백 지옥을 다시 만났을 거라는 게 솔직한 감상이다.

6. 샘플을 내 도메인용으로 개조하는 패턴

샘플이 떴다면 본격 가치는 지금부터다. 어떤 샘플이든 보통 다음 4단계로 내 도메인용 에이전트로 바꿀 수 있다.

1. 인스트럭션(시스템 프롬프트)을 내 비즈니스 톤·정책에 맞게 다시 작성한다.
2. tools.py의 가짜 도구를 실제 API 콜로 교체한다 (REST·DB·내부 마이크로서비스).
3. 필요하다면 SequentialAgent 또는 LoopAgent로 멀티 에이전트화한다.
4. 평가용 시나리오 몇 개를 eval/ 폴더에 추가하고 회귀 테스트로 돌린다.

가장 손이 자주 가는 부분은 도구 교체다. ADK에서 도구는 그냥 타입 힌트가 붙은 Python 함수다. 데코레이터도 BaseTool 상속도 필요 없다.

from google.adk import Agent
import httpx

def get_order_status(order_id: str) -> dict:
    """주문 ID로 현재 상태를 조회한다."""
    # 실제 ERP API 호출로 교체
    resp = httpx.get(f"https://internal-api/orders/{order_id}")
    return resp.json()

def cancel_order(order_id: str, reason: str) -> str:
    """주문을 취소하고 사유를 기록한다."""
    httpx.post(
        "https://internal-api/orders/cancel",
        json={"order_id": order_id, "reason": reason},
    )
    return f"{order_id} 취소 처리되었습니다."

root_agent = Agent(
    name="cs_agent",
    model="gemini-2.0-flash",
    instruction="너는 e커머스 고객지원 에이전트다. 주문 관련 문의는 도구로 조회하고 추측하지 마라.",
    tools=[get_order_status, cancel_order],
)

함수의 docstring과 타입 힌트가 그대로 LLM에게 도구 스펙으로 전달된다. 그래서 docstring을 대충 쓰면 그 즉시 도구 호출 정확도가 떨어진다. 한 번은 docstring을 빈 줄로 둔 채 띄웠다가 모델이 get_order_status를 다른 함수와 혼동해 엉뚱한 파라미터를 넣는 걸 본 적이 있다. 도구 docstring은 코드보다 더 신경 써서 써야 한다.

7. Vertex AI Agent Engine에 배포하기 (개요)

로컬에서 잘 돈다면 다음 단계는 호스팅이다. ADK는 Vertex AI Agent Engine과 1급 통합을 제공한다.

배포 자체는 명령 한 줄에 가깝지만 사전 작업이 더 길다. GCP 프로젝트 선택, 결제 활성화, Vertex AI API 활성화, 서비스 계정 권한, 그리고 환경 변수 두 줄 변경이다.

export GOOGLE_GENAI_USE_VERTEXAI=True
export GOOGLE_CLOUD_PROJECT="your-project-id"
export GOOGLE_CLOUD_LOCATION="us-central1"

# 배포 (샘플 내 deployment 스크립트 참고)
python deployment/deploy.py

배포가 완료되면 Agent Engine 리소스 ID가 발급되고 REST·gRPC 엔드포인트로 호출할 수 있다. 자체 인프라에 별도의 서빙 컨테이너를 띄우지 않아도 되는 게 가장 큰 장점이다. 다만 Vertex AI 가격 모델은 미리 살펴보길 권한다. 트래픽이 작아도 항상 떠 있는 리소스라 청구서가 익숙해질 때까지 알람을 걸어두는 편이 안전하다.

⚠️ 자주 막히는 지점과 단점

처음 ADK를 만지면 거의 모두가 같은 지점에서 막힌다. 일종의 통과의례라 봐도 된다.

• GOOGLE_API_KEY만 잡고 GOOGLE_GENAI_USE_VERTEXAI=False를 빼먹으면 Vertex AI 인증을 시도하다 실패한다. 두 변수를 한 쌍으로 다뤄라.
• 도구 함수가 dict를 반환할 때는 JSON 직렬화 가능한 타입만 담아라. datetime 같은 객체는 문자열로 변환.
• 멀티 에이전트로 만들기 전에 단일 Agent로 충분히 검증하라. 디버깅 난이도가 한 차원 올라간다.
• adk web은 개발용이지 운영용이 아니다. 운영은 무조건 Agent Engine 또는 자체 서빙.
• 평가 시나리오를 코드 베이스에 두지 않으면 프롬프트 한 줄 바꿀 때마다 손으로 다시 테스트하게 된다. 처음부터 eval/ 폴더를 채워라.

💡 핵심 포인트

• 가상 도구로 충분히 검증한 뒤 실제 API로 교체하는 두 단계 전략이 사고를 가장 많이 줄여준다.
• Gemini 외 모델은 LiteLLM 어댑터로 붙일 수 있지만 일부 도구 호출 기능은 Gemini에서 더 매끄럽다.

8. FAQ

Q. ADK는 Gemini 외 다른 모델도 지원하나요?
A. 공식적으로 Gemini가 1차 백엔드지만 LiteLLM 같은 어댑터를 통해 OpenAI·Anthropic 모델도 연결할 수 있다. 단 도구 호출 포맷 차이로 인해 일부 기능은 Gemini에서 더 매끄럽게 동작한다.

Q. LangGraph에서 ADK로 갈아탈 가치가 있나요?
A. 코드가 작거나 그래프 상태가 복잡하지 않다면 큰 이득은 없다. 반대로 LangGraph 코드가 비대해지고 운영 표준화가 절실하다면 ADK가 깔끔한 답이다.

Q. adk-samples 라이선스는 어떻게 되나요?
A. Apache 2.0이다. 상업적 이용·수정·재배포 모두 가능하며 원저작자 표기와 라이선스 사본 포함 의무만 지키면 된다.

Q. 한국어 응답 품질은 어떤가요?
A. Gemini 2.0 계열 이후 한국어는 실무에 쓸 만한 수준이다. 다만 도메인 특화 용어가 많다면 인스트럭션에 용어집을 명시하는 편이 안전하다.

🚀 지금 바로 할 일

1. git clone https://github.com/google/adk-samples.git로 레포를 받는다.
2. Google AI Studio에서 Gemini API 키를 발급받아 환경 변수로 잡는다.
3. customer-service 샘플을 adk run으로 띄우고 도구 함수 하나를 내 비즈니스 로직으로 교체해본다.

💬 의견

지금 LangGraph·CrewAI·ADK 중 어떤 프레임워크로 에이전트를 짜고 계신가요? 갈아탄 경험이 있다면 결정 포인트가 무엇이었는지 댓글로 공유 부탁드립니다. 다음 글은 RAG 샘플을 Vertex AI Search와 붙이는 실전편을 다룰 예정입니다.

참고 자료

• github.com/google/adk-samples — 본 글의 코드 경로·디렉터리 명명 규칙은 모두 이 레포 기준이다.
• github.com/google/adk-python — ADK 코어 SDK. Agent, SequentialAgent 등 클래스 시그니처를 확인할 때 본다.
• Vertex AI Agent Engine 공식 문서 — 배포·인증·가격 모델 확인.
• Google Gemini API 공식 문서 — 모델별 입력 토큰 한도와 도구 호출 포맷.

---