GSP1350

개요

이 실습에서는 모델 컨텍스트 프로토콜(MCP) 서버와 같은 원격 도구를 사용하는 AI 에이전트를 빌드하기 위해 에이전트 개발 키트(ADK)를 사용하여 클라이언트 에이전트 서비스를 구현하고 배포하는 과정을 집중적으로 다룹니다. 실습에서 보여주는 핵심 아키텍처 원칙은 관심사 분리입니다. 즉, 별도의 추론 계층(에이전트)이 보안 API를 통해 별도의 도구 계층(MCP 서버)과 통신하는 구조입니다.

이 실습에는 가상 동물원의 동물 데이터를 LLM에 제공하는 MCP 서버가 사전 배포되어 있습니다. 이어서 Python 애플리케이션으로 구성된 가상의 동물원용 투어 가이드 에이전트를 빌드합니다. 에이전트는 MCP 서버를 사용하여 동물의 세부정보에 액세스하고 최적의 투어 가이드 경험을 제공하기 위해 Wikipedia 정보도 활용합니다.

마지막으로 투어 가이드 에이전트를 Google Cloud Run에 배포하여 로컬에서만 실행되는 것이 아니라 모든 동물원 방문객이 액세스할 수 있도록 합니다.

학습할 내용

이 실습에서는 다음 작업을 수행하는 방법을 알아봅니다.

• ADK 배포를 위한 Python 프로젝트를 구성합니다.
• google-adk를 사용하여 도구를 사용하는 에이전트를 구현합니다.
• 에이전트를 원격 MCP 서버에 연결하여 도구 모음을 사용합니다.
• Python 애플리케이션을 서버리스 컨테이너로 Cloud Run에 배포합니다.
• IAM 역할을 사용하여 서비스 간의 안전한 인증을 구성합니다.
• 향후 비용이 청구되지 않도록 Cloud 리소스를 삭제합니다.

Cloud Run에 배포해야 하는 이유

Cloud Run은 서버리스 플랫폼이므로 ADK 에이전트를 호스팅하는 데 적합합니다. 즉, 사용자는 기본 인프라 관리가 아닌 코드에 집중할 수 있습니다. Cloud Run이 운영 업무를 대신 처리해 주기 때문입니다.

팝업 스토어와 비슷하다고 생각하면 됩니다. 고객(요청)이 있을 때만 문을 열고 리소스를 사용합니다. 고객이 없을 때는 운영을 완전히 중단하므로 빈 매장에 대해 비용을 지급할 필요가 없습니다.

Cloud Run의 주요 기능

어디서나 컨테이너 실행

• 앱이 포함된 컨테이너(Docker 이미지)만 준비하면 됩니다.
• Cloud Run이 Google 인프라에서 이를 실행합니다.
• OS 패치, VM 설정, 확장 관리와 같은 번거로운 작업이 필요하지 않습니다.

자동 확장

• 앱을 사용하는 사람이 0명인 경우 → 실행되는 인스턴스가 0개입니다(유휴 상태 시 비용 $0).
• 1,000개의 요청이 몰릴 경우 → 필요한 만큼 인스턴스가 자동으로 확장됩니다.

기본적으로 스테이트리스(Stateless)

• 각 요청은 서로 다른 인스턴스로 이동할 수 있습니다.
• 상태를 저장해야 하는 경우 Cloud SQL, Firestore 또는 Redis와 같은 외부 서비스를 사용합니다.

모든 언어 또는 프레임워크 지원

• Linux 컨테이너에서 실행되는 한 Cloud Run은 Python, Go, Node.js, Java, .Net 등 어떤 언어로 작성되었는지 상관하지 않습니다.

사용한 만큼만 비용 지불

• 요청당 청구 + 컴퓨팅 시간(최대 100ms)
• 기존 VM과 달리 유휴 리소스에 대한 비용을 지급하지 않습니다.

설정 및 요건

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

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

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

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

• 표준 인터넷 브라우저 액세스 권한(Chrome 브라우저 권장)

