이 페이지는 Cloud Translation API를 통해 번역되었습니다.

ADK 에이전트와 함께 Cloud Run에서 MCP 서버 사용

1. 소개

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

실습 1에서는 Gemini CLI를 사용하는 경우와 같이 가상 동물원의 동물에 관한 데이터를 LLM에 제공하는 MCP 서버를 만들었습니다. 이 실습에서는 가상의 동물원용 투어 가이드 에이전트를 빌드합니다. 에이전트는 실습 1의 동일한 MCP 서버를 사용하여 동물원 동물에 관한 세부정보에 액세스하고 위키피디아를 사용하여 최고의 투어 가이드 환경을 만듭니다.

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

기본 요건

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

학습할 내용

ADK 배포를 위해 Python 프로젝트를 구조화하는 방법
google-adk로 도구 사용 에이전트를 구현하는 방법
도구 세트를 위해 에이전트를 원격 MCP 서버에 연결하는 방법
Python 애플리케이션을 서버리스 컨테이너로 Cloud Run에 배포하는 방법
IAM 역할을 사용하여 보안 서비스 간 인증을 구성하는 방법
향후 비용이 발생하지 않도록 Cloud 리소스를 삭제하는 방법

필요한 항목

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

2. Cloud Run에 배포해야 하는 이유

Cloud Run은 서버리스 플랫폼이므로 ADK 에이전트를 호스팅하는 데 적합합니다. 즉, 기본 인프라 관리가 아닌 코드에 집중할 수 있습니다. Google에서 운영 작업을 처리해 드립니다.

팝업 매장과 비슷하다고 생각하면 됩니다. 고객 (요청)이 도착할 때만 리소스를 열고 사용합니다. 고객이 없으면 완전히 폐쇄되므로 빈 매장에 대한 비용을 지불하지 않아도 됩니다.

주요 기능

어디서나 컨테이너 실행:

앱이 포함된 컨테이너 (Docker 이미지)를 가져옵니다.
Cloud Run은 Google 인프라에서 이를 실행합니다.
OS 패치, VM 설정, 확장 관련 문제가 없습니다.

자동 확장:

앱을 사용하는 사람이 0명인 경우 → 인스턴스가 0개 실행됩니다 (유휴 상태일 때 $0 지불).
1,000개의 요청이 발생하면 필요한 만큼의 복사본이 생성됩니다.

기본적으로 스테이트리스:

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

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

Linux 컨테이너에서 실행되는 한 Cloud Run은 Python, Go, Node.js, Java, .Net인지 신경 쓰지 않습니다.

사용한 만큼만 비용 지불:

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

3. 설정 및 요구사항

자습형 환경 설정

Google Cloud Console에 로그인하여 새 프로젝트를 만들거나 기존 프로젝트를 재사용합니다. 아직 Gmail이나 Google Workspace 계정이 없는 경우 계정을 만들어야 합니다.

프로젝트 이름은 이 프로젝트 참가자의 표시 이름입니다. 이는 Google API에서 사용하지 않는 문자열이며 언제든지 업데이트할 수 있습니다.
프로젝트 ID는 모든 Google Cloud 프로젝트에서 고유하며, 변경할 수 없습니다(설정된 후에는 변경할 수 없음). Cloud 콘솔은 고유한 문자열을 자동으로 생성합니다. 일반적으로는 신경 쓰지 않아도 됩니다. 대부분의 Codelab에서는 프로젝트 ID (일반적으로 PROJECT_ID로 식별됨)를 참조해야 합니다. 생성된 ID가 마음에 들지 않으면 다른 임의 ID를 생성할 수 있습니다. 또는 직접 시도해 보고 사용 가능한지 확인할 수도 있습니다. 이 단계 이후에는 변경할 수 없으며 프로젝트 기간 동안 유지됩니다.
참고로 세 번째 값은 일부 API에서 사용하는 프로젝트 번호입니다. 이 세 가지 값에 대한 자세한 내용은 문서를 참고하세요.

다음으로 Cloud 리소스/API를 사용하려면 Cloud 콘솔에서 결제를 사용 설정해야 합니다. 이 Codelab 실행에는 많은 비용이 들지 않습니다. 이 튜토리얼이 끝난 후에 요금이 청구되지 않도록 리소스를 종료하려면 만든 리소스 또는 프로젝트를 삭제하면 됩니다. Google Cloud 신규 사용자는 300달러(USD) 상당의 무료 체험판 프로그램에 참여할 수 있습니다.

Cloud Shell 시작

Cloud Shell 편집기로 이동합니다.

터미널이 화면 하단에 표시되지 않으면 다음 단계에 따라 엽니다.

터미널을 클릭합니다.
새 터미널을 클릭합니다.

터미널에서 다음 명령어를 사용하여 프로젝트를 설정합니다. 실습 1을 완료한 경우 동일한 프로젝트 ID를 사용하고 있는지 확인하세요.

gcloud config set project [YOUR-PROJECT-ID]

프로젝트 ID가 기억나지 않는 경우 다음을 사용하여 모든 프로젝트 ID를 나열할 수 있습니다.

gcloud projects list | awk '/PROJECT_ID/{print $2}'

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

