구글 ADK란? — ChatGPT와 결정적으로 다른 이유

구글 ADK(Agent Development Kit)는 AI 에이전트 및 멀티에이전트 시스템을
풀 스택으로 개발·배포할 수 있도록 설계된 구글의 오픈소스 프레임워크입니다.
2025년 4월 Google Cloud NEXT에서 처음 발표된 이후, 2026년 3월 현재 v0.6까지 빠르게
업데이트되며 전 세계 개발자들의 주목을 받고 있습니다.

ChatGPT·Claude 같은 AI 챗봇은 사람이 직접 입력하고 결과를 받는 ‘단방향 대화 모델’입니다.
반면 ADK로 만든 AI 에이전트는 스스로 계획을 세우고, 도구를 호출하고,
하위 에이전트에게 작업을 위임하며 자율적으로 목표를 달성합니다.
쉽게 말해 ‘지시를 내리는 사람(ChatGPT 사용자)’이 아니라
‘직접 일하는 직원(ADK 에이전트)’을 프로그래밍하는 것입니다.

ADK가 특별한 3가지 이유

▲ 목차로 돌아가기

구글 ADK 설치 & 첫 에이전트 5분 세팅

구글 ADK 사용법의 시작은 놀라울 정도로 단순합니다.
Python 3.10 이상과 pip만 있으면 5분 안에 첫 에이전트를 실행할 수 있습니다.
아래 순서를 그대로 따라 하면 로컬 웹 UI에서 에이전트와 실제로 대화할 수 있습니다.

Step 1: 가상환경 생성 및 ADK 설치

# 가상환경 생성 (권장)
python -m venv .venv
# 활성화 (macOS/Linux)
source .venv/bin/activate
# 활성화 (Windows)
.venv\Scripts\activate.bat
# ADK 설치
pip install google-adk

Step 2: 에이전트 프로젝트 생성

adk create my_agent

명령어 실행 후 my_agent/ 폴더가 생성되며
내부에 agent.py, .env,
__init__.py 세 파일이 자동으로 만들어집니다.

Step 3: Google AI Studio에서 API 키 발급 후 .env 설정

# my_agent/.env 파일에 저장
GOOGLE_API_KEY="여기에_발급받은_API_키_입력"

API 키는
Google AI Studio 키 발급 페이지에서 무료로 생성할 수 있습니다.
현재 Gemini API는 무료 티어(분당 15회 요청)를 제공하므로
처음 학습하는 데 비용이 들지 않습니다.

Step 4: agent.py 작성 — 현재 시간 알려주는 첫 에이전트

from google.adk.agents.llm_agent import Agent
# 커스텀 도구 정의
def get_current_time(city: str) -> dict:
"""지정한 도시의 현재 시간을 반환합니다."""
return {"status": "success", "city": city, "time": "17:23 KST"}
# 루트 에이전트 정의
root_agent = Agent(
model='gemini-3-flash-preview',
name='root_agent',
description="도시별 현재 시간을 알려주는 에이전트입니다.",
instruction="사용자가 도시를 물으면 get_current_time 도구를 사용하세요.",
tools=[get_current_time],
)

Step 5: 웹 UI로 실행

# my_agent/ 폴더가 있는 상위 디렉토리에서 실행
adk web --port 8000

브라우저에서 http://localhost:8000으로 접속하면
에이전트와 채팅할 수 있는 웹 인터페이스가 열립니다.
왼쪽 상단에서 에이전트를 선택한 뒤 “서울의 현재 시간은?” 같은 질문을 입력해 보세요.

▲ 목차로 돌아가기

핵심 구조 해부 — LlmAgent·Tool·Session

구글 ADK 사용법을 제대로 익히려면 프레임워크가 내부적으로 어떻게 작동하는지
이해해야 합니다. ADK는 크게 세 가지 핵심 개념으로 이루어집니다.

① LlmAgent — 에이전트의 두뇌