참고: 이 실습을 실행하려면 시크릿 모드(권장) 또는 시크릿 브라우저 창을 사용하세요. 개인 계정과 학습자 계정 간의 충돌로 개인 계정에 추가 요금이 발생하는 일을 방지해 줍니다.

• 실습을 완료하기에 충분한 시간(실습을 시작하고 나면 일시중지할 수 없음)

참고: 이 실습에는 학습자 계정만 사용하세요. 다른 Google Cloud 계정을 사용하는 경우 해당 계정에 비용이 청구될 수 있습니다.

Cloud Shell 활성화

Cloud Shell은 다양한 개발 도구가 탑재된 가상 머신으로, 5GB의 영구 홈 디렉터리를 제공하며 Google Cloud에서 실행됩니다. Cloud Shell을 사용하면 명령줄을 통해 Google Cloud 리소스에 액세스할 수 있습니다.

1. Google Cloud 콘솔 상단에서 Cloud Shell 활성화 를 클릭합니다.

2. 다음 창을 클릭합니다.

   • Cloud Shell 정보 창을 통해 계속 진행합니다.
   • 사용자 인증 정보를 사용하여 Google Cloud API를 호출할 수 있도록 Cloud Shell을 승인합니다.

연결되면 사용자 인증이 이미 처리된 것이며 프로젝트가 학습자의 PROJECT_ID, (으)로 설정됩니다. 출력에 이 세션의 PROJECT_ID를 선언하는 줄이 포함됩니다.

Your Cloud Platform project in this session is set to {{{project_0.project_id | "PROJECT_ID"}}}

gcloud는 Google Cloud의 명령줄 도구입니다. Cloud Shell에 사전 설치되어 있으며 명령줄 자동 완성을 지원합니다.

3. (선택사항) 다음 명령어를 사용하여 활성 계정 이름 목록을 표시할 수 있습니다.

gcloud auth list

4. 승인을 클릭합니다.

출력:

ACTIVE: * ACCOUNT: {{{user_0.username | "ACCOUNT"}}} To set the active account, run: $ gcloud config set account `ACCOUNT`

5. (선택사항) 다음 명령어를 사용하여 프로젝트 ID 목록을 표시할 수 있습니다.

gcloud config list project

출력:

[core] project = {{{project_0.project_id | "PROJECT_ID"}}} 참고: gcloud 전체 문서는 Google Cloud에서 gcloud CLI 개요 가이드를 참고하세요.

작업 1. ADK를 다운로드하여 설치하고 프로젝트 폴더 생성

이 작업에서는 관련 API를 사용 설정하고 Python 프로젝트 배포의 소스 코드를 저장할 프로젝트 폴더를 만듭니다.

API 사용 설정 및 환경 변수 설정

1. Cloud Shell에서 편집기 열기를 클릭하여 Cloud Shell 편집기를 홈 디렉터리로 엽니다.
2. Cloud Shell 편집기 작업 모음에서 보기 > 터미널을 클릭합니다.

참고: '보기' 메뉴 옵션을 표시하려면 브라우저 창을 늘려야 할 수 있습니다.

실습의 나머지 부분에서는 이 창을 Cloud Shell 편집기(상단)와 Cloud Shell 터미널(하단)이 모두 있는 IDE로 사용합니다.

코드 편집기를 위한 공간을 더 확보할 수 있도록 화면 오른쪽에 표시되는 추가 튜토리얼 또는 Gemini 패널을 닫습니다.

3. 터미널에서 다음 명령어를 입력하여 프로젝트를 설정합니다.

   gcloud config set project {{{project_0.project_id | filled in at lab start}}}

예상 출력: 업데이트된 속성을 확인하는 출력 메시지가 표시됩니다.

참고: Cloud Shell이 제한 시간을 초과했거나 다시 시작되는 경우 프로젝트를 재설정해야 합니다.

4. 다음 명령어를 실행하여 필요한 모든 서비스를 사용 설정합니다.

   gcloud services enable \ run.googleapis.com \ artifactregistry.googleapis.com \ cloudbuild.googleapis.com \ aiplatform.googleapis.com \ compute.googleapis.com

