1. 소개
이 Codelab에서는 데이터베이스용 MCP 도구 상자를 활용하는 에이전트 개발 키트 (ADK)를 사용하여 에이전트를 빌드합니다.
이 Codelab에서는 다음과 같이 단계별로 접근합니다.
- 호텔 데이터베이스와 샘플 데이터가 포함된 PostgreSQL용 Cloud SQL 데이터베이스를 프로비저닝합니다.
- 데이터에 대한 액세스를 제공하는 데이터베이스용 MCP 도구 상자를 설정합니다.
- MCP 도구 상자를 활용하여 사용자의 쿼리에 답변하는 에이전트 개발 키트 (ADK)를 사용하여 에이전트를 설계하고 개발합니다.
- 로컬 및 Cloud Run 서비스를 통해 Google Cloud에서 데이터베이스용 에이전트 및 MCP 도구 상자를 테스트하는 옵션을 살펴보세요.
실행할 작업
- 특정 위치의 호텔에 관한 사용자 쿼리에 답변하거나 이름으로 호텔을 검색하는 상담사를 설계, 빌드, 배포합니다.
학습할 내용
- PostgreSQL용 Cloud SQL 데이터베이스를 프로비저닝하고 샘플 데이터로 채웁니다.
- PostgreSQL용 Cloud SQL 데이터베이스 인스턴스의 데이터베이스용 MCP Toolbox를 설정합니다.
- 에이전트 개발 키트 (ADK)를 사용하여 에이전트를 설계하고 개발하여 사용자 쿼리에 답변합니다.
- 로컬 환경에서 데이터베이스용 에이전트 및 MCP 도구 상자를 테스트합니다.
- (선택사항) Google Cloud에 데이터베이스용 에이전트 및 MCP 도구 상자를 배포합니다.
필요한 항목
- Chrome 웹브라우저
- Gmail 계정
- 결제가 사용 설정된 Cloud 프로젝트
이 Codelab은 초보자를 포함한 모든 수준의 개발자를 위해 설계되었으며 샘플 애플리케이션에서 Python을 사용합니다. 하지만 Python 지식이 없어도 소개된 개념을 이해하는 데는 문제가 없습니다.
2. 시작하기 전에
프로젝트 만들기
- Google Cloud 콘솔의 프로젝트 선택기 페이지에서 Google Cloud 프로젝트를 선택하거나 만듭니다.
- Cloud 프로젝트에 결제가 사용 설정되어 있는지 확인합니다. 프로젝트에 결제가 사용 설정되어 있는지 확인하는 방법을 알아보세요 .
- bq가 미리 로드되어 제공되는 Google Cloud에서 실행되는 명령줄 환경인 Cloud Shell을 사용합니다. Google Cloud 콘솔 상단에서 Cloud Shell 활성화를 클릭합니다.
- Cloud Shell에 연결되면 다음 명령어를 사용하여 이미 인증되었는지, 프로젝트가 프로젝트 ID로 설정되어 있는지 확인합니다.
gcloud auth list
- Cloud Shell에서 다음 명령어를 실행하여 gcloud 명령어가 프로젝트를 알고 있는지 확인합니다.
gcloud config list project
- 프로젝트가 설정되지 않은 경우 다음 명령어를 사용하여 설정합니다.
gcloud config set project <YOUR_PROJECT_ID>
- 아래 명령어를 통해 필수 API를 사용 설정합니다. 이 작업은 몇 분 정도 걸릴 수 있으니 기다려 주시기 바랍니다.
gcloud services enable cloudresourcemanager.googleapis.com \
servicenetworking.googleapis.com \
run.googleapis.com \
cloudbuild.googleapis.com \
cloudfunctions.googleapis.com \
aiplatform.googleapis.com \
sqladmin.googleapis.com \
compute.googleapis.com
명령어 실행이 성공하면 아래와 유사한 메시지가 표시됩니다.
Operation "operations/..." finished successfully.
gcloud 명령어 대신 각 제품을 검색하거나 이 링크를 사용하여 콘솔을 통해 수행할 수도 있습니다.
누락된 API가 있으면 구현 과정에서 언제든지 사용 설정할 수 있습니다.
gcloud 명령어 및 사용법은 문서를 참조하세요.
3. Cloud SQL 인스턴스 만들기
PostgreSQL용 Google Cloud SQL 인스턴스를 사용하여 호텔 데이터를 저장합니다. PostgreSQL용 Cloud SQL은 Google Cloud Platform에서 PostgreSQL 관계형 데이터베이스를 설정, 유지, 관리할 수 있는 완전 관리형 데이터베이스 서비스입니다.
Cloud Shell에서 다음 명령어를 실행하여 인스턴스를 만듭니다.
gcloud sql instances create hoteldb-instance \
--database-version=POSTGRES_15 \
--cpu=2 \
--memory=8GiB \
--region=us-central1 \
--edition=ENTERPRISE \
--root-password=postgres
이 명령어를 실행하는 데 3~5분 정도 걸립니다. 명령어가 실행되면 NAME, DATABASE_VERSION, LOCATION과 같은 Cloud SQL 인스턴스 정보와 함께 명령어 실행 완료를 나타내는 출력이 표시됩니다.
4. 호텔 데이터베이스 준비
이제 호텔 상담사를 위한 샘플 데이터를 만들어 보겠습니다.
Cloud 콘솔에서 Cloud SQL 페이지로 이동합니다.hoteldb-instance가 준비되고 생성된 것을 볼 수 있습니다. 아래와 같이 인스턴스 이름 (hoteldb-instance)을 클릭합니다.
Cloud SQL 왼쪽 메뉴에서 아래와 같이 Cloud SQL Studio 메뉴 옵션으로 이동합니다.
그러면 Cloud SQL Studio에 로그인하라는 메시지가 표시됩니다. 이 Cloud SQL Studio를 통해 몇 가지 SQL 명령어를 제공할 예정입니다. 데이터베이스 옵션에 postgres를 선택하고 사용자와 비밀번호 모두에 사용할 값은 postgres입니다. AUTHENTICATE 아이콘을 클릭합니다.
먼저 아래에 나온 스키마에 따라 호텔 테이블을 만들어 보겠습니다. Cloud SQL Studio의 편집기 창 중 하나에서 다음 SQL을 실행합니다.
CREATE TABLE hotels(
id INTEGER NOT NULL PRIMARY KEY,
name VARCHAR NOT NULL,
location VARCHAR NOT NULL,
price_tier VARCHAR NOT NULL,
checkin_date DATE NOT NULL,
checkout_date DATE NOT NULL,
booked BIT NOT NULL
);
이제 hotels 테이블을 샘플 데이터로 채워 보겠습니다. 다음 SQL을 실행합니다.
INSERT INTO hotels(id, name, location, price_tier, checkin_date, checkout_date, booked)
VALUES
(1, 'Hilton Basel', 'Basel', 'Luxury', '2024-04-22', '2024-04-20', B'0'),
(2, 'Marriott Zurich', 'Zurich', 'Upscale', '2024-04-14', '2024-04-21', B'0'),
(3, 'Hyatt Regency Basel', 'Basel', 'Upper Upscale', '2024-04-02', '2024-04-20', B'0'),
(4, 'Radisson Blu Lucerne', 'Lucerne', 'Midscale', '2024-04-24', '2024-04-05', B'0'),
(5, 'Best Western Bern', 'Bern', 'Upper Midscale', '2024-04-23', '2024-04-01', B'0'),
(6, 'InterContinental Geneva', 'Geneva', 'Luxury', '2024-04-23', '2024-04-28', B'0'),
(7, 'Sheraton Zurich', 'Zurich', 'Upper Upscale', '2024-04-27', '2024-04-02', B'0'),
(8, 'Holiday Inn Basel', 'Basel', 'Upper Midscale', '2024-04-24', '2024-04-09', B'0'),
(9, 'Courtyard Zurich', 'Zurich', 'Upscale', '2024-04-03', '2024-04-13', B'0'),
(10, 'Comfort Inn Bern', 'Bern', 'Midscale', '2024-04-04', '2024-04-16', B'0');
아래와 같이 SELECT SQL을 실행하여 데이터를 검증해 보겠습니다.
SELECT * FROM hotels;
아래와 같이 hotels 테이블에 여러 레코드가 표시됩니다.
Cloud SQL 인스턴스 설정 프로세스를 완료하고 샘플 데이터를 만들었습니다. 다음 섹션에서는 데이터베이스용 MCP 도구 상자를 설정합니다.
5. 데이터베이스용 MCP 도구 상자 설정
데이터베이스용 MCP 도구 상자는 데이터베이스를 위한 오픈소스 MCP 서버로, 엔터프라이즈급 및 프로덕션 품질을 염두에 두고 설계되었습니다. 이를 통해 연결 풀링, 인증 등의 복잡성을 처리하여 도구를 더 쉽고 빠르고 안전하게 개발할 수 있습니다.
Toolbox를 사용하면 상담사가 데이터베이스의 데이터에 액세스할 수 있는 생성형 AI 도구를 빌드할 수 있습니다. Toolbox는 다음을 제공합니다.
- 간소화된 개발: 10줄 미만의 코드로 도구를 상담사에게 통합하고, 여러 상담사 또는 프레임워크 간에 도구를 재사용하며, 새 버전의 도구를 더 쉽게 배포할 수 있습니다.
- 성능 개선: 연결 풀링, 인증 등의 권장사항
- 보안 강화: 통합 인증을 통해 데이터에 더 안전하게 액세스
- 엔드 투 엔드 관측 가능성: OpenTelemetry를 기본적으로 지원하는 즉시 사용 가능한 측정항목 및 추적
Toolbox는 애플리케이션의 오케스트레이션 프레임워크와 데이터베이스 사이에 있으며 도구를 수정, 배포 또는 호출하는 데 사용되는 제어 영역을 제공합니다. 도구를 저장하고 업데이트할 수 있는 중앙 위치를 제공하여 도구 관리를 간소화하므로 상담사와 애플리케이션 간에 도구를 공유하고 애플리케이션을 다시 배포하지 않고도 이러한 도구를 업데이트할 수 있습니다.
데이터베이스용 MCP 도구 상자에서 지원하는 데이터베이스 중 하나가 Cloud SQL이며 이전 섹션에서 프로비저닝한 것을 확인할 수 있습니다.
도구 상자 설치
Cloud Shell 터미널을 열고 mcp-toolbox라는 폴더를 만듭니다.
mkdir mcp-toolbox
아래 명령어를 통해 mcp-toolbox 폴더로 이동합니다.
cd mcp-toolbox
아래 스크립트를 통해 데이터베이스용 MCP 도구 상자의 바이너리 버전을 설치합니다.
export VERSION=0.6.0
curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox
chmod +x toolbox
이제 사용할 준비가 된 도구 상자의 바이너리 버전이 있습니다. 다음 단계는 데이터 소스 및 기타 구성으로 도구 상자를 구성하는 것입니다.
tools.yaml 구성
Toolbox를 구성하는 기본 방법은 tools.yaml 파일을 사용하는 것입니다. 동일한 폴더(mcp-toolbox)에 tools.yaml라는 파일을 만듭니다. 이 파일의 내용은 아래와 같습니다.
Cloud Shell에서 제공되는 nano 편집기를 사용할 수 있습니다. nano 명령어는 다음과 같습니다. 'nano tools.yaml'.
YOUR_PROJECT_ID 값을 Google Cloud 프로젝트 ID로 바꿔야 합니다.
sources:
my-cloud-sql-source:
kind: cloud-sql-postgres
project: YOUR_PROJECT_ID
region: us-central1
instance: hoteldb-instance
database: postgres
user: postgres
password: postgres
tools:
search-hotels-by-name:
kind: postgres-sql
source: my-cloud-sql-source
description: Search for hotels based on name.
parameters:
- name: name
type: string
description: The name of the hotel.
statement: SELECT * FROM hotels WHERE name ILIKE '%' || $1 || '%';
search-hotels-by-location:
kind: postgres-sql
source: my-cloud-sql-source
description: Search for hotels based on location.
parameters:
- name: location
type: string
description: The location of the hotel.
statement: SELECT * FROM hotels WHERE location ILIKE '%' || $1 || '%';
toolsets:
my_first_toolset:
- search-hotels-by-name
- search-hotels-by-location
파일을 간단히 살펴보겠습니다.
Sources는 도구가 상호작용할 수 있는 다양한 데이터 소스를 나타냅니다. 소스는 도구가 상호작용할 수 있는 데이터 소스를 나타냅니다. tools.yaml 파일의 소스 섹션에서Sources를 맵으로 정의할 수 있습니다. 일반적으로 소스 구성에는 데이터베이스에 연결하고 상호작용하는 데 필요한 모든 정보가 포함됩니다. 이 경우 사용자 인증 정보로 PostgreSQL용 Cloud SQL 인스턴스를 가리키는 단일 소스를 구성했습니다. 자세한 내용은 소스 참조를 참고하세요.Tools: 소스 읽기 및 쓰기와 같이 에이전트가 취할 수 있는 작업을 정의합니다. 도구는 상담사가 취할 수 있는 작업(예: SQL 문 실행)을 나타냅니다. tools.yaml 파일의 tools 섹션에서Tools를 맵으로 정의할 수 있습니다. 일반적으로 도구는 작업할 소스가 필요합니다. 이 경우 두 가지 도구(search-hotels-by-name및search-hotels-by-location)를 정의하고 SQL 및 매개변수와 함께 작업할 소스를 지정합니다. 자세한 내용은 도구 참조를 참고하세요.- 마지막으로 함께 로드할 도구 그룹을 정의할 수 있는
Toolset가 있습니다. 이는 상담사 또는 애플리케이션을 기반으로 여러 그룹을 정의하는 데 유용할 수 있습니다. 여기서는 정의한 두 가지 도구가 포함된 단일 도구 모음인my_first_toolset이 있습니다.
데이터베이스 서버용 MCP 도구 상자 실행
mcp-toolbox 폴더에서 다음 명령어를 실행하여 서버를 시작합니다.
./toolbox --tools-file "tools.yaml"
서버가 데이터 소스에 연결되고 도구 모음과 도구를 로드했음을 나타내는 출력이 표시되는 것이 좋습니다. 샘플 출력은 다음과 같습니다.
./toolbox --tools-file "tools.yaml"
2025-04-23T14:32:29.564903079Z INFO "Initialized 1 sources."
2025-04-23T14:32:29.565009291Z INFO "Initialized 0 authServices."
2025-04-23T14:32:29.565070176Z INFO "Initialized 2 tools."
2025-04-23T14:32:29.565120847Z INFO "Initialized 2 toolsets."
2025-04-23T14:32:29.565510068Z INFO "Server ready to serve!"
MCP 도구 상자 서버는 기본적으로 포트 5000에서 실행됩니다. 포트 5000가 이미 사용 중인 경우 아래 명령어에 따라 다른 포트 (예: 7000)를 사용해도 됩니다. 후속 명령어에서 5000 포트 대신 7000를 사용하세요.
./toolbox --tools-file "tools.yaml" --port 7000
Cloud Shell을 사용하여 테스트해 보겠습니다.
아래와 같이 Cloud Shell에서 웹 미리보기를 클릭합니다.
포트 변경을 클릭하고 아래와 같이 포트를 5000으로 설정한 다음 변경 및 미리보기를 클릭합니다.
다음과 같은 출력이 표시됩니다.
브라우저 URL에서 URL 끝에 다음을 추가합니다.
/api/toolset
이렇게 하면 현재 구성된 도구가 표시됩니다. 샘플 출력은 다음과 같습니다.
{
"serverVersion": "0.3.0+container.12222fe27ae070f2689a0632d60fda45412d1f97",
"tools": {
"search-hotels-by-location": {
"description": "Search for hotels based on location.",
"parameters": [
{
"name": "location",
"type": "string",
"description": "The location of the hotel.",
"authSources": []
}
]
},
"search-hotels-by-name": {
"description": "Search for hotels based on name.",
"parameters": [
{
"name": "name",
"type": "string",
"description": "The name of the hotel.",
"authSources": []
}
]
}
}
}
데이터베이스용 MCP 도구 키트는 도구를 검증하고 테스트하는 Python 방식을 설명하며, 이는 여기에 설명되어 있습니다. 이 부분은 건너뛰고 다음 섹션에서 이러한 도구를 활용하는 Agent Development Kit (ADK)로 바로 이동하겠습니다.
6. 에이전트 개발 키트 (ADK)로 에이전트 작성
에이전트 개발 키트 (ADK) 설치하기
Cloud Shell에서 새 터미널 탭을 열고 다음과 같이 my-agents라는 폴더를 만듭니다. my-agents 폴더로 이동합니다.
mkdir my-agents
cd my-agents
이제 다음과 같이 venv를 사용하여 가상 Python 환경을 만들어 보겠습니다.
python -m venv .venv
다음과 같이 가상 환경을 활성화합니다.
source .venv/bin/activate
다음과 같이 langchain 종속 항목과 함께 ADK 및 데이터베이스용 MCP 도구 상자 패키지를 설치합니다.
pip install google-adk toolbox-core
이제 다음과 같이 adk 유틸리티를 호출할 수 있습니다.
adk
명령어 목록이 표시됩니다.
$ adk
Usage: adk [OPTIONS] COMMAND [ARGS]...
Agent Development Kit CLI tools.
Options:
--help Show this message and exit.
Commands:
api_server Starts a FastAPI server for agents.
create Creates a new app in the current folder with prepopulated agent template.
deploy Deploys agent to hosted environments.
eval Evaluates an agent given the eval sets.
run Runs an interactive CLI for a certain agent.
web Starts a FastAPI server with Web UI for agents.
첫 번째 상담사 애플리케이션 만들기
이제 adk를 사용하여 adk create 명령어를 통해 앱 이름이 **(hotel-agent-app)**인 호텔 상담사 애플리케이션의 스켈레톤을 아래와 같이 만듭니다.
adk create hotel-agent-app
단계에 따라 다음을 선택합니다.
- 루트 에이전트의 모델을 선택하기 위한 Gemini 모델입니다.
- 백엔드로 Vertex AI를 선택합니다.
- 기본 Google 프로젝트 ID 및 리전이 표시됩니다. 기본값 자체를 선택합니다.
Choose a model for the root agent:
1. gemini-2.0-flash-001
2. Other models (fill later)
Choose model (1, 2): 1
1. Google AI
2. Vertex AI
Choose a backend (1, 2): 2
You need an existing Google Cloud account and project, check out this link for details:
https://google.github.io/adk-docs/get-started/quickstart/#gemini---google-cloud-vertex-ai
Enter Google Cloud project ID [gcp-experiments-349209]:
Enter Google Cloud region [us-central1]:
Agent created in /home/romin/hotel-agent-app:
- .env
- __init__.py
- agent.py
상담사의 기본 템플릿과 필수 파일이 생성된 폴더를 확인합니다.
먼저 .env 파일을 살펴보겠습니다. 내용은 다음과 같습니다.
GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=YOUR_GOOGLE_PROJECT_ID
GOOGLE_CLOUD_LOCATION=YOUR_GOOGLE_PROJECT_REGION
이 값은 Google Cloud 프로젝트 ID 및 위치의 각 값과 함께 Vertex AI를 통해 Gemini를 사용할 것임을 나타냅니다.
그런 다음 폴더를 모듈로 표시하고 agent.py 파일에서 에이전트를 가져오는 단일 문을 포함하는 __init__.py 파일이 있습니다.
from . import agent
마지막으로 agent.py 파일을 살펴보겠습니다. 콘텐츠는 다음과 같습니다.
from google.adk.agents import Agent
root_agent = Agent(
model='gemini-2.0-flash-001',
name='root_agent',
description='A helpful assistant for user questions.',
instruction='Answer user questions to the best of your knowledge',
)
이는 ADK로 작성할 수 있는 가장 간단한 에이전트입니다. ADK 문서 페이지에 따르면 에이전트는 특정 목표를 달성하기 위해 자율적으로 작동하도록 설계된 독립형 실행 단위입니다. 에이전트는 작업을 실행하고, 사용자와 상호작용하고, 외부 도구를 활용하고, 다른 에이전트와 협력할 수 있습니다.
특히 LLMAgent(일반적으로 에이전트라는 별칭이 지정됨)는 대규모 언어 모델(LLM)을 핵심 엔진으로 활용하여 자연어를 이해하고, 추론하고, 계획하고, 응답을 생성하고, 진행 방법이나 사용할 도구를 동적으로 결정하므로 유연한 언어 중심 작업에 적합합니다. 여기에서 LLM 에이전트에 대해 자세히 알아보세요.
agent.py의 코드를 다음과 같이 수정해 보겠습니다.
from google.adk.agents import Agent
root_agent = Agent(
model='gemini-2.0-flash-001',
name='hotel_agent',
description='A helpful assistant that answers questions about a specific city.',
instruction='Answer user questions about a specific city to the best of your knowledge. Do not answer questions outside of this.',
)
로컬에서 상담사 앱 테스트
기존 터미널 창에서 다음 명령어를 실행합니다. hotel-agent-app 폴더가 포함된 상위 폴더 (my-agents)에 있는지 확인합니다.
adk web
샘플 실행은 다음과 같습니다.
INFO: Started server process [5015]
INFO: Waiting for application startup.
+-----------------------------------------------------------------------------+
| ADK Web Server started |
| |
| For local testing, access at http://localhost:8000. |
+-----------------------------------------------------------------------------+
INFO: Application startup complete.
INFO: Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
마지막 링크를 클릭하면 에이전트를 테스트할 수 있는 웹 콘솔이 표시됩니다. 아래와 같이 브라우저에 다음이 실행된 것을 볼 수 있습니다.
왼쪽 상단에서 hotel-agent-app이 식별된 것을 볼 수 있습니다. 이제 상담사와 대화를 시작할 수 있습니다. 도시에 관해 묻는 몇 가지 프롬프트를 제공합니다. 대화의 예는 다음과 같습니다.
Cloud Shell 터미널에서 실행 중인 프로세스를 종료할 수 있습니다 (Ctrl-C).
에이전트를 테스트하는 다른 방법은 아래와 같이 my-agents 폴더에서 adk run 명령어를 사용하는 것입니다.
adk run hotel-agent-app
명령어를 사용해 보고 명령줄 (터미널)을 통해 상담사와 대화할 수 있습니다. exit를 입력하여 대화를 종료합니다.
7. 상담사를 도구에 연결
이제 에이전트를 작성하고 로컬에서 테스트하는 방법을 알게 되었습니다. 이 상담사를 도구에 연결하겠습니다. ADK 컨텍스트에서 도구는 AI 에이전트에 제공되어 에이전트가 핵심 텍스트 생성 및 추론 능력 외에도 작업을 실행하고 세상과 상호작용할 수 있는 특정 기능을 나타냅니다.
이 경우 데이터베이스용 MCP 도구 상자에서 구성한 도구를 에이전트에 제공합니다.
agent.py 파일을 다음 코드로 수정합니다. 코드에서는 기본 포트 5000을 사용하고 있지만, 다른 포트 번호를 사용하는 경우 해당 포트 번호를 사용하세요.
from google.adk.agents import Agent
from toolbox_core import ToolboxSyncClient
toolbox = ToolboxSyncClient("http://127.0.0.1:5000")
# Load single tool
# tools = toolbox.load_tool('search-hotels-by-location')
# Load all the tools
tools = toolbox.load_toolset('my_first_toolset')
root_agent = Agent(
name="hotel_agent",
model="gemini-2.0-flash",
description=(
"Agent to answer questions about hotels in a city or hotels by name."
),
instruction=(
"You are a helpful agent who can answer user questions about the hotels in a specific city or hotels by name. Use the tools to answer the question"
),
tools=tools,
)
이제 데이터베이스용 MCP 도구 상자로 구성된 PostgreSQL 데이터베이스에서 실제 데이터를 가져오는 에이전트를 테스트할 수 있습니다.
이렇게 하려면 다음 단계를 따르세요.
Cloud Shell의 터미널에서 데이터베이스용 MCP 도구 상자를 실행합니다. 이전에 테스트한 것처럼 이미 포트 5000에서 로컬로 실행 중일 수 있습니다. 그렇지 않으면 mcp-toolbox 폴더에서 다음 명령어를 실행하여 서버를 시작합니다.
./toolbox --tools_file "tools.yaml"
서버가 데이터 소스에 연결되고 도구 모음과 도구를 로드했음을 나타내는 출력이 표시되는 것이 좋습니다. 샘플 출력은 다음과 같습니다.
./toolbox --tools-file "tools.yaml"
2025-04-23T14:32:29.564903079Z INFO "Initialized 1 sources."
2025-04-23T14:32:29.565009291Z INFO "Initialized 0 authServices."
2025-04-23T14:32:29.565070176Z INFO "Initialized 2 tools."
2025-04-23T14:32:29.565120847Z INFO "Initialized 2 toolsets."
2025-04-23T14:32:29.565510068Z INFO "Server ready to serve!"
MCP 서버가 성공적으로 시작되면 다른 터미널에서 아래에 표시된 adk run (my-agents 폴더) 명령어를 통해 이전과 같이 에이전트를 실행합니다. 원하는 경우 adk web 명령어를 사용할 수도 있습니다.
$ adk run hotel-agent-app/
Log setup complete: /tmp/agents_log/agent.20250423_170001.log
To access latest log: tail -F /tmp/agents_log/agent.latest.log
Running agent hotel_agent, type exit to exit.
user: what can you do for me?
[hotel_agent]: I can help you find hotels in a specific city or search for hotels by name.
user: I would like to search for hotels
[hotel_agent]: Great, do you have a specific city or hotel name in mind?
user: Yes a specific city
[hotel_agent]: Great, which city are you interested in?
user: Basel
[hotel_agent]: OK. I found three hotels in Basel: Hilton Basel, Hyatt Regency Basel, and Holiday Inn Basel.
이제 에이전트가 데이터베이스용 MCP 도구 상자에서 구성한 두 가지 도구 (search-hotels-by-name 및 search-hotels-by-location)를 활용하고 올바른 옵션을 제공합니다. 그러면 PostgreSQL 인스턴스 데이터베이스에서 데이터를 원활하게 가져와 그에 따라 응답 형식을 지정할 수 있습니다.
이렇게 하면 에이전트 개발 키트 (ADK)를 사용하여 빌드하고 데이터베이스용 MCP 도구 상자에서 구성한 도구를 기반으로 하는 호텔 에이전트의 로컬 개발 및 테스트가 완료됩니다.
8. (선택사항) 데이터베이스용 MCP 도구 상자 및 에이전트를 Cloud Run에 배포
이전 섹션에서는 Cloud Shell 터미널을 사용하여 MCP Toolbox 서버를 실행하고 상담사와 함께 도구를 테스트했습니다. Cloud Shell 환경에서 로컬로 실행되었습니다.
이러한 애플리케이션을 호스팅할 수 있는 Google Cloud 서비스에 MCP Toolbox 서버와 에이전트를 모두 배포할 수 있습니다.
Cloud Run에서 MCP Toolbox 서버 호스팅
먼저 MCP Toolbox 서버를 시작하고 Cloud Run에서 호스팅할 수 있습니다. 그러면 다른 애플리케이션 또는 상담사 애플리케이션과 통합할 수 있는 공개 엔드포인트가 생성됩니다. Cloud Run에서 호스팅하는 방법은 여기를 참고하세요. 이제 주요 단계를 살펴보겠습니다.
새 Cloud Shell 터미널을 실행하거나 기존 Cloud Shell 터미널을 사용합니다. toolbox 바이너리와 tools.yaml가 있는 mcp-toolbox 폴더로 이동합니다.
다음 명령어를 실행합니다 (각 명령어에 대한 설명이 제공됨).
PROJECT_ID 변수를 Google Cloud 프로젝트 ID를 가리키도록 설정합니다.
export PROJECT_ID="YOUR_GOOGLE_CLOUD_PROJECT_ID"
다음으로 프로젝트에서 다음 Google Cloud 서비스가 사용 설정되어 있는지 확인합니다.
gcloud services enable run.googleapis.com \
cloudbuild.googleapis.com \
artifactregistry.googleapis.com \
iam.googleapis.com \
secretmanager.googleapis.com
Google Cloud Run에 배포할 Toolbox 서비스의 ID 역할을 할 별도의 서비스 계정을 만들어 보겠습니다. 또한 이 서비스 계정에 올바른 역할(예: Secret Manager에 액세스하고 Cloud SQL과 통신할 수 있는 기능)이 있는지 확인합니다.
gcloud iam service-accounts create toolbox-identity
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member serviceAccount:toolbox-identity@$PROJECT_ID.iam.gserviceaccount.com \
--role roles/secretmanager.secretAccessor
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member serviceAccount:toolbox-identity@$PROJECT_ID.iam.gserviceaccount.com \
--role roles/cloudsql.client
tools.yaml 파일을 비밀로 업로드합니다. Cloud Run에 Toolbox를 설치해야 하므로 Toolbox에 최신 컨테이너 이미지를 사용하고 IMAGE 변수에 이를 설정합니다.
gcloud secrets create tools --data-file=tools.yaml
export IMAGE=us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest
Cloud Run에 배포하는 익숙한 명령어의 마지막 단계는 다음과 같습니다.
gcloud run deploy toolbox \
--image $IMAGE \
--service-account toolbox-identity \
--region us-central1 \
--set-secrets "/app/tools.yaml=tools:latest" \
--args="--tools_file=/app/tools.yaml","--address=0.0.0.0","--port=8080" \
--allow-unauthenticated
이렇게 하면 구성된 tools.yaml를 사용하여 Toolbox 서버를 Cloud Run에 배포하는 프로세스가 시작됩니다. 배포가 완료되면 다음과 유사한 메시지가 표시됩니다.
Deploying container to Cloud Run service [toolbox] in project [YOUR_PROJECT_ID] region [us-central1]
OK Deploying new service... Done.
OK Creating Revision...
OK Routing traffic...
OK Setting IAM Policy...
Done.
Service [toolbox] revision [toolbox-00001-zsk] has been deployed and is serving 100 percent of traffic.
Service URL: https://toolbox-<SOME_ID>.us-central1.run.app
이제 브라우저에서 위에 나열된 Service URL를 방문할 수 있습니다. 앞서 본 'Hello World' 메시지가 표시됩니다. 또한 다음 URL을 방문하여 사용 가능한 도구를 확인할 수 있습니다.
SERVICE URL/api/toolset
Google Cloud 콘솔에서 Cloud Run으로 이동하면 Cloud Run의 서비스 목록에 사용 가능한 Toolbox 서비스가 표시됩니다.
참고: Hotel Agent를 로컬에서 계속 실행하면서 새로 배포된 Cloud Run 서비스에 연결하려면 my-agents/hotel-agent-app/agent.py 파일에서 한 가지만 변경하면 됩니다.
다음과 같이 표시됩니다.
toolbox = ToolboxTool("http://127.0.0.1:5000")
아래와 같이 Cloud Run 서비스의 서비스 URL로 변경합니다.
toolbox = ToolboxTool("CLOUD_RUN_SERVICE_URL")
앞에서 본 것처럼 adk run 또는 adk web를 사용하여 상담사 애플리케이션을 테스트합니다.
Cloud Run에 호텔 상담사 앱 배포
첫 번째 단계는 위의 안내에 따라 my-agents/hotel-agent-app/agent.py에서 로컬 호스트가 아닌 Cloud Run에서 실행 중인 Toolbox 서비스 URL을 가리키도록 변경했는지 확인하는 것입니다.
새 Cloud Shell 터미널 또는 기존 터미널 세션에서 앞에서 설정한 올바른 Python 가상 환경에 있는지 확인합니다.
먼저 아래와 같이 my-agents/hotel-agent-app 폴더에 requirements.txt 파일을 만듭니다.
google-adk
toolbox-core
my-agents 폴더로 이동하여 먼저 다음 환경 변수를 설정합니다.
export GOOGLE_CLOUD_PROJECT=YOUR_GOOGLE_CLOUD_PROJECT_ID
export GOOGLE_CLOUD_LOCATION=us-central1
export AGENT_PATH="hotel-agent-app/"
export SERVICE_NAME="hotels-service"
export APP_NAME="hotels-app"
export GOOGLE_GENAI_USE_VERTEXAI=True
마지막으로 아래와 같이 adk deploy cloud_run 명령어를 통해 Cloud Run에 에이전트 애플리케이션을 배포합니다. 서비스에 대한 인증되지 않은 호출을 허용하라는 메시지가 표시되면 지금은 'y'를 값으로 입력하세요.
adk deploy cloud_run \
--project=$GOOGLE_CLOUD_PROJECT \
--region=$GOOGLE_CLOUD_LOCATION \
--service_name=$SERVICE_NAME \
--app_name=$APP_NAME \
--with_ui \
$AGENT_PATH
그러면 Cloud Run에 호텔 상담사 애플리케이션을 배포하는 프로세스가 시작됩니다. 소스를 업로드하고 Docker 컨테이너로 패키징한 후 Artifact Registry에 푸시하고 Cloud Run에 서비스를 배포합니다. 이 작업은 몇 분 정도 걸릴 수 있으니 기다려 주시기 바랍니다.
아래와 유사한 메시지가 표시됩니다.
Start generating Cloud Run source files in /tmp/cloud_run_deploy_src/20250424_045623
Copying agent source code...
Copying agent source code complete.
Creating Dockerfile...
Creating Dockerfile complete: /tmp/cloud_run_deploy_src/20250424_045623/Dockerfile
Deploying to Cloud Run...
Building using Dockerfile and deploying container to Cloud Run service [hotels-service] in project [YOUR_GOOGLE_CLOUD_PROJECT] region [us-central1]
| Building and deploying... Uploading sources.
| Uploading sources...
OK Building and deploying... Done.
OK Uploading sources...
OK Building Container... Logs are available at [https://console.cloud.google.com/cloud-build/builds;region=us-central1/b02f5a74-6da6-4367-aaba-0c8aa098edf5?project=415458962931].
OK Creating Revision...
OK Routing traffic...
Done.
Service [hotels-service] revision [hotels-service-00002-cpm] has been deployed and is serving 100 percent of traffic.
Service URL: https://hotels-service-<SOME_ID>.us-central1.run.app
Cleaning up the temp folder: /tmp/cloud_run_deploy_src/20250424_045623
배포가 완료되면 서비스 URL 값이 제공됩니다. 이 값을 브라우저에서 사용하여 이전에 로컬 설정에서 본 것처럼 호텔 상담사와 채팅할 수 있는 동일한 웹 애플리케이션을 볼 수 있습니다.
9. 삭제
Google Cloud 계정에 계속 요금이 청구되지 않도록 하려면 이 워크샵에서 만든 리소스를 삭제하는 것이 중요합니다. Cloud SQL 인스턴스가 삭제되며, 원하는 경우 Toolbox 및 호텔 앱을 Cloud Run에 배포한 경우 해당 서비스도 삭제됩니다.
프로젝트 및 지역에 따라 다음 환경 변수가 올바르게 설정되어 있는지 확인합니다.
export PROJECT_ID="YOUR_PROJECT_ID"
export REGION="YOUR_REGION"
다음 두 명령어는 배포한 Cloud Run 서비스를 삭제합니다.
gcloud run services delete toolbox --platform=managed --region=${REGION} --project=${PROJECT_ID} --quiet
gcloud run services delete hotels-service --platform=managed --region=${REGION} --project=${PROJECT_ID} --quiet
다음 명령어는 Cloud SQL 인스턴스를 삭제합니다.
gcloud sql instances delete hoteldb-instance
10. 축하합니다
수고하셨습니다. 데이터베이스용 MCP 도구 상자를 활용하는 에이전트 개발 키트 (ADK)를 사용하여 에이전트를 빌드했습니다.