ADK 튜토리얼 (1): ADK란? & 간단하게 멀티 에이전트 시스템 구현

ADK(Agent Development Kit)란?

최근 AI 에이전트(agentic AI) 패러다임이 본격화되면서, 단순히 챗봇 수준을 넘어 스스로 판단하고 도구(tool)를 활용하며, 여러 에이전트가 협업하는 시스템이 각광받고 있습니다. 이런 흐름 속에서 Agent Development Kit(이하 ADK)은 구글에서 오픈소스로 공개한 프레임워크로, 에이전트 개발을 소프트웨어 개발 방식으로 보다 구조화하고, 확장 가능하며 배포 가능한 수준까지 끌어올리고자 만들어진 도구입니다. (Google GitHub)

저는 TripFlow라는 저의 제품에서 사용되는 멀티 에이전트 시스템에 ADK 프레임워크를 사용하여 시스템을 구현하고, 현재 개발 중입니다.

왜 ADK인가?

개발자 관점에서 ADK가 갖는 주요 장점은 다음과 같습니다:

• 모델·배포 프레임워크 독립성: Gemini 모델을 포함해 다양한 LLM을 쓸 수 있고, 배포도 클라우드나 온프레미스 등 자유롭게 구성할 수 있습니다. (PyPI) 물론, 구글의 프레임워크인만큼, Gemini 모델에 특화된 도구를 더 지원하고, Gemini 모델 사용이 더 쉽게 만들어져 있습니다.
• 에이전트 아키텍처의 구조화: 단일 에이전트 뿐 아니라 여러 에이전트를 조합하는 워크플로우(Sequential, Parallel, Loop 등)를 기본 개념으로 제공합니다. (Google GitHub)
• 에이전트기반 오케스트레이션: LLM 기반의 에이전트(LlmAgent)가 동적으로 하위 에이전트(sub-agents) 를 선택하거나 호출할 수 있는 라우팅(routing) 역할을 수행합니다. 기존의 다른 프레임워크들이 라우팅을 위하여 직접 머신러닝 모델을 학습하거나, LLM을 따로 붙여야하는 점을 그냥 에이전트가 라우팅을 위한 도구를 내장하는 방식으로 제공합니다.
• 툴(tool) 통합 생태계: 검색, 코드 실행, API 호출 등 다양한 외부 시스템을 “도구”로 연결할 수 있어 단일 응답을 넘는 행동(action)도 설계 가능해집니다. (PyPI)
• 배포 및 운영에 가까운 개발 경험: 세션 관리, 콜백(callbacks), 평가(evaluation) 기능이 마련되어 있어, 프로토타입을 넘어 실서비스 수준까지 고려되어 있습니다. (구글 개발자 블로그)

여러 주요한 프레임워크와 비교한 표는 아래와 같습니다.

프레임워크	오케스트레이션 방식 및 특징	장점	주요 제약 및 특징
LangGraph	그래프 기반(Graph) 워크플로우 중심. 노드/엣지로 흐름 설계 가능하며 순차·분기·루프 등 복잡 제어 흐름 지원됨.	매우 유연하고 복잡한 워크플로우 설계에 강함; 상태관리 및 장기 실행 에이전트 지원됨.	러닝커브가 상대적으로 높고 설계 복잡도가 올라갈 수 있음.
CrewAI	다중 에이전트(Multi-Agent) 팀 개념 기반. 역할(role) 기반 에이전트를 구성하고 이들이 상호작용하며 작업 흐름을 설계가능함.	역할 분담·병렬 협업 구조에 적합; 복잡한 작업을 여러 에이전트로 분해 가능	그래프 제어보다는 역할 기반 협업 중심으로 설계됨; 설계 시 역할 정의 및 조율 오버헤드 있을 수 있음
AutoGen	대화(Conversation) 중심의 멀티 에이전트 프레임워크. 에이전트들이 자연어로 상호작용하며 협력함.	대화 중심, 빠른 프로토타이핑 가능; 여러 에이전트 간 상호작용에 적합	워크플로우 제어나 명시적 그래프 설계 부분에서 설계 난이도 존재할 수 있음
ADK	하이브리드 방식: 워크플로우 에이전트(Sequential, Parallel, Loop) 지원 + 동적 라우팅 가능한 에이전트 구조 포함됨.	엔터프라이즈급 설계 가능; 구조화된 워크플로우 및 라우팅 패턴 지원됨	자유로운 그래프 설계보다는 워크플로우 패턴 중심일 수 있음; 커스텀 구조 설계 시 복잡도 증가 가능

