GENAI124

개요

이 실습에서는 외부 서비스, 데이터 소스, 도구, 애플리케이션 간의 원활한 통합을 지원하는 개방형 표준인 모델 컨텍스트 프로토콜(MCP)을 살펴봅니다. 기존 MCP 서버에서 제공하는 도구를 사용하여 ADK 워크플로를 개선하고 MCP를 ADK 에이전트에 통합하는 방법을 알아봅니다. 또한 커스텀 빌드된 MCP 서버를 통해 load_web_page와 같은 ADK 도구를 노출하여 MCP 클라이언트와의 광범위한 통합을 지원하는 방법을 알아봅니다.

모델 컨텍스트 프로토콜(MCP)이란 무엇인가요?

모델 컨텍스트 프로토콜(MCP)은 Gemini 및 Claude와 같은 대규모 언어 모델(LLM)이 외부 애플리케이션, 데이터 소스, 도구와 통신하는 방식을 표준화하기 위해 설계된 개방형 표준입니다. LLM이 컨텍스트를 가져오고, 작업을 실행하고, 다양한 시스템과 상호작용하는 방식을 간소화하는 범용 연결 메커니즘이라고 생각하면 됩니다.

MCP는 클라이언트-서버 아키텍처를 따르며, 데이터(리소스), 상호작용형 템플릿(프롬프트), 실행 가능한 함수(도구)가 MCP 서버에 의해 노출되고 MCP 클라이언트(LLM 호스트 애플리케이션 또는 AI 에이전트)에 의해 소비되는 방식을 정의합니다.

이 실습에서는 두 가지 기본 통합 패턴을 다룹니다.

• ADK 내에서 기존 MCP 서버 사용: ADK 에이전트는 MCP 클라이언트 역할을 하며 외부 MCP 서버에서 제공하는 도구를 활용합니다.
• MCP 서버를 통한 ADK 도구 노출: ADK 도구를 래핑하는 MCP 서버를 빌드하여 모든 MCP 클라이언트가 ADK 도구에 액세스할 수 있도록 합니다.

목표

이 실습에서는 다음 작업을 수행하는 방법을 배웁니다.

• ADK 에이전트를 MCP 클라이언트로 사용하여 기존 MCP 서버의 도구와 상호작용합니다.
• 자체 MCP 서버를 구성하고 배포하여 ADK 도구를 다른 클라이언트에 노출합니다.
• 표준화된 MCP 통신을 통해 ADK 에이전트를 외부 도구와 연결합니다.
• 모델 컨텍스트 프로토콜을 사용하여 LLM과 도구 간의 원활한 상호작용을 지원합니다.

설정 및 요건

실습 시작 버튼을 클릭하기 전에

다음 안내를 확인하세요. 실습에는 시간 제한이 있으며 일시중지할 수 없습니다. 실습 시작을 클릭하면 타이머가 시작됩니다. 이 타이머에는 Cloud 리소스를 사용할 수 있는 시간이 얼마나 남았는지 표시됩니다.

Qwiklabs 실습을 통해 시뮬레이션이나 데모 환경이 아닌 실제 클라우드 환경에서 직접 실습 활동을 진행할 수 있습니다. 실습 시간 동안 Google Cloud Platform에 로그인하고 액세스하는 데 사용할 수 있는 새로운 임시 사용자 인증 정보가 제공됩니다.

준비할 사항

이 실습을 완료하려면 다음을 준비해야 합니다.

• 표준 인터넷 브라우저(Chrome 브라우저 권장)
• 실습을 완료할 시간

참고: 이미 개인용 GCP 계정이나 프로젝트가 있어도 이 실습에서는 사용하지 마세요.

실습을 시작하고 Google Cloud 콘솔에 로그인하는 방법

1. 실습 시작 버튼을 클릭합니다. 실습 비용을 결제해야 하는 경우 결제 수단을 선택할 수 있는 대화상자가 열립니다. 왼쪽에는 다음과 같은 항목이 포함된 실습 세부정보 창이 있습니다.

   • Google Cloud 콘솔 열기 버튼
   • 남은 시간
   • 이 실습에 사용해야 하는 임시 사용자 인증 정보
   • 필요한 경우 실습 진행을 위한 기타 정보

2. Google Cloud 콘솔 열기를 클릭합니다(Chrome 브라우저를 실행 중인 경우 마우스 오른쪽 버튼으로 클릭하고 시크릿 창에서 링크 열기를 선택합니다).

   실습에서 리소스가 가동되면 다른 탭이 열리고 로그인 페이지가 표시됩니다.

   팁: 두 개의 탭을 각각 별도의 창으로 나란히 정렬하세요.

   참고: 계정 선택 대화상자가 표시되면 다른 계정 사용을 클릭합니다.

