Google ADK 실전 가이드 — 에이전트를 백엔드 시스템처럼 만드는 법

2025년 4월 Google이 ADK(Agent Development Kit)를 출시했어요. 2026년 4월 기준 v1.26.0까지 업데이트됐어요.

다른 프레임워크들이 "AI 에이전트를 빠르게 만들자"에 집중할 때 ADK는 다른 방향을 봐요.

CrewAI:  역할 기반 팀 → 빠른 프로토타입
LangGraph: 그래프 기반 → 복잡한 워크플로우
ADK:     백엔드 시스템처럼 → 프로덕션 배포 중심

---

ADK가 뭔가

오픈소스 (Apache 2.0)
지원 언어: Python, TypeScript, Java, Go
모델: Gemini 최적화, 다른 모델도 지원
배포: Vertex AI Agent Engine (완전 관리형)
프로토콜: MCP + A2A 네이티브 지원

핵심 철학:

"에이전트는 LLM 실험이 아니라
프로덕션 소프트웨어다.
처음부터 배포, 모니터링, 테스트를 고려해라."

---

설치 및 기본 설정

pip install google-adk

# Google Cloud 인증 (Vertex AI 사용 시)
gcloud auth application-default login

# 환경 변수
export GOOGLE_CLOUD_PROJECT="your-project-id"
export GOOGLE_CLOUD_LOCATION="us-central1"

프로젝트 구조:

my_agent/
  __init__.py
  agent.py      # 에이전트 정의
  tools.py      # 커스텀 툴
  .env          # 환경 변수

---

1단계 — 기본 에이전트 만들기

# agent.py
from google.adk.agents import Agent
from google.adk.models.lite_llm import LiteLlm

# 툴 정의 — 도큐스트링이 핵심
def get_weather(city: str) -> dict:
    """특정 도시의 현재 날씨를 가져옵니다.

    Args:
        city: 날씨를 조회할 도시 이름 (예: "서울", "부산")

    Returns:
        온도(celsius), 날씨 상태, 습도를 포함한 딕셔너리
    """
    # 실제로는 날씨 API 호출
    return {
        "city": city,
        "temperature": 22,
        "condition": "맑음",
        "humidity": 45
    }

def search_news(query: str, limit: int = 5) -> list:
    """최신 뉴스를 검색합니다.

    Args:
        query: 검색어
        limit: 반환할 뉴스 개수 (기본값: 5)

    Returns:
        제목과 요약을 포함한 뉴스 목록
    """
    # 실제로는 뉴스 API 호출
    return [{"title": f"{query} 관련 뉴스 {i}", "summary": "..."}
            for i in range(limit)]

# 에이전트 정의
agent = Agent(
    model="gemini-2.0-flash",  # Gemini 기본 사용
    name="assistant_agent",
    description="날씨와 뉴스를 제공하는 어시스턴트",
    instruction="""
    당신은 친절한 어시스턴트입니다.
    사용자가 날씨나 뉴스를 물어보면 적절한 툴을 사용하세요.
    항상 한국어로 답변하세요.
    """,
    tools=[get_weather, search_news]
)

# 로컬에서 실행
adk run my_agent

# 브라우저 UI로 실행
adk web

---

2단계 — 다른 모델 사용

ADK는 Gemini 외에 다른 모델도 지원해요.

from google.adk.models.lite_llm import LiteLlm

# Claude 사용
claude_agent = Agent(
    model=LiteLlm(model="anthropic/claude-opus-4-7"),
    name="claude_assistant",
    tools=[get_weather, search_news]
)

# GPT-5.4 사용
gpt_agent = Agent(
    model=LiteLlm(model="openai/gpt-5.4"),
    name="gpt_assistant",
    tools=[get_weather, search_news]
)

# 로컬 Ollama 사용
local_agent = Agent(
    model=LiteLlm(model="ollama/llama3.2"),
    name="local_assistant",
    tools=[get_weather]
)

---

3단계 — 멀티에이전트 시스템

ADK의 핵심이에요. 계층적 에이전트 트리로 구성해요.

from google.adk.agents import Agent
from google.adk.tools import agent_tool

# 전문화된 서브에이전트들
flight_agent = Agent(
    model="gemini-2.0-flash",
    name="flight_agent",
    description="항공편 검색과 예약 전문 에이전트",
    instruction="항공편 관련 요청만 처리하세요. 다른 요청은 거절하세요.",
    tools=[search_flights, book_flight]
)

hotel_agent = Agent(
    model="gemini-2.0-flash",
    name="hotel_agent",
    description="숙소 검색과 예약 전문 에이전트",
    instruction="숙소 관련 요청만 처리하세요.",
    tools=[search_hotels, book_hotel]
)

# 서브에이전트를 툴로 변환
flight_tool = agent_tool.AgentTool(agent=flight_agent)
hotel_tool = agent_tool.AgentTool(agent=hotel_agent)