예상 출력: 작업이 성공했음을 확인하는 출력 메시지가 표시됩니다.

내 진행 상황 확인하기를 클릭하여 목표를 확인합니다. API 사용 설정

프로젝트 디렉터리 생성

1. 다음 명령어를 실행하여 에이전트의 소스 코드를 위한 기본 폴더를 실습에 만듭니다.

   mkdir zoo_guide_agent && cd zoo_guide_agent

이제 requirements.txt 파일을 만들 준비가 되었습니다. 이 파일에는 동물원 에이전트에 필요한 Python 라이브러리가 나열되어 있습니다.

2. 다음 명령어를 실행하여 zoo_guide_agent 디렉터리 내에 파일을 만들고 Cloud Shell 편집기에서 파일을 실행하여 편집할 수 있도록 합니다.

   cloudshell edit requirements.txt

3. requirements.txt 파일에 다음을 추가하고 Ctrl+S를 눌러 변경사항을 저장합니다.

   google-adk==1.28.0 langchain==1.2.14 langchain-community==0.4.1 wikipedia

4. 터미널에서 다음 명령어를 실행하여 Python 패키지를 설치하고 PATH를 업데이트합니다.

   export PATH=$PATH:~/.local/bin pip3 install -r requirements.txt --user

5. 다음 명령어를 사용하여 현재 프로젝트, 리전, 사용자의 변수를 설정합니다.

   export PROJECT_ID=$(gcloud config get-value project) export REGION=$(gcloud compute project-info describe \ --format="value(commonInstanceMetadata.items[google-compute-default-region])") export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)") export SERVICE_ACCOUNT="${PROJECT_NUMBER}-compute@developer.gserviceaccount.com"

참고: Cloud Shell이 제한 시간을 초과했거나 다시 시작되는 경우 위의 변수를 다시 초기화해야 합니다.

6. 다음 명령어를 사용하여 zoo_guide_agent 디렉터리에서 에이전트를 인증할 .env 파일을 만들고 엽니다.

   cloudshell edit .env

.env 파일이 포함된 디렉터리가 Cloud Shell 편집기에 열립니다.

7. .env 파일에 다음을 추가하고 변경사항을 저장합니다.

   MODEL="{{{ project_0.startup_script.gemini_flash_model_id | filled in at lab start }}}" SERVICE_ACCOUNT="${PROJECT_NUMBER}-compute@developer.gserviceaccount.com" GOOGLE_GENAI_USE_ENTERPRISE=true GOOGLE_CLOUD_LOCATION=global

보안 MCP 서버 엔드포인트에 연결

이 섹션에서는 원격 MCP 서버에 대한 연결을 설정합니다.

1. Cloud Shell 터미널로 돌아가서 다음 명령어를 실행하여 Cloud Run 서비스 ID에 원격 MCP 서버를 호출할 수 있는 권한을 부여합니다.

   gcloud projects add-iam-policy-binding $PROJECT_ID \ --member="serviceAccount:$SERVICE_ACCOUNT" \ --role="roles/run.invoker"

2. 다음 명령어를 실행하여 MCP 서버 URL을 환경 변수에 저장합니다.

   echo -e "\nMCP_SERVER_URL=https://zoo-mcp-server-${PROJECT_NUMBER}.${REGION}.run.app/mcp/" >> .env

3. 다음 명령어를 실행하여 __init__.py 파일을 만듭니다. 이 파일은 Python에 zoo_guide_agent 디렉터리가 패키지임을 알려줍니다.

   cloudshell edit __init__.py

4. 열린 Cloud Shell 편집기에서 __init__.py에 다음 코드를 추가하고 변경사항을 저장합니다.

   from . import agent

작업 2. 에이전트 워크플로 생성

이 작업에서는 동물원 투어 가이드 에이전트의 워크플로를 구성합니다. 먼저 초기 설정을 위한 관련 라이브러리를 가져옵니다. 그리고 동물원 에이전트의 기능(사용하는 도구)을 정의하고 전문가 에이전트를 정의합니다. 그런 다음 워크플로 에이전트를 정의하고 마지막으로 기본 워크플로를 구성합니다.

