Google ADK를 MCP 클라이언트로 활용한 AI 에이전트 구축 심층 분석

Cook AI

Google ADK를 MCP 클라이언트로 활용한 AI 에이전트 구축 심층 분석

앤써니킴 2025. 5. 22. 22:16

이 글은 Arjun Prabhulal님의 동의 하에 그분의 깊이 있는 분석과 자료를 사용하여 작성했습니다. 원문은 [Building AI Agents with Google's Agent Development Kit(ADK) as MCP Client - A Deep Dive]에서 확인하실 수 있습니다. 독자 여러분께 더욱 유익한 정보를 전달할 수 있도록 귀한 내용을 공유해 주신 Arjun Prabhulal님께 다시 한번 감사드립니다.

Google Cloud Next ’ 25에서는 여러 획기적인 발표가 있었습니다. 지난해에는 GenAI(챗봇)와 Vertex AI가 주목받았다면, 올해의 주제는 명확했습니다. 바로 에이전트, 에이전트, 그리고 더 많은 에이전트였죠. Agent Development Kit (ADK)부터 에이전트 간(A2A) 프로토콜, AgentSpace, 그리고 Google의 주력 LLM인 Gemini 2.5 Pro Preview까지 다양한 내용이 다뤄졌습니다.

지난 글에서는 MCP 클라이언트 역할을 하는 Model Context Protocol(MCP)을 사용하여 Gemini LLM을 통합하는 방법을 살펴보았습니다. 이를 통해 외부 API 및 시스템과의 구조화되고 도구가 보강된 상호작용이 가능해지는 것을 확인했죠. 또한 MCP의 핵심 개념, 사용 사례 및 데모에 대해서도 논의했습니다.

이번 글에서는 ADK 에이전트를 MCP 클라이언트로 활용하여 기존 MCP 서버를 사용하는 데 중점을 둘 것입니다. 이를 통해 외부 MCP 기반 도구가 제공하는 기능을 사용하여 도구를 호출할 수 있게 됩니다. 코드 구현에 앞서 ADK의 핵심 개념에 대해 먼저 논의해 보겠습니다.

ADK (Agent Development Kit)란 무엇인가요?

Agent Development Kit (ADK)는 지능형 AI 에이전트를 구축, 평가 및 배포하기 위한 오픈 소스, 코드 우선(code-first) Python 툴킷입니다.

ADK를 사용하면 개발자는 간단한 단일 에이전트 작업부터 복잡한 다중 에이전트 오케스트레이션에 이르기까지, 모듈식이고 확장 가능한 프레임워크 내에서 에이전트 워크플로우를 생성할 수 있습니다.

ADK에서의 에이전트란?

에이전트는 특정 목표를 달성하도록 설계된 자율적이고 독립적인 실행 단위입니다. 에이전트는 다음과 같은 작업을 수행할 수 있습니다.

작업 수행
사용자와의 상호작용
외부 도구 활용
복잡한 워크플로우를 완료하기 위한 다른 에이전트와의 협업

더 자세한 정보는 ADK 공식 문서에서 확인하실 수 있습니다.

핵심 에이전트 카테고리

ADK는 다음 세 가지 주요 에이전트 유형을 제공합니다.

LLM 에이전트 (예: LlmAgent, Agent): LLM을 사용하여 이해, 추론, 계획 및 행동합니다. 동적이고 언어 중심적인 작업에 이상적입니다.
워크플로우 에이전트 (예: SequentialAgent, ParallelAgent, LoopAgent): 흐름 제어를 위해 LLM에 의존하지 않고 예측 가능한 패턴으로 다른 에이전트를 조정합니다. 구조화되고 반복 가능한 프로세스에 가장 적합합니다.
커스텀 에이전트: BaseAgent를 확장하여 사용자 지정 로직, 특수 워크플로우 또는 고유한 도구 통합을 가능하게 합니다. 고급 맞춤형 설루션에 적합합니다.

이 글에서는 MCPTools와 함께 LLM 에이전트 유형을 사용할 예정입니다.

ADK 콘텍스트에서의 도구(Tools)란?

도구는 AI 에이전트에게 부여된 특정 기능으로, 기본적인 텍스트 생성 및 추론을 넘어 외부 세계와 상호작용하고 작업을 수행할 수 있게 해 줍니다.

일반적으로 도구는 특정 작업을 수행하도록 설계된 모듈식 코드 구성 요소(예: Python 함수, 클래스 메서드 또는 다른 에이전트)입니다.

에이전트는 도구를 어떻게 사용하나요?

에이전트는 함수 호출(function-calling) 메커니즘을 통해 동적으로 도구를 활용합니다. 여기서 LLM은 콘텍스트를 추론하고, 생성된 입력으로 적절한 도구를 선택 및 호출하며, 결과를 관찰하고, 출력을 다음 작업이나 응답에 통합합니다. 쉽게 말해서, 에이전트가 필요할 때 적절한 연장을 꺼내 쓰는 것과 비슷하다고 생각하시면 됩니다.

ADK의 도구 유형

ADK는 여러 유형의 도구를 지원합니다.

함수 도구 (Function Tools): 애플리케이션의 고유한 로직 및 워크플로우를 위해 특별히 제작된 사용자 지정 도구입니다.
- 함수/메서드: 도구로 등록된 표준 동기식 Python 함수(def) 또는 클래스 메서드입니다.
- 에이전트-애즈-툴 (Agents-as-Tools): 모듈식 동작을 위해 부모 에이전트 내에서 호출 가능한 도구로 특수 에이전트를 사용합니다.
- 장기 실행 함수 도구 (Long-Running Function Tools): 비동기 또는 시간이 많이 걸리는 작업을 위해 설계된 도구입니다.
내장 도구 (Built-in Tools): 웹 검색, 코드 실행 또는 RAG와 같은 작업을 위해 프레임워크에 포함된 미리 정의된 도구입니다.
타사 도구 (Third-Party Tools): LangChain 또는 CrewAI와 같은 인기 있는 생태계의 도구를 쉽게 통합할 수 있습니다.

아키텍처

이전 글과 동일한 아키텍처를 사용하며, 여기에 추가로 ADK를 활용합니다.

구현

이제 ADK, MCP, 그리고 Gemini AI를 사용하여 이 파이프라인을 구축하는 과정을 주요 구현 단계로 나누어 자세히 살펴보겠습니다.

사전 준비 사항

Python 3.8+ 설치
API 키를 통한 Google Gemini Generative AI 액세스 권한
유효한 SerpAPI 키 (실시간 항공편 데이터를 가져오는 데 사용)

1단계: 가상 환경 설정

다음 명령어를 사용하여 의존성을 설치합니다.

# 가상 환경 설정 (mac 또는 Unix)
python -m venv venv && source venv/bin/activate

# 에이전트 개발 키트 설치
pip install google-adk

# MCP 서버 설치
pip install mcp-flight-search

# GenAI Python SDK 설치
pip install google-genai

google-adk: 에이전트 구축을 위한 Google의 에이전트 개발 키트입니다.
google-genai: Generative AI 모델(예: Gemini)과 상호작용하기 위한 Google 라이브러리입니다.
mcp-flight-search: MCP 라이브러리를 사용하여 SerpAPI를 통해 항공편을 검색하는 MCP 서버입니다.

환경 변수 설정:

여기서 중요한 차이점이 있습니다. ADK에서는 GEMINI_API_KEY 대신 GOOGLE_API_KEY를 사용해야 합니다!

export GOOGLE_API_KEY="your-google-api-key"
export SERP_API_KEY="your-serpapi-key"

2단계: MCP 서버 설치 — mcp-flight-search

Gemini가 실제 API와 상호작용할 수 있도록 MCP 호환 서버를 사용합니다.

이 글에서는 mcp-flight-search를 사용합니다. 이는 FastMCP를 사용하여 구축된 경량 MCP 서버로, SerpAPI를 사용하여 실시간 항공편 데이터를 검색하는 도구를 노출합니다.

설치된 MCP 서버 패키지를 확인하세요: https://pypi.org/project/mcp-flight-search/

# PyPI에서 설치 (1단계에서 이미 설치됨)
pip install mcp-flight-search

3단계: MCP 클라이언트로서의 ADK 이해하기

from google.adk.agents.llm_agent import LlmAgent
from google.adk.runners import Runner
from google.adk.sessions import InMemorySessionService
from google.adk.tools.mcp_tool.mcp_toolset import MCPToolset, StdioServerParameters

LlmAgent: ADK의 핵심 구성 요소로, 애플리케이션의 "사고" 부분을 담당합니다. 대규모 언어 모델(LLM)의 능력을 활용하여 추론, 자연어 이해, 의사 결정, 응답 생성 및 도구와의 상호작용을 수행합니다.

Runner: 에이전트의 라이프사이클 동안 다양한 구성 요소 간의 상호작용을 조정하는 역할을 합니다. Runner는 아티팩트, 세션 및 메모리 서비스에 대한 인메모리 구현을 사용하여 에이전트 실행을 위한 경량의 독립적인 환경을 제공합니다.

InMemorySessionService: ADK의 SessionService 인터페이스 구현체로, 대화 기록, 상태, 메타데이터와 같은 모든 세션 데이터를 애플리케이션 메모리에 직접 저장합니다. 즉, 애플리케이션이 중지되거나 다시 시작되면 모든 세션 정보가 손실됩니다. 사용자가 AI 에이전트와 상호작용하면 대화를 추적하기 위해 Session 객체가 생성됩니다.

MCPToolset: ADK 내의 클래스로, AI 에이전트가 외부 MCP 서버에 연결할 수 있도록 합니다. 이러한 서버는 에이전트가 특정 작업을 수행하는 데 사용할 수 있는 API 또는 서비스와 같은 도구를 노출합니다. MCPToolset을 사용하면 에이전트는 이러한 외부 도구를 원활하게 검색, 호출 및 관리할 수 있습니다.

StdioServerParameters: 에이전트가 표준 입력/출력 스트림을 통해 MCP 서버에 연결하는 방법을 지정하는 데 사용되는 구성 클래스입니다. 이는 MCP 서버가 콘솔을 통해 통신하는 로컬 프로세스일 때 특히 유용합니다.

MCPToolSet과 StdioServerParameters의 연동 방식

MCPToolset과 StdioServerParameters를 함께 사용하면 ADK 에이전트는 다음을 수행할 수 있습니다.

연결 설정: StdioServerParameters를 사용하여 MCP 서버 프로세스를 시작하는 데 필요한 명령과 인수를 정의합니다.
사용 가능한 도구 검색: MCPToolset은 MCP 서버에 연결하고 에이전트가 사용할 수 있는 사용 가능한 도구 목록을 검색합니다.
에이전트에 도구 통합: 검색된 도구는 ADK 에이전트와 호환되는 형식으로 조정되어 에이전트 실행 중에 원활하게 호출할 수 있도록 합니다.
연결 수명 주기 관리: MCPToolset은 MCP 서버에 대한 연결 설정 및 해제를 처리하여 리소스가 적절하게 관리되도록 합니다.

4단계: MCP 서버에 연결하기

StdioServerParameters는 MCPToolset을 사용하여 비동기적으로 도구를 나열하고 수신 대기하기 위한 MCP 구성을 정의합니다.

# --- 1단계: MCP 서버에서 도구 가져오기 ---
async def get_tools_async():
    """Flight Search MCP 서버에서 도구를 가져옵니다."""
    print("MCP Flight Search 서버에 연결 시도 중...")
    server_params = StdioServerParameters(
        command="mcp-flight-search",
        args=["--connection_type", "stdio"],
        env={"SERP_API_KEY": os.getenv("SERP_API_KEY")},
    )

    tools, exit_stack = await MCPToolset.from_server(
        connection_params=server_params
    )
    print("MCP Toolset이 성공적으로 생성되었습니다.")
    return tools, exit_stack

5단계: ADK에서 에이전트 생성하기

위에서 언급했듯이, 우리는 애플리케이션의 사고 부분을 담당하는 Llm 에이전트를 사용하고 있습니다.

# --- 2단계: ADK 에이전트 생성 정의 ---
async def get_agent_async():
    """MCP 서버의 도구를 갖춘 ADK 에이전트를 생성합니다."""
    tools, exit_stack = await get_tools_async()
    print(f"MCP 서버에서 {len(tools)}개의 도구를 가져왔습니다.")

    # 예제 구조와 일치하는 LlmAgent 생성
    root_agent = LlmAgent(
        model=os.getenv("GEMINI_MODEL", "gemini-1.5-pro-preview-0514"), # 원래는 gemini-2.5-pro-preview-03-25 였으나, 2.5 Pro가 아직 Preview 일 수 있어 1.5 Pro로 변경 예시
        name='flight_search_assistant',
        instruction='프롬프트에 따라 사용 가능한 도구를 사용하여 항공편을 검색하도록 도와주세요. 반환 날짜가 지정되지 않은 경우 편도 여행에는 빈 문자열을 사용하세요.',
        tools=tools,
    )

    return root_agent, exit_stack

6단계: 에이전트 생성, 세션 관리 및 Runner와의 오케스트레이션 통합

async def async_main():
    # 서비스 생성
    session_service = InMemorySessionService()

    # 세션 생성
    session = session_service.create_session(
        state={}, app_name='flight_search_app', user_id='user_flights'
    )

    # 사용자 프롬프트 정의
    query = "Find flights from Atlanta to Las Vegas 2025-05-05"
    print(f"사용자 질문: '{query}'")

    # 입력을 types.Content 형식으로 변환
    content = types.Content(role='user', parts=[types.Part(text=query)])

    # 에이전트 및 exit_stack 가져오기
    root_agent, exit_stack = await get_agent_async()

    # Runner 생성
    runner = Runner(
        app_name='flight_search_app',
        agent=root_agent,
        session_service=session_service,
    )

    print("에이전트 실행 중...")
    events_async = runner.run_async(
        session_id=session.id,
        user_id=session.user_id,
        new_message=content
    )

    # 이벤트 처리
    final_content = None
    async for event in events_async:
        print(f"수신된 이벤트: {event}")


    # 항상 리소스 정리
    print("MCP 서버 연결 닫는 중...")
    await exit_stack.aclose()
    print("정리 완료.")

7단계: 데모

MCP 클라이언트의 사용자 질문:

query = "2025년 5월 5일 애틀랜타에서 라스베이거스로 가는 항공편 찾아줘"

표준 로깅을 사용한 데모

디버그 로깅을 사용한 데모

MCP와 ADK 통합 시 주요 고려 사항

MCP 대 ADK
- MCP는 AI 모델이 외부 도구 및 데이터 소스와 상호작용하는 방식을 표준화하는 오픈 프로토콜입니다.
- ADK는 AI 에이전트를 구축하고 배포하기 위한 Python 기반 프레임워크입니다.
- MCPToolset: ADK 에이전트가 MCP 서버에서 노출된 도구를 사용할 수 있도록 하여 MCP와 ADK를 연결합니다.
도구 유형 및 통합
- ADK 도구: ADK 에이전트 내에서 직접 사용하도록 설계된 Python 객체(예: BaseTool, FunctionTool)입니다.
- MCP 도구: MCP 서버에서 노출하는 기능으로, MCPToolset이 ADK 에이전트 내에서 사용할 수 있도록 조정합니다.
- 타사 도구: LangChain 및 CrewAI와 같은 라이브러리는 LangchainTool 및 CrewaiTool과 같은 래퍼를 사용하여 ADK에 통합할 수 있는 도구를 제공합니다.
비동기 아키텍처
- ADK와 MCP Python 라이브러리 모두 Python의 asyncio 프레임워크를 기반으로 구축되었습니다.
- 논블로킹(non-blocking) 작업을 보장하려면 도구 구현 및 서버 핸들러가 비동기(async def)여야 합니다.
MCP의 상태 저장 세션 (Stateful Sessions)
- MCP는 일반적인 상태 비저장(stateless) REST API와 달리 클라이언트와 서버 간에 영구적이고 상태를 저장하는 연결을 설정합니다.
- 이러한 상태 저장 특성으로 인해 상호작용 전반에 걸쳐 콘텍스트를 유지할 수 있지만 신중한 세션 관리가 필요합니다.
배포 고려 사항
- MCP 연결의 영구적인 특성은 특히 여러 사용자를 처리하는 원격 서버의 경우 확장성 및 배포에 어려움을 초래할 수 있습니다.
- 인프라 고려 사항에는 연결 안정성을 유지하기 위한 로드 밸런싱 및 세션 어피니티(session affinity)가 포함됩니다.
ADK에서 MCP 연결 관리
- MCPToolset은 ADK 내에서 MCP 연결의 수명 주기를 관리합니다.
- exit_stack을 사용하면 에이전트 실행이 완료될 때 연결이 올바르게 종료되도록 보장합니다.

Python으로 MCP 서버를 구축하려면 model-context-protocol 라이브러리를 사용하세요.

문제 해결 팁 💡

현업 개발자들 사이에서도 자주 마주치는 문제들과 해결책을 공유해 드립니다.

ValueError: Missing key inputs argument! To use the Google AI API,provide (`api_key`) arguments. To use the Google Cloud API, provide (`vertexai`, `project` & `location`) arguments.

기본적으로 ADK 라이브러리는 GCP Project Vertex AI, 위치 및 VertexAI 구성을 예상합니다. 오류 메시지에 환경 변수 누락이 명확하게 표시되지 않을 수 있으니 GEMINI_API_KEY 대신 GOOGLE_API_KEY를 사용했는지 다시 한번 확인해 보세요.

해결책: 환경 변수를 GOOGLE_API_KEY로 설정합니다.

잦은 429 비율 제한(rate-limit) 오류 및 500 내부 서버 오류

"Gemini API '무료 등급'은 테스트 목적으로 더 낮은 비율 제한으로 API 서비스를 통해 제공됩니다."라는 공식 문서 내용처럼, 무료 등급의 한도에 도달했을 가능성이 큽니다.
해결책: Gemini 2 Flash와 같이 다른 모델로 전환하거나 유료 등급 사용을 고려해 보세요.

google.genai.errors.ClientError: 429 RESOURCE_EXHAUSTED. {'error': {'code': 429, 'message': 'You exceeded your current quota, please check your plan and billing details. For more information on this error, head to: https://ai.google.dev/gemini-api/docs/rate-limits.', 'status': 'RESOURCE_EXHAUSTED', 'details': [{'@type': 'type.googleapis.com/google.rpc.QuotaFailure', 'violations': [{'quotaMetric': 'generativelanguage.googleapis.com/generate_content_free_tier_requests', 'quotaId': 'GenerateRequestsPerDayPerProjectPerModel-FreeTier', 'quotaDimensions': {'model': 'gemini-2.0-pro-exp', 'location': 'global'}, 'quotaValue': '25'}]}, {'@type': 'type.googleapis.com/google.rpc.Help', 'links': [{'description': 'Learn more about Gemini API quotas', 'url': 'https://ai.google.dev/gemini-api/docs/rate-limits'}]}, {'@type': 'type.googleapis.com/google.rpc.RetryInfo', 'retryDelay': '27s'}]}}

An error occurred during execution: 500 INTERNAL. {'error': {'code': 500, 'message': 'An internal error has occurred. Please retry or report in https://developers.generativeai.google/guide/troubleshooting', 'status': 'INTERNAL'}}

Gemini API 비용 청구

Gemini 2.5 Pro Preview — Google 문서에 따르면, Gemini API "무료 등급"은 테스트 목적으로 더 낮은 비율 제한으로 API 서비스를 통해 제공됩니다. Gemini API "유료 등급"은 더 높은 비율 제한, 추가 기능 및 다른 데이터 처리 방식을 제공합니다.

공식 문서 참조

Agent Development Kit (ADK) 문서: Gemini 및 Google과 통합된 오픈 소스 AI 에이전트 프레임워크에 대한 전체 가이드입니다.
ADK의 LLM 에이전트: ID, 지침, 도구 정의 및 고급 구성을 포함한 LLM 에이전트 구현에 대한 자세한 문서입니다.
ADK와 MCP 도구: MCP 서버에 연결하기 위해 ADK를 MCP 클라이언트로 사용하는 방법에 대한 구체적인 지침입니다.

GitHub 저장소

이 튜토리얼에 사용된 모든 코드는 제 GitHub에서 액세스 할 수 있습니다.

GitHub - arjunprabhulal/adk-python-mcp-client: Demo of ADK (Agent Development Kit) as an MCP (Model Context Protocol) client for

Demo of ADK (Agent Development Kit) as an MCP (Model Context Protocol) client for flight search capabilities. - arjunprabhulal/adk-python-mcp-client

github.com

결론

지금까지 오픈소스 ADK를 사용하여 Google Gemini LLM을 MCP 클라이언트로 활용하는 Model Context Protocol(MCP) 기반의 에이전트 설정 도우미를 구축하는 방법을 자세히 살펴보았습니다.

'Cook AI' 카테고리의 다른 글

구글 A2A 프로토콜, ADK, MCP로 멀티 에이전트 AI 앱 만들기 (1)	2025.05.23
Model Context Protocol(MCP) 과 구글 Gemini 2.5 Pro — 심층 분석 (2)	2025.05.21
Ollama와 Gemma3를 활용한 함수 호출 (8)	2025.05.20
AI 개발자라면 놓칠 수 없는 기회! AI 스타터팩 -무료 및 할인 (2)	2025.05.19
Supabase API Key 생성하기 (2)	2025.05.16

현재글Google ADK를 MCP 클라이언트로 활용한 AI 에이전트 구축 심층 분석

슬기로운 개발자의 생활

개발자 여러분과 함께 성장하고, 새로운 지식을 공유하는 공간입니다. 댓글을 통해 질문을 남기거나, 의견을 공유해 주세요. 서로의 경험을 나누며 더 나은 개발자가 되는 여정에 함께해요!

model context protocol, agent, python, OpenAI, 기상청, v0, Open API, cursor ai, Rocky Linux, 개발생산성, tool, AI, 메일, Cursor, LLM, qmail, langchain, MCP, function calling, claude desktop,

Today :
Yesterday :

슬기로운 개발자의 생활