3. 필요한 경우 아래의 사용자 이름을 복사하여 로그인 대화상자에 붙여넣습니다.

   {{{user_0.username | "Username"}}}

   실습 세부정보 창에서도 사용자 이름을 확인할 수 있습니다.

4. 다음을 클릭합니다.

5. 아래의 비밀번호를 복사하여 시작하기 대화상자에 붙여넣습니다.

   {{{user_0.password | "Password"}}}

   실습 세부정보 창에서도 비밀번호를 확인할 수 있습니다.

6. 다음을 클릭합니다.

   중요: 실습에서 제공하는 사용자 인증 정보를 사용해야 합니다. Google Cloud 계정 사용자 인증 정보를 사용하지 마세요. 참고: 이 실습에 자신의 Google Cloud 계정을 사용하면 추가 요금이 발생할 수 있습니다.

7. 이후에 표시되는 페이지를 클릭하여 넘깁니다.

   • 이용약관에 동의합니다.
   • 임시 계정이므로 복구 옵션이나 2단계 인증을 추가하지 않습니다.
   • 무료 체험판을 신청하지 않습니다.

잠시 후 Google Cloud 콘솔이 이 탭에서 열립니다.

참고: Google Cloud 제품 및 서비스에 액세스하려면 탐색 메뉴를 클릭하거나 검색창에 제품 또는 서비스 이름을 입력합니다.

작업 1. ADK 설치 및 환경 설정

참고: 일반적으로 Qwiklabs에서는 Qwiklabs 학습자 계정과 Google Cloud에 로그인된 다른 계정 간에 혼동하지 않도록 시크릿 모드 브라우저 창을 사용하는 것이 좋습니다. Chrome을 사용하는 경우 시크릿 창을 닫은 다음 이 실습 상단의 Google Cloud 콘솔 열기 버튼을 마우스 오른쪽 버튼으로 클릭하고 시크릿 창에서 링크 열기를 선택하면 쉽게 시크릿 모드 브라우저 창을 사용할 수 있습니다.

권장 API 사용 설정

1. 이 실습 환경에서는 Vertex AI API, Routes API, Directions API가 사용 설정되어 있습니다.

Cloud Shell 편집기 탭 준비

2. Google Cloud 콘솔 창을 선택한 상태에서 키보드의 G 키와 S 키를 차례로 눌러 Cloud Shell을 엽니다. 또는 Cloud 콘솔의 오른쪽 상단에서 Cloud Shell 활성화 버튼()을 클릭할 수도 있습니다.

3. 계속을 클릭합니다.

4. Cloud Shell을 승인하라는 메시지가 표시되면 승인을 클릭합니다.

5. Cloud Shell 터미널 패널의 오른쪽 상단에서 새 창에서 열기 버튼 을 클릭합니다.

6. Cloud Shell 터미널에서 다음을 입력하여 Cloud Shell 편집기를 홈 디렉터리로 엽니다.

   cloudshell workspace ~

7. 화면 오른쪽에 표시되는 추가 튜토리얼 또는 Gemini 패널을 닫아 코드 편집기에 더 많은 공간을 확보합니다.

8. 이 실습의 나머지 부분에서는 이 창을 Cloud Shell 편집기 및 Cloud Shell 터미널이 있는 IDE로 사용할 수 있습니다.

실습에 필요한 ADK 및 코드 샘플 다운로드 및 설치

9. Cloud Shell 터미널에서 다음 명령어를 실행하여 ADK를 설치합니다.

   참고: 설치하는 ADK 버전이 이 실습에서 사용되는 버전과 일치하도록 버전을 지정합니다. 최신 버전 번호와 출시 노트는 adk-python 저장소에서 확인할 수 있습니다. sudo python3 -m pip install google-adk==1.5.0

10. 다음 명령어를 Cloud Shell 터미널에 붙여넣어 Cloud Storage 버킷에서 파일을 복사하고 압축을 해제하면 실습을 위한 코드를 포함한 프로젝트 디렉터리가 생성됩니다.

    gcloud storage cp gs://{{{project_0.project_id| YOUR_GCP_PROJECT_ID}}}-bucket/adk_mcp_tools.zip . unzip adk_mcp_tools.zip

11. 다음 명령어를 사용하여 실습에 필요한 추가 항목을 설치합니다.

    python3 -m pip install -r adk_mcp_tools/requirements.txt