기본 agent.py 파일 생성

• Cloud Shell 터미널로 돌아가서 다음 명령어를 실행하여 기본 agent.py 파일을 만듭니다. 그러면 Cloud Shell 편집기에서 파일이 열리므로 다음 단계에서 멀티 에이전트 시스템의 전체 코드를 붙여넣을 수 있습니다.

  cloudshell edit agent.py

라이브러리 가져오기 및 초기 설정 수행

첫 번째 블록은 ADK와 Google Cloud에서 필요한 모든 라이브러리를 가져옵니다. 또한 로깅을 설정하고 .env 파일에서 환경 변수를 로드합니다. 이는 모델과 서버 URL에 액세스하는 데 중요합니다.

• agent.py 파일에 다음 코드를 추가합니다.

  import os import sys import logging import google.cloud.logging from dotenv import load_dotenv # Add current directory for workspace utilities sys.path.append(os.path.dirname(os.path.abspath(__file__))) from google.adk import Agent from google.adk.agents import SequentialAgent from google.adk.tools.mcp_tool.mcp_toolset import MCPToolset, StreamableHTTPConnectionParams from google.adk.tools.tool_context import ToolContext from google.adk.tools.langchain_tool import LangchainTool from langchain_community.tools import WikipediaQueryRun from langchain_community.utilities import WikipediaAPIWrapper import google.auth import google.auth.transport.requests import google.oauth2.id_token # --- Setup Logging and Environment --- cloud_logging_client = google.cloud.logging.Client() cloud_logging_client.setup_logging() load_dotenv() model_name = os.getenv("MODEL")

도구 정의

에이전트의 성능은 사용할 수 있는 도구에 따라 달라집니다. 이 섹션에서는 데이터 저장을 위한 커스텀 함수, 보안 MCP 서버에 연결하는 MCP 도구, Wikipedia 도구를 포함한 에이전트의 모든 기능을 정의합니다.

• agent.py 하단에 다음 코드를 추가합니다.

  # Greet user and save their prompt def add_prompt_to_state( tool_context: ToolContext, prompt: str ) -> dict[str, str]: """Saves the user's initial prompt to the state.""" tool_context.state["PROMPT"] = prompt logging.info(f"[State updated] Added to PROMPT: {prompt}") return {"status": "success"} # Configuring the MCP Tool to connect to the Zoo MCP server mcp_server_url = os.getenv("MCP_SERVER_URL") if not mcp_server_url: raise ValueError("The environment variable MCP_SERVER_URL is not set.") def get_id_token(): """Get an ID token to authenticate with the MCP server.""" target_url = os.getenv("MCP_SERVER_URL") audience = target_url.split('/mcp/')[0] request = google.auth.transport.requests.Request() id_token = google.oauth2.id_token.fetch_id_token(request, audience) return id_token """ ## Use this code if you are using the public MCP Server and comment out the code below defining mcp_tools mcp_tools = MCPToolset( connection_params=StreamableHTTPConnectionParams( url=mcp_server_url ) ) """ mcp_tools = MCPToolset( connection_params=StreamableHTTPConnectionParams( url=mcp_server_url, headers={ "Authorization": f"Bearer {get_id_token()}", }, ), ) # Configuring the Wikipedia Tool wikipedia_tool = LangchainTool( tool=WikipediaQueryRun(api_wrapper=WikipediaAPIWrapper()) )

세 가지 도구 설명

• add_prompt_to_state: 📝 동물원 방문객이 무엇을 물어봤는지 기억하는 도구입니다. 방문자가 '사자는 어디에 있어?'라고 물으면 이 도구는 해당 질문을 에이전트의 메모리에 저장하여 워크플로의 다른 에이전트가 무엇을 조사해야 하는지 알 수 있도록 합니다.

  작동 방식: 방문자의 프롬프트를 공유된 tool_context.state 사전에 작성하는 Python 함수입니다. 이 도구 컨텍스트는 단일 대화에 대한 에이전트의 단기 메모리를 나타냅니다. 한 에이전트가 상태에 저장한 데이터는 워크플로의 다음 에이전트가 읽을 수 있습니다.

