GSP1350

개요

이 실습에서는 에이전트 개발 키트(ADK)를 사용하여 MCP 서버와 같은 원격 도구를 사용하는 AI 에이전트를 빌드하기 위한 클라이언트 에이전트 서비스를 구현하고 배포하는 데 중점을 둡니다. 이 실습에서 보여주는 핵심 아키텍처 원칙은 관심사 분리입니다. 즉, 별도의 추론 레이어(에이전트)가 보안 API를 통해 별도의 도구 레이어(MCP 서버)와 통신합니다.

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

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

기본 요건

• Cloud Run에서 실행 중인 MCP 서버 또는 연결된 서비스 URL
• 결제가 사용 설정된 Google Cloud 프로젝트.

학습할 내용

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

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

필요한 항목

• Google Cloud 계정 및 Google Cloud 프로젝트
• 웹브라우저(예: Chrome)

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

2. 다음으로 다음 명령어를 실행하여 가상 환경을 만듭니다.

   uv venv

3. 다음 명령어를 실행하여 가상 환경을 활성화합니다.

   source .venv/bin/activate

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

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

   cloudshell edit requirements.txt

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

   google-adk==1.12.0 langchain-community wikipedia

6. 터미널에서 다음 명령어를 실행하여 uv 패킷 관리자가 Python 패키지를 설치하도록 합니다.

   uv pip install -r requirements.txt

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

   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이 시간 초과 시 또는 다시 시작되는 경우 위의 변수를 다시 초기화해야 합니다.

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

   cloudshell edit .env

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

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

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

보안 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

1단계: 라이브러리 가져오기 및 초기 설정 수행

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

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

  import os import logging import google.cloud.logging from dotenv import load_dotenv 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")

2단계: 도구(에이전트의 기능) 정의

에이전트의 성능은 사용할 수 있는 도구에 따라 달라집니다. 이 섹션에서는 데이터 저장을 위한 커스텀 함수, 보안 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 Toolset
• 함수 도구
• 상태

3단계: 전문가 에이전트 정의

이 섹션에서는 연구원 에이전트와 대답 포맷터 에이전트라는 두 가지 전문가 에이전트를 정의합니다. 연구원 에이전트는 작업의 '두뇌'입니다. 이 에이전트는 공유된 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 }} """ )

4단계: 워크플로 에이전트 정의

워크플로 에이전트는 동물원 투어의 '백오피스' 관리자 역할을 합니다. 조사 요청을 받아들이고 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 ] )

5단계: 기본 워크플로 구성

주요 워크플로는 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 서비스가 사용자를 대신하여 Vertex AI 모델을 호출할 수 있도록 하는 중요한 IAM 권한을 구성한다는 것입니다. 이 단계를 완료하면 클라우드 환경에서 에이전트를 성공적으로 실행할 수 있습니다.

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

   source .env

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

   # Grant the "Vertex AI 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

배포 링크 가져오기

• 에이전트가 Cloud Run에 성공적으로 배포되면 출력에서 서비스 URL을 Ctrl+클릭하여 새 브라우저 탭에서 엽니다.

  다음 형식과 유사해야 합니다. 서비스 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을 열거나 출력에서 URL을 클릭합니다(새 브라우저 탭에서 열림). 그러면 ADK 개발자 UI가 열립니다.

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

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

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

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

   "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 can I find penguins?

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

   

에이전트 흐름 설명

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

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

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

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

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

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

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

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

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

• 동물원 기록의 내부 데이터(MCP 서버를 통해)
• 웹의 일반적인 지식(Wikipedia API를 통해)
• 복잡한 질문인 경우 둘 다

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

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

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

역할: 동물원 투어 가이드의 친절한 목소리 역할을 합니다. 이 레이어는 원시 데이터(하나 또는 두 소스 모두에서 가져올 수 있음)를 가져와서 다듬습니다.

작업: 모든 정보를 하나의 일관성 있고 흥미로운 답변으로 종합합니다. 지시에 따라 먼저 특정 동물원에 대한 정보를 제시한 다음 흥미로운 일반적인 사실을 추가합니다.

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

다음 단계/더 학습하기

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

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

작업 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 명령줄 인터페이스를 사용하여 배포할 Python 프로젝트를 구조화하는 방법을 알아보고, 멀티 에이전트 워크플로를 구현하고, 원격 MCP 서버에 연결하여 해당 도구를 사용하고, Wikipedia API와 같은 외부 도구를 통합하여 내부 데이터를 보강하고, 에이전트를 서버리스 컨테이너로 Cloud Run에 배포하는 과정을 살펴보았습니다.

설명서 최종 업데이트: 2025년 10월 13일

실습 최종 테스트: 2025년 10월 13일

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