내 진행 상황 확인하기를 클릭하여 목표를 확인합니다. ADK 설치 및 환경 설정

작업 2. adk 웹에서 ADK 에이전트(MCP 클라이언트로서의 ADK)와 함께 Google 지도 MCP 서버 사용

이 섹션에서는 외부 Google 지도 MCP 서버의 도구를 ADK 에이전트에 통합하는 방법을 보여줍니다. 이는 ADK 에이전트가 MCP 인터페이스를 노출하는 기존 서비스에서 제공하는 기능을 사용해야 하는 경우 가장 일반적인 통합 패턴입니다. MCPToolset 클래스를 에이전트의 tools 목록에 직접 추가하여 MCP 서버에 원활하게 연결하고, 도구를 검색하고, 에이전트가 사용할 수 있도록 만드는 방법을 알아봅니다. 이러한 예시는 주로 adk 웹 개발 환경 내의 상호작용에 중점을 둡니다.

MCPToolset

MCPToolset 클래스는 MCP 서버의 도구를 통합하기 위한 ADK의 기본 메커니즘입니다. 에이전트의 tools 목록에 MCPToolset 인스턴스를 포함하면 지정된 MCP 서버와의 상호작용이 자동으로 처리됩니다. 실행 방식은 다음과 같습니다.

• 연결 관리: 초기화 시 MCPToolset는 MCP 서버에 대한 연결을 설정하고 관리합니다. 이는 로컬 서버 프로세스(표준 입력/출력을 통한 통신에 StdioServerParameters 사용) 또는 원격 서버(서버 전송 이벤트에 SseServerParams 사용)일 수 있습니다. 또한 이 도구 모음은 에이전트 및 애플리케이션이 종료될 때 이 연결의 단계적 종료를 처리합니다.
• 도구 검색 및 조정: 연결되면 MCPToolset가 MCP 서버에 사용 가능한 도구를 쿼리합니다(list_tools MCP 메서드 사용). 그런 다음 발견된 MCP 도구의 스키마를 ADK 호환 BaseTool 인스턴스로 변환합니다.
• 에이전트 노출: 이와 같이 조정된 도구는 기본 ADK 도구처럼 LlmAgent에서 사용할 수 있게 됩니다.
• 도구 호출 프록시: LlmAgent가 이러한 도구 중 하나를 사용하기로 결정하면 MCPToolset는 call_tool MCP 메서드를 사용하여 MCP 서버에 대한 호출을 투명하게 프록시하고, 필요한 인수를 전송하고, 서버의 응답을 에이전트에 반환합니다.
• 필터링(선택사항): MCPToolset를 만들 때 tool_filter 파라미터를 사용하여 에이전트에 모든 도구를 노출하는 대신 MCP 서버에서 특정 도구 하위 집합을 선택할 수 있습니다.

API 키 가져오기 및 API 사용 설정

이 하위 섹션에서는 GOOGLE_MAPS_API_KEY라는 이름의 새 API 키를 생성합니다.

1. Google Cloud 콘솔(Cloud Shell 편집기 아님)을 표시하는 브라우저 탭을 엽니다.

2. 이 브라우저 탭에서 Cloud Shell 터미널 창을 닫아 콘솔 영역을 넓힐 수 있습니다.

3. 페이지 상단의 검색창에서 사용자 인증 정보를 검색합니다. 검색 결과에서 선택합니다.

   

4. 사용자 인증 정보 페이지에서 페이지 상단의 + 사용자 인증 정보 만들기를 클릭한 다음 API 키를 선택합니다.

   API 키 생성 대화상자에 새로 생성된 키가 표시됩니다. 실습 후반부에 사용할 수 있도록 이 키를 로컬에 저장해야 합니다.

5. 대화상자에서 닫기를 클릭합니다.

   새로 생성된 키에는 기본적으로 API 키 1이라는 이름이 지정됩니다. 키를 선택하고 GOOGLE_MAPS_API_KEY로 이름을 바꾼 다음 저장을 클릭합니다.

   

Google 지도의 MCPToolset로 에이전트 정의

이 하위 섹션에서는 Google 지도에 MCPToolset를 사용하도록 에이전트를 구성하여 경로 및 위치 기반 정보를 원활하게 제공할 수 있도록 합니다.

6. Cloud Shell 편집기의 파일 탐색기 창에서 adk_mcp_tools 폴더를 찾습니다. 클릭하여 전환해 엽니다.

7. adk_mcp_tools/google_maps_mcp_agent 디렉터리로 이동합니다.