• MCPToolset: 🦁 투어 가이드 에이전트를 이 실습에 사전 배포된 동물원 MCP 서버에 연결하는 데 사용됩니다. 이 서버에는 동물원에 있는 동물의 이름, 나이, 우리 등 특정 정보를 조회할 수 있는 전문 도구가 있습니다.

  방식: 동물원의 비공개 서버 URL에 안전하게 연결됩니다. get_id_token을 사용하여 안전한 '키 카드'(서비스 계정 ID 토큰)를 자동으로 가져와 ID를 증명하고 액세스 권한을 얻습니다.

• LangchainTool: 🌍 투어 가이드 에이전트에게 일반적인 세계 지식을 제공합니다. 방문자가 동물원 데이터베이스에 없는 질문(예: '사자는 야생에서 무엇을 먹어?')을 하면 이 도구를 통해 에이전트가 Wikipedia에서 답을 찾아볼 수 있습니다.

  작동 방식: 어댑터 역할을 하여 에이전트가 LangChain 라이브러리의 사전 빌드된 WikipediaQueryRun 도구를 사용할 수 있도록 합니다.

리소스:

• MCP 도구 모음
• 함수 도구
• 상태

전문가 에이전트 정의

이 섹션에서는 연구원 에이전트와 대답 포맷터 에이전트라는 두 가지 전문가 에이전트를 정의합니다. 연구원 에이전트는 작업의 '두뇌'입니다. 이 에이전트는 공유된 State에서 사용자의 프롬프트를 가져와 강력한 도구(동물원의 MCP 서버 도구 및 Wikipedia 도구)를 검사하고, 어떤 도구를 사용하여 답을 찾을지 결정합니다.

대답 포맷터 에이전트의 역할은 프레젠테이션입니다. 새로운 정보를 찾기 위해 도구를 사용하지 않습니다. 대신 연구원 에이전트가 수집한 원시 데이터(상태를 통해 전달됨)를 가져와 LLM의 언어 기술을 사용하여 친근한 대화형 대답으로 변환합니다.

• agent.py 하단에 다음 코드를 추가합니다.

  # 1. Researcher Agent comprehensive_researcher = Agent( name="comprehensive_researcher", model=model_name, description="The primary researcher that can access both internal zoo data and external knowledge from Wikipedia.", instruction=""" You are a helpful research assistant. Your goal is to fully answer the user's PROMPT. You have access to two tools: 1. A tool for getting specific data about animals AT OUR ZOO (names, ages, locations). 2. A tool for searching Wikipedia for general knowledge (facts, lifespan, diet, habitat). First, analyze the user's PROMPT. - If the prompt can be answered by only one tool, use that tool. - If the prompt is complex and requires information from both the zoo's database AND Wikipedia, you MUST use both tools to gather all necessary information. - Synthesize the results from the tool(s) you use into preliminary data outputs. PROMPT: {{ PROMPT }} """, tools=[ mcp_tools, wikipedia_tool ], output_key="research_data" # A key to store the combined findings ) # 2. Response Formatter Agent response_formatter = Agent( name="response_formatter", model=model_name, description="Synthesizes all information into a friendly, readable response.", instruction=""" You are the friendly voice of the Zoo Tour Guide. Your task is to take the RESEARCH_DATA and present it to the user in a complete and helpful answer. - First, present the specific information from the zoo (like names, ages, and where to find them). - Then, add the interesting general facts from the research. - If some information is missing, just present the information you have. - Be conversational and engaging. RESEARCH_DATA: {{ research_data }} """ )

워크플로 에이전트 정의