제가 ADK를 제 프로젝트의 AI 시스템 메인 프레임워크로 선정한 이유는:
LangGraph는 구조가 유연한 만큼 설계 복잡도와 러닝커브가 높고,
특히 당시 멀티-에이전트 간 통신이나 표준화된 상호작용(A2A) 지원 측면에서는 아직 초기 단계였습니다.
제가 생각하는 시스템은 여러 에이전트가 유기적으로 협력해야 하는 구조입니다. 이 때문에 저는 에이전트 간 상호작용(A2A) 를 안정적으로 지원하는 프레임워크가 필요했습니다.
A2A자체가 구글이 제안한 프로토콜인 만큼, ADK는 바로 이 부분에서 강점을 보였습니다. 서로 다른 시스템의 에이전트들도 쉽게 연결하고 협력할 수 있습니다. 하지만 여전히 초기 단계의 프레임워크라 부족한 부분이 많고, 미래에는 필요에 따라 LangGraph나 CrewAI 등의 구조로 확장하거나, 여러 프레임워크의 에이전트를 혼합 운용하는 방향도 고려하고 있습니다.

---

ADK 핵심 개념 훑어보기

에이전트(Agent)

ADK에서 에이전트는 “목표를 가진 자율 실행 단위”로 정의됩니다. (Google GitHub)

주요 에이전트 종류는 다음과 같습니다:

• LlmAgent (또는 Agent): LLM을 활용해 입력을 이해하고 도구를 호출하거나 응답을 생성하는 역할.
• Workflow Agents: 순차(SequentialAgent), 병렬(ParallelAgent), 반복(LoopAgent) 등의 제어 흐름을 담당하는 구조적 에이전트. (Google GitHub)

툴(Tool)

에이전트는 외부 시스템과 상호작용할 때 “도구” 개념을 사용합니다. 예컨대 검색 API, 코드 실행, DB 쿼리 등이 도구가 될 수 있습니다. ADK는 여러 내장 도구와 통합 가능하며 커스텀 도구도 쉽게 연결됩니다. (PyPI)

다중 Agent 시스템(Multi-Agent System)

여러 에이전트가 협업하거나 위임(delegation)하는 구조를 의미합니다. 단일 에이전트로 처리가 어려운 복잡한 작업을 여러 전문 에이전트로 나눠 처리할 수 있도록 설계되어 있습니다. (Google Cloud)

배포·세션·콜백 등

ADK는 단순히 코드 작성만이 아니라, 세션 관리, 메모리 서비스, 콜백(before/after 모델·도구 호출) 등 운영 측면도 고려되어 있습니다. 여전히 아직 부족한 점들이 이런 부분에서 보이지만 많은 발전 가능성이 보입니다.

---

환경 설정 및 Single Agent 구현/디버깅

이제 실제로 간단히 “싱글 에이전트(Single Agent)”를 구현해 보겠습니다. 이후에 멀티 에이전트 구조로 확장하는 흐름으로 연결됩니다.
이 글에서는 google-adk==1.18.0 을 기준으로 작성되어 있습니다. ADK Docs

1) 환경 준비

테스트 환경: Ubuntu 24.04, uv (python 3.12)

mkdir adk-example
uv init
uv add google-adk
source .venv/bin/activate
adk --version
# adk, version 1.18.0

2) ADK Create

ADK는 create라는 명령어를 통해서, 새로운 에이전트 프로젝트를 생성합니다. (물론 메뉴얼로 폴더 및 파일 생성을 하셔도 됩니다.)

adk create new_agent

위를 실행하면 모델 선택을 할 수 있고, 여기서는 그냥 gemini-2.5-flash를 사용하겠습니다.
또한 GCP 프로젝트까지 확장하지는 않을거라 일단 Google AI (로컬 기반) 으로 선택하겠습니다.

Choose a model for the root agent:
1. gemini-2.5-flash
2. Other models (fill later)
Choose model (1, 2): 1
1. Google AI
2. Vertex AI
Choose a backend (1, 2): 1

Don't have API Key? Create one in AI Studio: https://aistudio.google.com/apikey
Enter Google API key: **여기에 API 키 입력**

Agent created in adk-example/new_agent:
- .env
- __init__.py
- agent.py

터미널 출력의 내용대로 https://aistudio.google.com/apikey 에서 API 키를 생성하여 입력해주시면 완료입니다.
아래와 같은 프로젝트 구조가 형성됩니다.

# tree -L 2
.
├── README.md
├── main.py
├── new_agent
│   ├── __init__.py
│   └── agent.py
├── pyproject.toml
└── uv.lock

3) Single Agent 테스트: Web UI

프로젝트를 생성하면 기본으로 root_agent가 생성되며, 간단한 응답이 가능하도록 구성되어있습니다.
ADK는 root_agent를 필요로 하며, 해당 root_agent가 오케스트레이션 및 라우팅을 담당하는 핵심적인 에이전트입니다.
우리는 adk web 이라는 명령어를 통해 간단하게 Web UI로 테스트 해볼 수 있습니다.

adk web

INFO:     Started server process [1654]
INFO:     Waiting for application startup.

+-----------------------------------------------------------------------------+
| ADK Web Server started                                                      |
|                                                                             |
| For local testing, access at http://127.0.0.1:8000.                         |
+-----------------------------------------------------------------------------+

INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