8. 다음 명령어를 일반 텍스트 파일에 붙여넣은 다음 YOUR_ACTUAL_API_KEY 값을 이전 단계에서 생성하고 저장한 Google 지도 API 키로 업데이트합니다.

   cd ~/adk_mcp_tools cat << EOF > google_maps_mcp_agent/.env GOOGLE_GENAI_USE_VERTEXAI=TRUE GOOGLE_CLOUD_PROJECT={{{project_0.project_id | Project }}} GOOGLE_CLOUD_LOCATION={{{ project_0.default_region | Region}}} GOOGLE_MAPS_API_KEY="YOUR_ACTUAL_API_KEY" EOF

9. 업데이트된 명령어를 Cloud Shell 터미널에 복사하여 붙여넣고 실행하여 이 에이전트 디렉터리에 대한 인증 세부정보를 제공하는 .env 파일을 작성합니다.

10. 다음 명령어를 실행하여 .env 파일을 이 실습에서 사용할 다른 에이전트 디렉터리로 복사합니다.

    cp google_maps_mcp_agent/.env adk_mcp_server/.env

11. 다음으로 agent.py 파일에 표시된 위치에 다음 코드를 추가하여 Google 지도 도구를 에이전트에 추가합니다. 이렇게 하면 에이전트가 Google 지도의 MCPToolset를 사용하여 경로 또는 위치 기반 정보를 제공할 수 있습니다.

    tools=[ MCPToolset( connection_params=StdioConnectionParams( server_params=StdioServerParameters( command='npx', args=[ "-y", "@modelcontextprotocol/server-google-maps", ], env={ "GOOGLE_MAPS_API_KEY": google_maps_api_key } ), timeout=15, ), ) ],

12. adk_mcp_tools 프로젝트 디렉터리에서 다음 명령어를 사용하여 Agent Development Kit Dev UI를 실행합니다.

    adk 웹

    출력:

    INFO: Started server process [2434] INFO: Waiting for application startup. +----------------------------------------------------+ | ADK 웹 서버 시작됨 | | | | 로컬 테스트를 위해 http://localhost:8000에서 액세스하세요.| +----------------------------------------------------+ INFO: Application startup complete. INFO: Uvicorn running on http://0.0.0.0:8081 (Press CTRL+C to quit)

13. 새 탭에서 웹 인터페이스를 보려면 터미널 출력에서 http://127.0.0.1:8000 링크를 클릭합니다.

14. ADK Dev UI가 포함된 새 브라우저 탭이 열립니다. 왼쪽의 에이전트 선택 드롭다운에서 드롭다운의 google_maps_mcp_agent를 선택합니다.

15. 에이전트와 대화를 시작하고 다음 프롬프트를 실행합니다.

    GooglePlex에서 SFO까지 가는 길을 찾아 줘. 참고: API를 처음 사용할 때 API 호출 시간이 초과되면 ADK Dev UI의 오른쪽 상단에서 + 새 세션을 클릭하고 다시 시도하세요. 프랑스 파리에서 독일 베를린까지 가는 경로가 뭐야?

    출력:

    

16. 번개 표시가 있는 에이전트의 채팅 풍선 옆에 있는 에이전트 아이콘을 클릭합니다. 번개 표시는 함수 호출을 나타냅니다. 그러면 이 이벤트의 이벤트 검사기가 열립니다.

    

17. 에이전트 그래프에는 렌치 이모티콘(🔧)으로 식별되는 여러 도구가 표시됩니다. MCPToolset를 하나만 가져왔지만 이 도구 세트에는 maps_place_details, maps_directions 등 여기에 나열된 다양한 도구가 포함되어 있습니다.

    

18. 요청 탭에서 요청의 구조를 확인할 수 있습니다. 이벤트 검사기 상단의 화살표를 사용하여 에이전트의 생각, 함수 호출, 응답을 탐색할 수 있습니다.

19. 이 에이전트에 대한 질문을 마치면 개발 UI 브라우저 탭을 닫습니다.

20. Cloud Shell 터미널 패널로 돌아가서 CTRL + C를 눌러 서버를 중지합니다.

내 진행 상황 확인하기를 클릭하여 목표를 확인합니다. API 키를 만들고 ADK 에이전트 배포

작업 3. ADK 도구를 사용한 MCP 서버 빌드(ADK를 노출하는 MCP 서버)

이 섹션에서는 커스텀 빌드된 MCP 서버를 통해 ADK load_web_page 도구를 노출하는 방법을 알아봅니다. 이 패턴을 사용하면 기존 ADK 도구를 래핑하여 모든 표준 MCP 클라이언트 애플리케이션에서 액세스할 수 있도록 만들 수 있습니다.