5. 다음 메시지가 표시되어야 합니다.

Updated property [core/project].

If you see a `WARNING` and are asked `Do you want to continue (Y/n)?`,

then you have likely entered the project ID incorrectly. Press `n`,

press `Enter`, and try to run the `gcloud config set project` command again.

4. 시작하기 전에

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

필요한 모든 서비스를 사용 설정합니다.

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

예상 출력

Operation "operations/acat.p2-[GUID]" finished successfully.

Vertex AI 임베딩 모델을 사용하도록 기본 리전을 구성합니다. Vertex AI에 사용할 수 있는 위치에 대해 자세히 알아보세요. 이 예에서는 europe-west1 리전을 사용합니다.

gcloud config set compute/region europe-west1

5. ADK 다운로드 및 설치, 프로젝트 폴더 생성

프로젝트 디렉터리를 만듭니다.

이 명령어는 에이전트 소스 코드의 실습용 기본 폴더를 만듭니다.

cd && mkdir zoo_guide_agent && cd zoo_guide_agent

가상 환경을 만듭니다.

python3 -m venv .venv

가상 환경 활성화

source .venv/bin/activate

requirements.txt 파일을 생성합니다. 이 파일에는 에이전트에 필요한 Python 라이브러리가 나열됩니다. 다음 명령어는 파일을 만들고 채웁니다.

cloudshell edit requirements.txt

google-adk==1.12.0
langchain-community
wikipedia

기본 프로젝트 디렉터리(zoo_guide_agent)에서 명령어를 실행해야 합니다.

pip install -r requirements.txt

현재 프로젝트, 리전, 사용자의 변수를 설정합니다. 이 방법은 이러한 명령어를 실행하는 더 강력한 방법입니다.

export PROJECT_ID=$(gcloud config get-value project)
export PROJECT_REGION=$(gcloud config get-value compute/region)
export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")
export SERVICE_ACCOUNT="${PROJECT_NUMBER}-compute@developer.gserviceaccount.com"

zoo_guide_agent 디렉터리에서 에이전트를 인증하기 위해 .env 파일을 만들고 엽니다.

cloudshell edit .env

cloudshell edit 명령어를 사용하면 터미널 위의 편집기에서 .env 파일이 열립니다. .env 파일에 다음을 입력하고 터미널로 돌아갑니다.

MODEL="gemini-2.5-flash"
SERVICE_ACCOUNT="${PROJECT_NUMBER}-compute@developer.gserviceaccount.com"

MCP 서버 URL 추가 실습 1을 완료한 경우 다음 단계에 따라 실습 1에서 만든 MCP 서버를 사용하세요.

Cloud Run 서비스 ID에 원격 MCP 서버 호출 권한 부여

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

실습 1의 MCP 서버 URL을 환경 변수에 저장합니다.

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

공개 MCP 서버 링크를 사용하는 경우 다음을 실행하고 PROJECT_NUMBER를 제공된 것으로 바꿉니다.

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

6. 에이전트 워크플로 만들기

init.py 파일 만들기

init.py 파일을 만듭니다. 이 파일은 Python에 zoo_guide_agent 디렉터리가 패키지임을 알려줍니다.

cloudshell edit __init__.py

위 명령어를 실행하면 코드 편집기가 열립니다. 다음 코드를 __init__.py에 추가합니다.

from . import agent

Create main agent.py file(기본 agent.py 파일 만들기)

main agent.py 파일을 만듭니다. 이 명령어는 Python 파일을 만들고 멀티 에이전트 시스템의 전체 코드를 붙여넣습니다.

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 🦁

이는 투어 가이드 에이전트를 실습 1에서 만든 동물원 MCP 서버에 연결하는 데 사용됩니다. 이 서버에는 동물 이름, 나이, 사육장과 같은 동물에 관한 특정 정보를 조회할 수 있는 특별한 도구가 있습니다.

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

LangchainTool 🌍

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

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

리소스:

3단계: 전문가 상담사 정의하기

다음으로 연구원 에이전트와 응답 포맷터 에이전트를 정의합니다. 리서치 에이전트는 Google의 작업에서 '두뇌' 역할을 합니다. 이 에이전트는 공유된 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단계: 워크플로 에이전트

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

방식: 자체적으로 생각하지 않는 특수한 유형의 에이전트인 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
    ]
)

마지막 단계: 기본 워크플로 조립

이 에이전트는 ADK 프레임워크가 모든 새 대화의 시작점으로 사용하는 root_agent로 지정됩니다. 기본 역할은 전체 프로세스를 오케스트레이션하는 것입니다. 대화의 첫 번째 턴을 관리하는 초기 컨트롤러 역할을 합니다.

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 파일이 완성되었습니다. 이러한 방식으로 빌드하면 각 구성요소(도구, 작업자 에이전트, 관리자 에이전트)가 최종 지능형 시스템을 만드는 데 어떤 역할을 하는지 확인할 수 있습니다. 다음은 배포입니다.

7. 배포를 위해 애플리케이션 준비