LlmAgent는 LLM을 추론 엔진으로 사용하는 기본 에이전트 클래스입니다.
model에 어떤 LLM을 쓸지,
instruction에 역할을 정의하고,
tools에 사용할 함수를 넘겨주면 됩니다.
description 필드는 멀티에이전트 환경에서 LLM이 작업을 위임할 때
어느 에이전트에게 넘길지 판단하는 핵심 기준이 되므로, 명확하게 작성하는 것이 무엇보다 중요합니다.

② Tool — 에이전트의 손발

Tool은 에이전트가 실제 세계와 상호작용하는 수단입니다.
Python 함수를 정의하기만 하면 ADK가 함수의 docstring을 읽어
LLM에게 “언제, 어떻게 이 도구를 쓸지” 자동으로 알려줍니다.
구글 검색(google_search)이나 코드 실행
같은 사전 제작된 도구도 기본 제공되며, MCP(Model Context Protocol) 도구나
LangChain·LlamaIndex 라이브러리도 연동할 수 있습니다.

③ Session & State — 에이전트의 기억

에이전트들이 서로 데이터를 주고받을 때 사용하는 공유 저장소가 바로
session.state입니다.
에이전트 A가 output_key=”result”로 결과를 저장하면,
에이전트 B는 프롬프트에서 {result}로 그 값을 즉시 읽어 올 수 있습니다.
이를 통해 복잡한 파이프라인에서도 별도의 DB 없이 에이전트 간 통신이 가능합니다.

▲ 목차로 돌아가기

멀티에이전트 시스템 구축 — Sequential·Parallel·Loop

구글 ADK의 진가는 단일 에이전트를 넘어 여러 에이전트가 협력하는
멀티에이전트 시스템(MAS)을 구축할 때 드러납니다.
ADK는 세 가지 워크플로 에이전트를 제공하며, 이를 조합하면 거의 모든 비즈니스 로직을
AI 에이전트로 구현할 수 있습니다.

SequentialAgent — 순서대로 처리하는 파이프라인

SequentialAgent는 서브 에이전트를 등록된 순서대로 실행합니다.
앞 에이전트의 출력이 session.state를 통해
자동으로 다음 에이전트에 전달됩니다.
데이터 수집 → 분석 → 보고서 작성처럼 순서가 중요한 작업에 이상적입니다.

from google.adk.agents import SequentialAgent, LlmAgent
step1 = LlmAgent(name="DataFetcher",
instruction="최신 AI 뉴스를 수집하세요.",
output_key="news_data")
step2 = LlmAgent(name="Summarizer",
instruction="{news_data}를 3줄로 요약하세요.")
pipeline = SequentialAgent(name="NewsPipeline", sub_agents=[step1, step2])

ParallelAgent — 동시에 처리하는 병렬 실행

ParallelAgent는 서브 에이전트를 동시에 실행합니다.
날씨 정보·뉴스·주가를 동시에 수집한 뒤 하나의 보고서로 합치는 식으로 활용할 수 있으며,
처리 시간을 획기적으로 단축할 수 있습니다.
병렬로 실행되는 에이전트들은 같은 session.state를 공유하므로,
서로 다른 output_key를 사용해야 데이터 충돌을 피할 수 있습니다.

from google.adk.agents import ParallelAgent, LlmAgent
weather = LlmAgent(name="WeatherAgent", output_key="weather")
news    = LlmAgent(name="NewsAgent",    output_key="news")
stocks  = LlmAgent(name="StockAgent",  output_key="stocks")
gatherer = ParallelAgent(name="MorningBrief",
sub_agents=[weather, news, stocks])

LoopAgent — 조건을 만족할 때까지 반복

LoopAgent는 서브 에이전트를 반복 실행합니다.
특정 조건(escalate=True)이 충족되거나
max_iterations 횟수에 도달하면 루프가 종료됩니다.
품질 검수를 통과할 때까지 콘텐츠를 개선하거나,
API 폴링처럼 상태가 바뀔 때까지 대기하는 자동화 시나리오에 활용할 수 있습니다.

▲ 목차로 돌아가기

실전 활용 — MCP 도구 연동과 Vertex AI 배포