# 루트 에이전트 — 모든 요청의 진입점
root_agent = Agent(
    model="gemini-2.0-flash",
    name="travel_coordinator",
    description="여행 전체를 조율하는 메인 에이전트",
    instruction="""
    사용자의 여행 요청을 분석하고
    적절한 전문 에이전트에게 위임하세요.
    항공편과 숙소 예약은 독립적으로 처리 가능합니다.
    """,
    tools=[flight_tool, hotel_tool]
)

---

4단계 — 병렬 실행

서로 독립적인 작업을 동시에 실행해서 속도를 높여요.

from google.adk.agents import ParallelAgent, SequentialAgent

# 병렬 실행: 항공편과 숙소를 동시에 검색
parallel_search = ParallelAgent(
    name="parallel_travel_search",
    sub_agents=[flight_agent, hotel_agent]
)

# 순차 실행: 검색 → 비교 → 예약
booking_pipeline = SequentialAgent(
    name="booking_pipeline",
    sub_agents=[
        parallel_search,    # 1단계: 동시 검색
        comparison_agent,   # 2단계: 결과 비교
        booking_agent       # 3단계: 최적 옵션 예약
    ]
)

실행 흐름:

SequentialAgent
├── ParallelAgent (동시 실행)
│   ├── FlightAgent → 항공편 5개 검색 (2초)
│   └── HotelAgent → 숙소 3개 검색 (2초)
│   총 2초 (순차면 4초)
├── ComparisonAgent → 결과 비교 (1초)
└── BookingAgent → 예약 (1초)
총 4초 (순차면 6초)

---

5단계 — 세션 상태 관리

에이전트가 대화 전반에 걸쳐 상태를 유지해요.

from google.adk.sessions import InMemorySessionService
from google.adk.runners import Runner

# 세션 서비스 설정
session_service = InMemorySessionService()

# 프로덕션: 데이터베이스 백엔드
# from google.adk.sessions import DatabaseSessionService
# session_service = DatabaseSessionService(db_url="postgresql://...")

runner = Runner(
    agent=root_agent,
    app_name="travel_app",
    session_service=session_service
)

# 대화 실행
async def chat(user_id: str, session_id: str, message: str):
    from google.genai import types

    content = types.Content(
        role="user",
        parts=[types.Part(text=message)]
    )

    async for event in runner.run_async(
        user_id=user_id,
        session_id=session_id,
        new_message=content
    ):
        if event.is_final_response():
            return event.content.parts[0].text

---

6단계 — 평가 (ADK의 핵심 차별점)

대부분의 프레임워크가 무시하는 평가를 ADK는 기본으로 지원해요.

# tests/test_travel_agent.py
from google.adk.evaluation import AgentEvaluator

evaluator = AgentEvaluator()

# 테스트 케이스 정의
test_cases = [
    {
        "query": "서울에서 도쿄 가는 가장 싼 항공편 찾아줘",
        "expected_tool_calls": ["search_flights"],
        "expected_outcome": "항공편 검색 결과 포함"
    },
    {
        "query": "신주쿠에 있는 호텔 중 조식 포함 3성급 찾아줘",
        "expected_tool_calls": ["search_hotels"],
        "expected_outcome": "조식 포함 호텔 목록"
    }
]

# 평가 실행
results = await evaluator.evaluate(
    agent=root_agent,
    test_cases=test_cases,
    metrics=["tool_call_accuracy", "response_relevance"]
)

print(f"툴 호출 정확도: {results.tool_call_accuracy:.1%}")
print(f"응답 관련성: {results.response_relevance:.1%}")

---

7단계 — Vertex AI 배포

from vertexai.agent_engines import AdkApp
import vertexai

vertexai.init(
    project="your-project-id",
    location="us-central1"
)

# 앱 래핑
app = AdkApp(agent=root_agent)

# Vertex AI에 배포
remote_app = app.deploy(
    display_name="travel-coordinator",
    requirements=["google-adk>=1.0.0", "requests"]
)

print(f"배포 완료: {remote_app.resource_name}")

# 배포된 에이전트 호출
async for event in remote_app.async_stream_query(
    user_id="user-123",
    message="도쿄 여행 계획 세워줘"
):
    if event.get("is_final"):
        print(event["content"])

---

ADK vs 다른 프레임워크 선택 기준

Google ADK 써야 할 때:
✅ Google Cloud / Vertex AI 이미 사용 중
✅ 멀티모달 (이미지, 오디오, 영상) 처리 필요
✅ A2A 프로토콜로 타 프레임워크 에이전트와 통신
✅ 처음부터 프로덕션 배포 염두
✅ Java/Go/TypeScript 팀

LangGraph 써야 할 때:
✅ 복잡한 조건 분기, 루프, 병렬 처리
✅ 장기 실행 에이전트 (체크포인트 중요)
✅ 디버깅/타임트래블 기능 필요
✅ 모델 벤더 종속 피하고 싶음

CrewAI 써야 할 때:
✅ 빠른 프로토타입
✅ 역할 기반 팀 구성이 직관적
✅ MCP 툴 생태계 최대 활용
✅ 커뮤니티 샘플 코드 많이 필요

OpenAI Agents SDK 써야 할 때:
✅ OpenAI 스택 전용
✅ 단순한 핸드오프 패턴
✅ 가장 빠른 시작