로컬 환경이 준비되면 다음 단계는 배포를 위해 Google Cloud 프로젝트를 준비하는 것입니다. 여기에는 배포 명령어와 호환되는지 확인하기 위해 에이전트의 파일 구조를 최종적으로 확인하는 작업이 포함됩니다. 더 중요한 점은 배포된 Cloud Run 서비스가 사용자를 대신하여 Vertex AI 모델을 호출할 수 있도록 하는 중요한 IAM 권한을 구성한다는 것입니다. 이 단계를 완료하면 클라우드 환경에서 에이전트를 성공적으로 실행할 수 있습니다.

source 명령어를 실행하여 변수를 셸 세션에 로드합니다.

source .env

서비스 계정에 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"

8. ADK CLI를 사용하여 에이전트 배포

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

.gcloudignore 파일 만들기

배포 시간을 줄이기 위해 .gcloudignore 파일을 만들려고 합니다. 다음 명령어를 실행하여 에이전트를 배포합니다.

cloudshell edit .gcloudignore

cloudshell edit 명령어를 사용하면 터미널 위의 편집기에서 .gcloudignore 파일이 열립니다. 파일에 다음을 작성하고 저장합니다. 그런 다음 터미널로 돌아가 다음 섹션에서 배포 명령어를 실행합니다.

.venv/

배포

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

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

gcloud run services update zoo-tour-guide \
  --region=europe-west1 \
  --update-labels=dev-tutorial=codelab-adk

프롬프트 수락

다음과 같은 메시지가 표시될 수 있습니다.

Deploying from source requires an Artifact Registry Docker repository to store built containers. A repository named [cloud-run-source-deploy] in region 
[europe-west1] will be created.

Do you want to continue (Y/n)?

Y를 입력하고 Enter 키를 누릅니다.

다음과 같은 메시지가 표시될 수 있습니다.

Allow unauthenticated invocations to [your-service-name] (y/N)?.

이 실습에서는 쉽게 테스트할 수 있도록 인증되지 않은 호출을 허용하려고 합니다. y를 입력하고 Enter 키를 누릅니다.

배포 링크 가져오기

실행이 성공하면 명령에서 배포된 Cloud Run 서비스의 URL을 제공합니다. (예: https://zoo-tour-guide-123456789.europe-west1.run.app) 다음 작업을 위해 이 URL을 복사합니다.

9. 배포된 에이전트 테스트

이제 에이전트가 Cloud Run에서 라이브 상태이므로 배포가 성공했고 에이전트가 예상대로 작동하는지 확인하는 테스트를 실행합니다. 공개 서비스 URL (예: https://zoo-tour-guide-123456789.europe-west1.run.app/)을 사용하여 ADK의 웹 인터페이스에 액세스하고 에이전트와 상호작용합니다.

웹브라우저에서 공개 Cloud Run 서비스 URL을 엽니다. --with_ui flag를 사용했으므로 ADK 개발자 UI가 표시됩니다.

오른쪽 상단에서 Token Streaming를 사용 설정합니다.

이제 동물원 상담사와 상호작용할 수 있습니다.

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?"

상담사 흐름 설명

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

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

전체 프로세스는 인사말 에이전트에서 시작됩니다.

역할: 대화를 시작합니다. 사용자에게 인사하고 어떤 동물에 대해 알고 싶은지 묻는 것이 이 프롬프트의 지침입니다.

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

핸드오프: 프롬프트를 저장하면 즉시 하위 에이전트인 tour_guide_workflow에 제어권을 전달합니다.

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

이는 기본 워크플로의 첫 번째 단계이자 작업의 '브레인'입니다. 이제 대규모 팀 대신 사용 가능한 모든 정보에 액세스할 수 있는 숙련된 단일 상담사가 있습니다.

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

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

작업: 필요한 모든 원시 데이터를 수집하기 위해 필요한 도구를 실행합니다. 예를 들어 '사자의 나이는 몇 살이고 야생에서 무엇을 먹어?'라고 물으면 MCP 서버에서 나이를, Wikipedia 도구에서 먹이 정보를 가져옵니다.

3. 응답 포맷터 (프레젠터)

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

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

작동 방식: 모든 정보를 하나의 일관되고 흥미로운 답변으로 종합합니다. 안내에 따라 먼저 특정 동물원 정보를 제시한 다음 흥미로운 일반 사실을 추가합니다.

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

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

10. 환경 정리

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

11. 축하합니다

축하합니다. Codelab을 완료했습니다.

학습한 내용

ADK 명령줄 인터페이스를 사용하여 배포할 Python 프로젝트를 구성하는 방법
SequentialAgent 및 ParallelAgent를 사용하여 멀티 에이전트 워크플로를 구현하는 방법
MCPToolset를 사용하여 원격 MCP 서버에 연결하여 도구를 사용하는 방법
Wikipedia API와 같은 외부 도구를 통합하여 내부 데이터를 보강하는 방법
adk deploy 명령어를 사용하여 에이전트를 서버리스 컨테이너로 Cloud Run에 배포하는 방법

12. 설문조사

결과:

본 튜토리얼을 어떻게 사용하실 계획인가요?

읽기만 할 계획입니다.

읽은 다음 연습 활동을 완료할 계획입니다.