에이전트를 단순히 로컬에서 테스트하는 것을 넘어,
실제 서비스 수준으로 올리려면 두 가지가 필요합니다.
바로 강력한 외부 도구 연동과 안정적인 배포 인프라입니다.

MCP(Model Context Protocol) 도구 통합

ADK는 MCP(Model Context Protocol)를 기본 지원합니다.
MCP는 AI 모델이 외부 툴·데이터 소스와 통신하는 표준 프로토콜로,
2026년 현재 수백 개의 MCP 서버가 커뮤니티에 공개되어 있습니다.
ADK 에이전트에 MCP 서버를 연결하면 웹 검색, 파일 시스템 접근, GitHub 통합,
데이터베이스 조회 등 거의 모든 작업을 에이전트가 직접 수행할 수 있습니다.

from google.adk.tools.mcp_tool.mcp_toolset import MCPToolset, StdioServerParameters
# MCP 서버 연결 예시 (파일시스템 MCP)
mcp_tools = MCPToolset(
connection_params=StdioServerParameters(
command="npx",
args=["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
)
)
agent = LlmAgent(
model="gemini-2.0-flash",
name="file_agent",
tools=[mcp_tools],
instruction="파일을 읽고 내용을 요약해 주세요."
)

Vertex AI Agent Engine으로 프로덕션 배포

로컬 개발이 완료됐다면 Vertex AI Agent Engine에 배포하는 것이 가장 권장되는 경로입니다.
완전 관리형 서버리스 환경으로 오토스케일링, 모니터링, 로깅이 자동으로 제공됩니다.
배포 명령어는 단 두 줄로 끝납니다.

# Vertex AI에 배포
adk deploy cloud_run \
--project=YOUR_PROJECT_ID \
--region=asia-northeast3 \
my_agent

Cloud Run을 통해 컨테이너 형태로도 배포할 수 있으며,
Apigee를 통한 기존 API 자산 연동, AlloyDB·BigQuery와의 직접 데이터 접근도 지원합니다.
개인 개발자라면 Cloud Run의 무료 티어(월 200만 요청)를 활용해
사실상 무료로 에이전트를 운영할 수 있다는 점도 실용적인 장점입니다.

▲ 목차로 돌아가기

ADK vs LangChain vs CrewAI — 선택 기준 완전 정리

AI 에이전트 프레임워크가 넘쳐나는 2026년, 어떤 것을 선택해야 할지
혼란스러운 분들이 많습니다. 필자가 직접 세 프레임워크를 실제 프로젝트에 써본 기준으로
명확하게 정리해 드리겠습니다.

▲ 목차로 돌아가기

초보자가 가장 많이 막히는 오류 3가지와 해결법

구글 ADK를 처음 접하는 분들이 실습 도중 공통적으로 겪는 오류가 있습니다.
커뮤니티와 공식 문서를 종합해 가장 빈번한 3가지를 정리했습니다.

오류 1: ModuleNotFoundError: No module named ‘google.adk’

가상환경 밖에서 설치하거나, 가상환경을 활성화하지 않고 실행할 때 발생합니다.
source .venv/bin/activate(macOS) 또는
.venv\Scripts\activate.bat(Windows)로
반드시 가상환경을 활성화한 뒤 pip install google-adk를
다시 실행하세요.

오류 2: 에이전트 위임이 작동하지 않음

멀티에이전트 구조에서 루트 에이전트가 서브 에이전트에게 작업을 넘기지 않는 경우입니다.
가장 흔한 원인은 서브 에이전트의 description 필드가
모호하게 작성된 것입니다. LLM은 이 설명을 기준으로 위임 여부를 결정하므로,
“사용자가 ‘안녕’이라고 말할 때만 담당”처럼 매우 구체적으로 작성해야 합니다.

오류 3: adk web 실행 시 에이전트가 보이지 않음

adk web 명령어는 반드시
my_agent/ 폴더의 상위 디렉토리에서 실행해야 합니다.
에이전트 폴더 내부에서 실행하면 정상적으로 에이전트를 인식하지 못합니다.
예를 들어 구조가 agents/my_agent/라면,
agents/ 위치에서 실행하면 됩니다.

▲ 목차로 돌아가기