이 Codelab 정보
1. 소개
이 Codelab에서는 데이터베이스용 MCP 도구 상자를 사용하여 BigQuery 데이터 세트를 제공합니다.
이 Codelab에서는 다음과 같이 단계별로 접근합니다.
- 공개 BigQuery 데이터 세트 프로그램에서 특정 BigQuery 데이터 세트 ('Google Cloud 출시 노트')를 찾습니다.
- BigQuery 데이터 세트에 연결되는 데이터베이스용 MCP 도구 상자를 설정합니다.
- MCP 도구 상자를 활용하여 Google Cloud 출시 노트에 관한 사용자의 쿼리에 답변하는 에이전트 개발 키트 (ADK)를 사용하여 에이전트 개발
실행할 작업
- 데이터베이스용 MCP 도구 상자를 설정하여 공개 BigQuery 데이터 세트인 Google Cloud 출시 노트를 다른 MCP 클라이언트 (IDE, 도구 등)에 MCP 인터페이스로 노출합니다.
학습할 내용
- BigQuery 공개 데이터 세트를 살펴보고 특정 데이터 세트를 선택합니다.
- MCP 클라이언트에게 제공하려는 BigQuery 공개 데이터 세트의 데이터베이스용 MCP 도구 상자를 설정합니다.
- 에이전트 개발 키트 (ADK)를 사용하여 에이전트를 설계하고 개발하여 사용자 쿼리에 답변합니다.
- 로컬 환경에서 데이터베이스용 에이전트 및 MCP 도구 상자를 테스트합니다.
필요한 항목
- Chrome 웹브라우저
- 로컬 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>
gcloud 명령어 및 사용법은 문서를 참조하세요.
3. Google 출시 노트 데이터 세트 및 MCP 클라이언트
먼저 공식 Google Cloud 출시 노트 웹페이지에서 정기적으로 업데이트되는 Google Cloud 출시 노트를 살펴보겠습니다. 스크린샷은 아래와 같습니다.
피드 URL을 구독할 수도 있지만 상담사 채팅에서 출시 노트에 관해 문의하시면 됩니다. 'Google Cloud 출시 노트 업데이트'와 같은 간단한 쿼리일 수 있습니다.
4. 데이터베이스용 MCP 도구 상자
데이터베이스용 MCP 도구 상자는 데이터베이스를 위한 오픈소스 MCP 서버로, 엔터프라이즈급 및 프로덕션 품질을 염두에 두고 설계되었습니다. 이를 통해 연결 풀링, 인증 등의 복잡성을 처리하여 도구를 더 쉽고 빠르고 안전하게 개발할 수 있습니다.
Toolbox를 사용하면 상담사가 데이터베이스의 데이터에 액세스할 수 있는 생성형 AI 도구를 빌드할 수 있습니다. Toolbox는 다음을 제공합니다.
- 간소화된 개발: 10줄 미만의 코드로 도구를 상담사에게 통합하고, 여러 상담사 또는 프레임워크 간에 도구를 재사용하며, 새 버전의 도구를 더 쉽게 배포할 수 있습니다.
- 성능 개선: 연결 풀링, 인증 등의 권장사항
- 보안 강화: 통합 인증을 통해 데이터에 더 안전하게 액세스
- 엔드 투 엔드 관측 가능성: OpenTelemetry를 기본적으로 지원하는 즉시 사용 가능한 측정항목 및 추적
- Toolbox를 사용하면 IDE에 있는 AI 어시스턴트도 포함하여 모든 MCP 지원 AI 어시스턴트에 데이터베이스를 쉽게 연결할 수 있습니다.
Toolbox는 애플리케이션의 오케스트레이션 프레임워크와 데이터베이스 사이에 있으며 도구를 수정, 배포 또는 호출하는 데 사용되는 제어 영역을 제공합니다. 도구를 저장하고 업데이트할 수 있는 중앙 위치를 제공하여 도구 관리를 간소화하므로 상담사와 애플리케이션 간에 도구를 공유하고 애플리케이션을 다시 배포하지 않고도 이러한 도구를 업데이트할 수 있습니다.
간단히 요약하자면 다음과 같습니다.
- MCP Toolbox는 바이너리, 컨테이너 이미지로 제공되며 소스에서 빌드할 수도 있습니다.
- tools.yaml 파일을 통해 구성하는 도구 세트를 노출합니다. 이 도구는 데이터 소스에 연결한다고 생각할 수 있습니다. AlloyDB, BigQuery 등 지원되는 다양한 데이터 소스를 확인할 수 있습니다.
- 이제 이 도구 상자가 MCP를 지원하므로 에이전트 (IDE)에서 사용할 수 있는 MCP 서버 엔드포인트가 자동으로 생성되며, 에이전트 개발 키트 (ADK)와 같은 다양한 프레임워크를 사용하여 에이전트 애플리케이션을 개발하는 동안 이를 사용할 수 있습니다.
이 블로그 게시물에서는 아래에 강조 표시된 영역에 중점을 둘 것입니다.
요약하면, 데이터베이스용 MCP 도구 상자에서 BigQuery 데이터 세트에 연결하는 방법을 알고 있는 구성을 만들 것입니다. 그런 다음 MCP 도구 상자 엔드포인트와 통합되고 자연 쿼리를 전송하여 데이터 세트에 관해 질문할 수 있는 에이전트 개발 키트 (ADK)를 사용하여 에이전트를 개발합니다. BigQuery 데이터 세트와 통신하는 방법을 알고 일부 쿼리를 실행하는 개발 중인 대리 애플리케이션이라고 생각하면 됩니다.
5. Google Cloud 출시 노트용 BigQuery 데이터 세트
Google Cloud 공개 데이터 세트 프로그램은 애플리케이션에 다양한 데이터 세트를 제공하는 프로그램입니다. 이러한 데이터 세트 중 하나는 Google Cloud 출시 노트 데이터베이스입니다. 이 데이터 세트는 공식 Google Cloud 출시 노트 웹페이지와 동일한 정보를 제공하며 공개적으로 쿼리할 수 있는 데이터 세트로 제공됩니다.
테스트로 아래와 같은 간단한 쿼리를 실행하여 데이터 세트의 유효성을 검사합니다.
SELECT
product_name,description,published_at
FROM
`bigquery-public-data`.`google_cloud_release_notes`.`release_notes`
WHERE
DATE(published_at) >= DATE_SUB(CURRENT_DATE(), INTERVAL 7 DAY)
GROUP BY product_name,description,published_at
ORDER BY published_at DESC
이렇게 하면 지난 7일 동안 게시된 출시 노트 데이터 세트의 레코드 목록이 표시됩니다.
원하는 다른 데이터 세트와 원하는 각 쿼리 및 매개변수로 대체합니다. 이제 데이터베이스용 MCP 도구 상자에서 이를 데이터 소스 및 도구로 설정하기만 하면 됩니다. 방법을 알아보겠습니다.
6. 데이터베이스용 MCP 도구 상자 설치
로컬 머신에서 터미널을 열고 mcp-toolbox라는 폴더를 만듭니다.
mkdir mcp-toolbox
아래 명령어를 통해 mcp-toolbox 폴더로 이동합니다.
cd mcp-toolbox
아래 스크립트를 통해 데이터베이스용 MCP 도구 상자의 바이너리 버전을 설치합니다. 아래에 나와 있는 명령어는 Linux용이지만 Mac 또는 Windows를 사용하는 경우 올바른 바이너리를 다운로드해야 합니다. 운영체제 및 아키텍처의 출시 페이지를 확인하고 올바른 바이너리를 다운로드합니다.
export VERSION=0.7.0
curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox
chmod +x toolbox
이제 사용할 준비가 된 도구 상자의 바이너리 버전이 있습니다. 다음 단계는 데이터 소스 및 기타 구성으로 도구 상자를 구성하는 것입니다.
7. 데이터베이스용 MCP 도구 상자 구성
이제 데이터베이스용 MCP 도구 상자에 필요한 BigQuery 데이터 세트와 도구를 tools.yaml 파일에서 정의해야 합니다. tools.yaml 파일은 Toolbox를 구성하는 기본 방법입니다.
동일한 폴더(mcp-toolbox)에 tools.yaml라는 파일을 만들고 아래와 같이 내용을 입력합니다.
Cloud Shell에서 제공되는 nano 편집기를 사용할 수 있습니다. nano 명령어는 다음과 같습니다. 'nano tools.yaml'.
YOUR_PROJECT_ID 값을 Google Cloud 프로젝트 ID로 바꿔야 합니다.
sources:
my-bq-source:
kind: bigquery
project: YOUR_PROJECT_ID
tools:
search_release_notes_bq:
kind: bigquery-sql
source: my-bq-source
statement: |
SELECT
product_name,description,published_at
FROM
`bigquery-public-data`.`google_cloud_release_notes`.`release_notes`
WHERE
DATE(published_at) >= DATE_SUB(CURRENT_DATE(), INTERVAL 7 DAY)
GROUP BY product_name,description,published_at
ORDER BY published_at DESC
description: |
Use this tool to get information on Google Cloud Release Notes.
toolsets:
my_bq_toolset:
- search_release_notes_bq
파일을 간단히 살펴보겠습니다.
- 소스는 도구가 상호작용할 수 있는 다양한 데이터 소스를 나타냅니다. 소스는 도구가 상호작용할 수 있는 데이터 소스를 나타냅니다. sources 섹션에서 sources를 맵으로 정의할 수 있습니다. 일반적으로 소스 구성에는 데이터베이스에 연결하고 상호작용하는 데 필요한 모든 정보가 포함됩니다. 이 경우 BigQuery 소스
my-bq-source를 정의했으며 Google Cloud 프로젝트 ID를 제공해야 합니다. 자세한 내용은 소스 참조를 참고하세요. - 도구는 소스 읽기 및 쓰기와 같이 에이전트가 취할 수 있는 작업을 정의합니다. 도구는 상담사가 취할 수 있는 작업(예: SQL 문 실행)을 나타냅니다. tools.yaml 파일의 tools 섹션에서 도구를 맵으로 정의할 수 있습니다. 일반적으로 도구는 작업할 소스가 필요합니다. 이 경우 단일 도구
search_release_notes_bq를 정의합니다. 이는 첫 번째 단계에서 정의한 BigQuery 소스my-bq-source를 참조합니다. 또한 AI 상담사 클라이언트에서 사용할 문과 안내도 포함되어 있습니다. 자세한 내용은 도구 참조를 참고하세요. - 마지막으로 함께 로드할 도구 그룹을 정의할 수 있는 도구 모음이 있습니다. 이는 상담사 또는 애플리케이션을 기반으로 여러 그룹을 정의하는 데 유용할 수 있습니다. 이 경우 현재 정의된 기존 도구
search_release_notes_bq하나만 정의된 도구 모음 정의가 있습니다. 여러 도구가 조합된 도구 모음을 둘 이상 보유할 수 있습니다.
따라서 현재 쿼리에 따라 지난 7일간의 출시 노트를 가져오는 도구는 하나만 정의되어 있습니다. 하지만 매개변수와도 다양한 조합을 사용할 수 있습니다.
데이터베이스용 MCP Toolbox의 BigQuery 데이터 소스 구성에서 구성 세부정보 ( 소스, 도구)를 확인합니다.
8. 데이터베이스용 MCP 도구 상자 테스트
mcp-toolbox 폴더에 있는 tools.yaml 파일로 Toolbox를 다운로드하고 구성했습니다. 먼저 로컬에서 실행해 보겠습니다.
다음 명령어를 실행합니다.
./toolbox --tools-file="tools.yaml"
실행에 성공하면 아래와 유사한 샘플 출력과 함께 서버가 시작됩니다.
2025-06-17T07:48:52.989710733Z INFO "Initialized 1 sources."
2025-06-17T07:48:52.989805642Z INFO "Initialized 0 authServices."
2025-06-17T07:48:52.989847035Z INFO "Initialized 1 tools."
2025-06-17T07:48:52.989889742Z INFO "Initialized 2 toolsets."
2025-06-17T07:48:52.990357879Z 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.7.0+binary.linux.amd64.714d990c34ee990e268fac1aa6b89c4883ae5023",
"tools": {
"search_release_notes_bq": {
"description": "Use this tool to get information on Google Cloud Release Notes.\n",
"parameters": [],
"authRequired": []
}
}
}
데이터베이스용 MCP 도구 키트는 도구를 검증하고 테스트하는 Python 방식을 설명하며, 이는 여기에 설명되어 있습니다. 이 부분은 건너뛰고 다음 섹션에서 이러한 도구를 활용하는 Agent Development Kit (ADK)로 바로 이동하겠습니다.
9. 에이전트 개발 키트 (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 명령어를 통해 앱 이름이 **(gcp-releasenotes-agent-app)**인 Google Cloud 출시 노트 에이전트 애플리케이션의 스캐폴딩을 아래와 같이 만듭니다.
adk create gcp-releasenotes-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 [YOUR_GOOGLE_PROJECT_ID]:
Enter Google Cloud region [us-central1]:
Agent created in ../my-agents/gcp-releasenotes-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 에이전트에 대해 자세히 알아보세요.
에이전트 개발 키트 (ADK)를 사용하여 기본 에이전트를 생성하기 위한 스캐폴딩이 완료되었습니다. 이제 에이전트가 MCP Toolbox에 연결되도록 하여 이 도구를 사용하여 사용자의 쿼리에 답변할 수 있도록 합니다 (이 경우 Google Cloud 출시 노트).
10. 상담사를 도구에 연결
이제 이 상담사를 도구에 연결하겠습니다. 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 all the tools
tools = toolbox.load_toolset('my_bq_toolset')
root_agent = Agent(
name="gcp_releasenotes_agent",
model="gemini-2.0-flash",
description=(
"Agent to answer questions about Google Cloud Release notes."
),
instruction=(
"You are a helpful agent who can answer user questions about the Google Cloud Release notes. Use the tools to answer the question"
),
tools=tools,
)
이제 데이터베이스용 MCP 도구 상자로 구성된 BigQuery 데이터 세트에서 실제 데이터를 가져오는 에이전트를 테스트할 수 있습니다.
이렇게 하려면 다음 단계를 따르세요.
Cloud Shell의 터미널에서 데이터베이스용 MCP 도구 상자를 실행합니다. 이전에 테스트한 것처럼 이미 포트 5000에서 로컬로 실행 중일 수 있습니다. 그렇지 않으면 mcp-toolbox 폴더에서 다음 명령어를 실행하여 서버를 시작합니다.
./toolbox --tools_file "tools.yaml"
서버가 데이터 소스에 연결되고 도구 모음과 도구를 로드했음을 나타내는 출력이 표시되는 것이 좋습니다. 샘플 출력은 다음과 같습니다.
./toolbox --tools-file "tools.yaml"
2025-06-17T07:48:52.989710733Z INFO "Initialized 1 sources."
2025-06-17T07:48:52.989805642Z INFO "Initialized 0 authServices."
2025-06-17T07:48:52.989847035Z INFO "Initialized 1 tools."
2025-06-17T07:48:52.989889742Z INFO "Initialized 2 toolsets."
2025-06-17T07:48:52.990357879Z INFO "Server ready to serve!"
MCP 서버가 성공적으로 시작되면 다른 터미널에서 아래에 표시된 adk run (my-agents 폴더) 명령어를 통해 에이전트를 실행합니다. 원하는 경우 adk web 명령어를 사용할 수도 있습니다.
$ adk run gcp-releasenotes-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 gcp_releasenotes_agent, type exit to exit.
[user]: get me the google cloud release notes
[gcp_releasenotes_agent]: Here are the Google Cloud Release Notes.
Google SecOps SOAR: Release 6.3.49 is being rolled out to the first phase of regions. This release contains internal and customer bug fixes. Published: 2025-06-14
Compute Engine: Dynamic NICs let you add or remove network interfaces to or from an instance without having to restart or recreate the instance. You can also use Dynamic NICs when you need more network interfaces. The maximum number of vNICs for most machine types in Google Cloud is 10; however, you can configure up to 16 total interfaces by using Dynamic NICs. Published: 2025-06-13
Compute Engine: General purpose C4D machine types, powered by the fifth generation AMD EPYC processors (Turin) and Google Titanium, are generally available. Published: 2025-06-13
Google Agentspace: Google Agentspace Enterprise: App-level feature management. As an Agentspace administrator, you can choose to turn the following features on or off for your end users in the web app: Agents gallery, Prompt gallery, No-code agent, NotebookLM Enterprise. Published: 2025-06-13
Cloud Load Balancing: Cloud Load Balancing supports load balancing to multi-NIC instances that use Dynamic NICs. This capability is in Preview. Published: 2025-06-13
Virtual Private Cloud: Dynamic Network Interfaces (NICs) are available in Preview. Dynamic NICs let you update an instance to add or remove network interfaces without having to restart or recreate the instance. Published: 2025-06-13
Security Command Center: The following Event Threat Detection detectors for Vertex AI have been released to Preview:
- `Persistence: New Geography for AI Service`
- `Privilege Escalation: Anomalous Multistep Service Account Delegation for AI Admin Activity`
- `Privilege Escalation: Anomalous Multistep Service Account Delegation for AI Data Access`
- `Privilege Escalation: Anomalous Service Account Impersonator for AI Admin Activity`
- `Privilege Escalation: Anomalous Service Account Impersonator for AI Data Access`
- `Privilege Escalation: Anomalous Impersonation of Service Account for AI Admin Activity`
- `Persistence: New AI API Method`
......
......
에이전트가 데이터베이스용 MCP 도구 상자 (search_release_notes_bq)에서 구성한 도구를 활용하고 BigQuery 데이터 세트에서 데이터를 가져와 그에 따라 응답 형식을 지정합니다.