워크플로 에이전트는 동물원 투어의 '백오피스' 관리자 역할을 합니다. 조사 요청을 받아들이고 3단계에서 정의한 두 에이전트가 올바른 순서로 작업을 수행하도록 합니다. 즉, 먼저 연구를 수행한 다음 형식을 지정합니다. 이로써 동물원 방문객의 질문에 답하는 예측 가능하고 신뢰할 수 있는 프로세스가 만들어집니다.

방식: SequentialAgent라는 특수한 유형의 에이전트로, 스스로 생각하지 않습니다. 이 에이전트의 유일한 작업은 고정된 순서로 sub_agents(연구원 및 포맷터) 목록을 실행하고 공유 메모리를 자동으로 다음 에이전트로 전달하는 것입니다.

• agent.py 하단에 다음 코드 블록을 추가합니다.

  tour_guide_workflow = SequentialAgent( name="tour_guide_workflow", description="The main workflow for handling a user's request about an animal.", sub_agents=[ comprehensive_researcher, # Step 1: Gather all data response_formatter, # Step 2: Format the final response ] )

기본 워크플로 구성

주요 워크플로는 root_agent를 통해 지정되며, ADK 프레임워크는 이를 모든 새로운 대화의 시작점으로 사용합니다. 이 에이전트의 주요 역할은 전체 프로세스를 조정하는 것입니다. 이 모델은 초기 컨트롤러 역할을 하며 대화의 첫 번째 단계를 관리합니다.

• 이 마지막 코드 블록을 agent.py 하단에 추가하고 변경사항을 저장합니다.

  root_agent = Agent( name="greeter", model=model_name, description="The main entry point for the Zoo Tour Guide.", instruction=""" - Let the user know you will help them learn about the animals we have in the zoo. - When the user responds, use the 'add_prompt_to_state' tool to save their response. After using the tool, transfer control to the 'tour_guide_workflow' agent. """, tools=[add_prompt_to_state], sub_agents=[tour_guide_workflow] )

이제 agent.py 파일이 완성되었습니다.

이러한 방식으로 빌드하면 도구, 작업자 에이전트, 관리자 에이전트 등 각 구성요소가 최종적인 지능형 시스템을 만드는 데 어떤 역할을 하는지 알 수 있습니다. 다음으로 배포할 차례입니다.

작업 3. 배포를 위한 애플리케이션 준비

로컬 환경이 준비되면 다음으로 동물원 투어 가이드 에이전트 배포를 위해 Google Cloud 프로젝트를 준비할 단계입니다.

이 단계에서는 에이전트의 파일 구조가 배포 명령어와 호환되는지 최종적으로 점검합니다. 무엇보다 중요한 점은 배포된 Cloud Run 서비스가 사용자를 대신하여 Agent Platform 모델을 호출할 수 있도록 핵심 IAM 권한을 구성하는 것입니다. 이 단계를 완료하면 클라우드 환경에서 에이전트를 성공적으로 실행할 수 있습니다.

1. Cloud Shell 터미널로 돌아가서 다음 명령어를 실행하여 변수를 셸 세션에 로드합니다.

   source .env

2. 다음 명령어를 실행하여 서비스 계정에 Agent Platform 사용자 역할을 부여합니다. 이 역할은 예측을 수행하고 Google 모델을 호출할 수 있는 권한을 제공합니다.

   # Grant the "Agent Platform User" role to your service account gcloud projects add-iam-policy-binding $PROJECT_ID \ --member="serviceAccount:$SERVICE_ACCOUNT" \ --role="roles/aiplatform.user"

작업 4. ADK CLI를 사용하여 에이전트 배포

로컬 코드가 준비되고 Google Cloud 프로젝트가 준비되었으므로 이제 에이전트를 배포할 차례입니다.

이 작업에서는 전체 배포 워크플로를 자동화하는 편리한 도구인 adk deploy cloud_run 명령어를 사용합니다. 이 단일 명령어를 사용하면 코드를 패키징하고 컨테이너 이미지를 빌드해 Artifact Registry에 푸시한 다음, Cloud Run에서 서비스를 실행하여 웹에서 액세스할 수 있게 됩니다.

에이전트 배포

1. 다음 명령어를 실행하여 에이전트를 배포합니다.

   # Run the deployment command adk deploy cloud_run \ --project=$PROJECT_ID \ --region=$REGION \ --service_name=zoo-tour-guide \ --with_ui \ .

2. 계속 진행할지 묻는 메시지나 [zoo-tour-guide]에 대한 인증되지 않은 호출을 허용할지 묻는 메시지가 표시되면 각각 Y를 입력하고 Enter 키를 누릅니다.

참고: 이 배포 명령어를 실행 완료하는 데 5~10분 정도 걸릴 수 있습니다.

3. 다음 명령어를 실행하여 기존 Cloud Run 서비스의 구성 설정을 수정합니다.

   gcloud run services update zoo-tour-guide \ --region=$REGION \ --update-labels=dev-tutorial=codelab-adk \ --set-env-vars="MODEL=$MODEL,MCP_SERVER_URL=$MCP_SERVER_URL,GOOGLE_CLOUD_LOCATION=global"

배포 링크 확인

• 에이전트가 Cloud Run에 성공적으로 배포되면 서비스 URL이 출력됩니다. 이 URL을 사용하여 새 브라우저 탭에서 열 수 있습니다.

  다음 형식과 유사해야 합니다. 서비스 URL 출력:

  https://zoo-tour-guide-{{{project_0.startup_script.project_number | filled in at lab start}}}.{{{project_0.default_region | filled in at lab start}}}.run.app

Cloud Run에 배포하는 동안 --with_ui 플래그를 사용했으므로 ADK 개발자 UI가 표시됩니다.

참고: URL이 있는 사람은 누구나 이 에이전트에 액세스할 수 있으므로 이 접근방식은 테스트 목적으로만 사용하는 것이 좋습니다. 참고: 배포가 완료된 후 활동 추적 확인을 통과하는 데 몇 분 정도 걸릴 수 있습니다.

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

작업 5. 배포된 에이전트 테스트

이제 에이전트가 Cloud Run에서 라이브로 실행되므로 이 작업에서는 테스트를 수행하여 배포가 성공적이었고 에이전트가 예상대로 작동하는지 확인합니다. 공개 서비스 URL을 사용하여 ADK의 웹 인터페이스에 액세스하고 에이전트와 상호작용을 해야 합니다.

1. 웹브라우저에서 이전 작업에서 출력된 공개 Cloud Run 서비스 URL을 열거나 출력에서 Ctrl을 누른 상태로 URL을 클릭합니다(새 브라우저 탭에서 열림). 그러면 ADK 개발자 UI가 열립니다.

   Cloud Shell에서 외부 웹사이트를 열지 묻는 알림이 표시되면 열기를 클릭하여 확인합니다.

2. ADK 툴바의 오른쪽 상단에서 토큰 스트리밍을 사용으로 전환합니다.

이제 동물원 에이전트와 상호작용을 할 수 있습니다.

3. 프롬프트 상자에 다음 프롬프트를 입력하고 Enter 키를 눌러 새 대화를 시작합니다.

Hello

결과를 확인합니다. 에이전트는 다음과 같이 표준 인사말로 빠르게 대답해야 합니다.

"Hello! I'm your Zoo Tour Guide. I can help you learn about the amazing animals we have here. What would you like to know or explore today?"

4. 이제 동물원 가이드 에이전트와 상호작용해 보겠습니다. 다음 프롬프트를 입력하여 대화를 재개합니다.

Where are the penguins located?

다음과 비슷한 대답이 표시됩니다.

5. 다음 추가 프롬프트를 사용해 에이전트가 다양한 도구(MCP 대 Wikipedia)를 사용하여 정보를 결합하는 방식을 확인해 보세요.

일반 지식 테스트(Wikipedia만 해당):

What is the average lifespan of a penguin in the wild?

내부 및 외부 데이터 결합 테스트:

What species are the penguins in our zoo, and what do they typically eat in the wild?

사자 정보(두 도구 모두 다시 테스트):

Where are the lions and what do they eat in the wild?

북극곰 정보(동물원에 없을 수도 있는 동물에 대한 테스트):

Do we have polar bears in this zoo?

에이전트 흐름 설명

시스템은 지능형 멀티 에이전트팀으로 작동합니다. 이 프로세스는 명확한 순서로 관리되어 사용자의 질문부터 최종적인 상세한 답변까지 원활하고 효율적인 흐름을 보장합니다.

1. 동물원 안내원(안내 데스크)

전체 프로세스는 안내원 에이전트로부터 시작됩니다.

역할: 대화를 시작합니다. 사용자에게 인사하고 어떤 동물에 대해 알고 싶은지 묻도록 지시받았습니다.

도구: 사용자가 대답하면 안내원은 add_prompt_to_state 도구를 사용하여 사용자의 정확한 입력 내용(예: "사자에 대해 알려줘")을 캡처하고 시스템의 메모리에 저장합니다.

전환: 프롬프트를 저장한 후 즉시 하위 에이전트인 tour_guide_workflow로 제어권을 넘깁니다.

2. 종합 연구원(슈퍼 연구원)

기본 워크플로의 첫 번째 단계이자 작업의 '두뇌'입니다. 이제 대규모 팀 대신 사용 가능한 모든 정보에 액세스할 수 있는 단일한 고숙련 에이전트를 보유하게 됩니다.

역할: 사용자의 질문을 분석하고 지능적인 계획을 수립합니다. 언어 모델의 강력한 도구 사용 기능을 사용하여 다음 중 어떤 정보가 필요한지 결정합니다.

• 동물원 기록의 내부 데이터(MCP 서버 활용)
• 웹의 일반적인 지식(Wikipedia API 활용)
• 복잡한 질문이면 두 가지 모두 활용

작업: 필요한 모든 원시 데이터를 수집하는 데 필요한 도구를 실행합니다. 예를 들어 '사자의 나이는 몇 살이고 야생에서 무엇을 먹고 살아?'라는 질문을 받으면 MCP 서버를 호출하여 나이를 확인하고 Wikipedia 도구를 호출하여 식단 정보를 확인합니다.

3. 대답 포맷터(제시자)

종합 연구원이 모든 사실을 수집한 후 실행되는 마지막 에이전트입니다.

역할: 친절한 동물원 투어 가이드 역할을 담당합니다. 하나 또는 여러 출처에서 수집된 원시 데이터를 자연스럽게 다듬어 줍니다.

동작: 수집된 모든 정보를 짜임새 있고 흥미로운 하나의 답변으로 종합합니다. 지시에 따라 먼저 특정 동물원에 대한 정보를 제시한 다음 흥미로운 일반적인 사실을 덧붙입니다.

최종 결과: 에이전트가 생성한 텍스트는 사용자가 채팅 창에서 보게 되는 완성된 상세 답변입니다.

작업 6. 환경 정리

이 작업에서는 실습에서 만든 Cloud 리소스를 삭제하여 향후 비용이 발생하지 않도록 합니다.

• Cloud Shell 터미널 탭으로 돌아가서 다음 명령어를 실행합니다.

  gcloud run services delete zoo-tour-guide --region=$REGION --quiet gcloud artifacts repositories delete cloud-run-source-deploy --location=$REGION --quiet

다음 단계/더 학습하기

에이전트 빌드에 대해 자세히 알아보려면 다음 리소스를 확인하세요.

• ADK 문서
• 에이전트를 위한 커스텀 도구 빌드

수고하셨습니다

이 실습에서는 ADK 명령줄 인터페이스를 사용하여 배포용 Python 프로젝트를 구조화하는 방법을 살펴보았습니다. 또한 멀티 에이전트 워크플로를 구현하고, 원격 MCP 서버에 연결하여 해당 도구를 활용하고, Wikipedia API와 같은 외부 도구를 통합하여 내부 데이터를 보강한 뒤 에이전트를 서버리스 컨테이너로 Cloud Run에 배포했습니다.

설명서 최종 업데이트: 2026년 7월 21일

실습 최종 테스트: 2026년 7월 21일

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