MCP 서버 스크립트 만들기 및 서버 로직 구현

1. Cloud Shell 편집기 탭으로 돌아가서 adk_mcp_tools/adk_mcp_server 디렉터리를 선택합니다.

2. adk_server.py라는 Python 파일이 준비되어 있으며 주석이 추가되어 있습니다. 잠시 시간을 내어 파일을 검토하고 주석을 읽어 코드가 도구를 래핑하고 MCP 서버로 제공하는 방법을 이해합니다. 또한 코드가 MCP 클라이언트로 하여금 사용 가능한 도구를 나열하고 ADK 도구를 비동기적으로 호출하여 MCP 호환 형식으로 요청과 응답을 처리할 수 있도록 하는 방법을 확인하세요.

ADK 에이전트로 커스텀 MCP 서버 테스트

3. adk_mcp_server 디렉터리에서 agent.py 파일을 클릭합니다.

4. adk_server.py 파일의 경로를 업데이트합니다.

   /home/{{{project_0.startup_script.updated_lab_username | Username}}}/adk_mcp_tools/adk_mcp_server/adk_server.py

5. 다음으로 agent.py 파일에서 표시된 위치에 다음 코드를 추가하여 에이전트에 MCPToolset를 추가합니다. ADK 에이전트는 MCP 서버의 클라이언트 역할을 합니다. 이 ADK 에이전트는 MCPToolset를 사용하여 adk_server.py 스크립트에 연결합니다.

   tools=[ MCPToolset( connection_params=StdioConnectionParams( server_params=StdioServerParameters( command="python3", # Command to run your MCP server script args=[PATH_TO_YOUR_MCP_SERVER_SCRIPT], # Argument is the path to the script ), timeout=15, ), tool_filter=['load_web_page'] # Optional: ensure only specific tools are loaded ) ],

6. MCP 서버를 실행하려면 Cloud Shell 터미널에서 다음 명령어를 실행하여 adk_server.py 스크립트를 시작합니다.

   python3 ~/adk_mcp_tools/adk_mcp_server/adk_server.py

   출력:

   

7. Cloud Shell 터미널 창 상단의 버튼을 클릭하여 새 Cloud Shell 터미널 탭을 엽니다.

8. Cloud Shell 터미널에서 adk_mcp_tools 프로젝트 디렉터리에서 다음 명령어를 사용하여 Agent Development Kit Dev UI를 실행합니다.

   cd ~/adk_mcp_tools adk web

9. 새 탭에서 웹 인터페이스를 보려면 터미널 출력에서 http://127.0.0.1:8000 링크를 클릭합니다.

10. 왼쪽의 에이전트 선택 드롭다운에서 드롭다운의 adk_mcp_server를 선택합니다.

11. 다음을 사용해 에이전트를 쿼리합니다.

    https://example.com에서 콘텐츠 로드

    출력:

    

    여기서 일어나는 일:

    1. ADK 에이전트(web_reader_mcp_client_agent)는 MCPToolset를 사용하여 adk_server.py에 연결합니다.
    2. MCP 서버는 call_tool 요청을 수신하고 ADK load_web_page 도구를 실행한 다음 결과를 반환합니다.
    3. 그러면 ADK 에이전트가 이 정보를 전달합니다. ADK Web UI(및 해당 터미널)와 adk_server.py 터미널에서 실행 중인 Cloud Shell 터미널 탭에 로그가 표시됩니다.

    이는 ADK 도구를 MCP 서버 내에 캡슐화하여 ADK 에이전트를 포함한 광범위한 MCP 호환 클라이언트가 ADK 도구에 액세스할 수 있음을 보여줍니다.

수고하셨습니다

이 실습을 마치면 MCPToolset 클래스를 사용하여 외부 모델 컨텍스트 프로토콜(MCP) 도구를 ADK 에이전트에 통합하는 방법을 알게 됩니다.

MCP 서버에 연결하고, 에이전트 내에서 해당 도구를 사용하고, 커스텀 MCP 서버를 통해 load_web_page와 같은 ADK 도구를 노출하는 방법을 알아보았습니다.

이러한 기술을 사용하면 강력한 외부 서비스로 ADK 에이전트를 확장하여 웹 개발 워크플로를 개선할 수 있습니다.

설명서 최종 업데이트: 2025년 9월 3일

실습 최종 테스트: 2025년 9월 3일

Copyright 2020 Google LLC All rights reserved. Google 및 Google 로고는 Google LLC의 상표입니다. 기타 모든 회사명 및 제품명은 해당 업체의 상표일 수 있습니다.