http://127.0.0.1:8000 또는 localhost/8000 에 접속하면 아래와 같은 에이전트 응답을 간단한 채팅을 통해 테스트 가능한 Chat UI 인터페이스를 확인할 수 있습니다.

질문을 해보면 아래와 같이 gemini-2.5-flash 모델이 간단하게 제공하는 기능들을 보여주는데, 아직 우리가 세팅해준게 따로 없기 때문에 도구는 내장 도구만을 사용하기 때문에 많은 기능을 가지지는 않습니다.

4) Single Agent 테스트: CLI

CLI를 사용하여 테스트를 해볼 수도 있습니다.

adk run new_agent

위를 실행하면 사용자 입력이 가능한 CLI가 실행되고 이를 통해 에이전트의 응답을 확인할 수 있습니다.

4) Single Agent 테스트: 런타임 디버깅

코드를 좀 수정해서, 우리는 adk에서 제공하는 (1.18.0 버전 이후) run_debug로 디버깅이 가능합니다.

# new_agent/agent.py
import asyncio
from dotenv import load_dotenv
from google.adk.agents.llm_agent import Agent
from google.adk.apps import App
from google.adk.runners import InMemoryRunner

root_agent = Agent(
    model='gemini-2.5-flash',
    name='simple_agent',
    description='A helpful assistant for user questions.',
    instruction='Answer user questions to the best of your knowledge',
)

app = App(
    name="agents",
    root_agent=root_agent,
    # Optionally include App-level features:
    # plugins, context_cache_config, resumability_config
)

# In-memory runner 로 빠르게 테스트
runner = InMemoryRunner(app=app)

# 개발 중 quick 테스트
async def main():
    try:  # run_debug() requires ADK Python 1.18 or higher:
        response = await runner.run_debug("안녕하세요, 오늘 날씨 어때요?")
        print(response)

    except Exception as e:
        print(f"An error occurred during agent execution: {e}")

if __name__ == "__main__":
    load_dotenv()
    asyncio.run(main())

위의 코드를 실행시, 응답은 아래와 같습니다.

python new_agent/agent.py

### Created new session: debug_session_id

User > 안녕하세요, 오늘 날씨 어때요?
simple_agent > 안녕하세요! 저는 지금 현재 날씨 정보를 직접 알려드릴 수는 없습니다. 저는 실시간 데이터를 확인할 수 없거든요.

오늘 날씨가 궁금하시면, 스마트폰 날씨 앱이나 인터넷 검색창에 '오늘 날씨' 또는 '서울 날씨'와 같이 검색해 보시면 가장 정확하고 최신 정보를 확인하실 수 있습니다!
[Event(model_version='gemini-2.5-flash', content=Content(
  parts=[
    Part(
      text="""안녕하세요! 저는 지금 현재 날씨 정보를 직접 알려드릴 수는 없습니다. 저는 실시간 데이터를 확인할 수 없거든요.

오늘 날씨가 궁금하시면, 스마트폰 날씨 앱이나 인터넷 검색창에 '오늘 날씨' 또는 '서울 날씨'와 같이 검색해 보시면 가장 정확하고 최신 정보를 확인하실 수 있습니다!"""
    ),
  ],
  role='model'
), grounding_metadata=None, partial=None, turn_complete=None, finish_reason=<FinishReason.STOP: 'STOP'>, error_code=None, error_message=None, interrupted=None, custom_metadata=None, usage_metadata=GenerateContentResponseUsageMetadata(
  candidates_token_count=68,
  prompt_token_count=48,
  prompt_tokens_details=[
    ModalityTokenCount(
      modality=<MediaModality.TEXT: 'TEXT'>,
      token_count=48
    ),
  ],
  thoughts_token_count=77,
  total_token_count=193
), live_session_resumption_update=None, input_transcription=None, output_transcription=None, avg_logprobs=None, logprobs_result=None, cache_metadata=None, citation_metadata=None, invocation_id='e-7f9911d6-65f4-476a-b982-56c3231e0c0c', author='simple_agent', actions=EventActions(skip_summarization=None, state_delta={}, artifact_delta={}, transfer_to_agent=None, escalate=None, requested_auth_configs={}, requested_tool_confirmations={}, compaction=None, end_of_agent=None, agent_state=None, rewind_before_invocation_id=None), long_running_tool_ids=None, branch=None, id='786a2cc1-c908-49ea-9afd-b46152e6037e', timestamp=1762827930.431039)]

위 코드에서는 run_debug(...) 방식으로 매우 간단히 입력→응답 흐름을 확인할 수 있습니다.

이번 글에서는 ADK의 개념과 구조, 그리고 간단한 싱글 이전트 예제를 통해 어떻게 에이전트 시스템을 설계할 수 있는지 살펴봤습니다. 음 글에서는 ADK의 도구(TOOLS) 및 MCP 사용법/소개 및 예제 구현을 다룰 예정입니다. ADK 에이전트를 보다 강력하게 만드는 중요한 요소이니 기대해 주세요.