程式碼研究室簡介
1. 簡介
在這個程式碼研究室中，您將使用 資料庫專用的 MCP Toolbox，提供 BigQuery 資料集。
您將透過本程式碼研究室，按照以下步驟逐步操作：
- 從公開的 BigQuery 資料集計畫中找出特定 BigQuery 資料集 (「Google Cloud 發布說明」)。
- 設定可連結至 BigQuery 資料集的資料庫專用 MCP Toolbox。
- 使用 Agent Development Kit (ADK) 開發代理，以便利用 MCP Toolbox 回答使用者有關 Google Cloud 發布說明的查詢
執行步驟
- 設定 MCP Toolbox for Databases，將 Google Cloud 發布說明 (公開的 BigQuery 資料集) 公開為 MCP 介面，供其他 MCP 用戶端 (IDE、工具等) 使用。
課程內容
- 探索 BigQuery 公開資料集並選擇特定資料集。
- 為要提供給 MCP 用戶的 BigQuery 公開資料集，設定 MCP 資料庫工具箱。
- 使用 Agent Development Kit (ADK) 設計及開發服務專員，以便回答使用者查詢。
- 在本機環境中測試代理程式和 MCP Toolbox for Databases。
軟硬體需求
- Chrome 網路瀏覽器。
- 本機 Python 開發環境。
2. 事前準備
建立專案
- 在 Google Cloud 控制台的專案選取器頁面中，選取或建立 Google Cloud 專案。
- 確認 Cloud 專案已啟用計費功能。瞭解如何檢查專案是否已啟用計費功能。
- 您將使用 Cloud Shell，這是在 Google Cloud 中運作的指令列環境，並已預先載入 bq。按一下 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 版本資訊網頁，如以下螢幕截圖所示：
您可以訂閱動態饋給網址，但如果我們可以直接在我們的服務專員即時通訊中詢問這些發布資訊，那就太好了。可以是簡單的查詢，例如「請更新 Google Cloud 版本資訊」。
4. MCP Toolbox for Databases
MCP Toolbox for Databases 是資料庫的開放原始碼 MCP 伺服器，設計時考量到企業級和實際工作環境的品質。它可處理連線集區、驗證等複雜作業，讓您更輕鬆、快速且安全地開發工具。
工具箱可協助您建立生成式 AI 工具，讓您的代理程式存取資料庫中的資料。工具箱提供以下功能：
- 簡化開發作業：透過不到 10 行程式碼，將工具整合至您的代理程式，在多個代理程式或架構之間重複使用工具，並更輕鬆地部署新版工具。
- 提升效能：採用連線集區、驗證等最佳做法。
- 強化安全性：整合式驗證機制，讓您更安全地存取資料
- 端對端監控：內建 OpenTelemetry 支援功能，可使用現成指標和追蹤記錄。
- Toolbox 可讓您輕鬆將資料庫連結至任何支援 MCP 的 AI 助理，甚至是 IDE 中的 AI 助理。
Toolbox 位於應用程式調度架構和資料庫之間，提供用於修改、發布或叫用工具的控制平面。這項服務可提供集中位置來儲存及更新工具，簡化工具管理作業，讓您在代理程式和應用程式之間共用工具，並更新這些工具，而無須重新部署應用程式。
簡單來說：
- MCP Toolbox 可做為二進位檔、容器映像檔使用，也可以從原始碼建構。
- 它會公開一組工具，您可以透過 tools.yaml 檔案進行設定。這些工具可連結至資料來源。您可以查看支援的各種資料來源：AlloyDB、BigQuery 等。
- 由於這個工具箱現在支援 MCP，您會自動取得 MCP 伺服器端點，可供代理程式 (IDE) 使用，或是在使用各種架構 (例如 Agent Development Kit (ADK)) 開發代理應用程式時使用。
本篇文章將著重於以下重點：
總而言之，我們將在 MCP Toolbox for Databases 中建立設定，讓系統知道如何連線至 BigQuery 資料集。接著，我們將使用 Agent Development Kit (ADK) 開發代理程式，以便整合 MCP Toolbox 端點，並傳送自然查詢來詢問資料集。您可以將其視為正在開發的代理應用程式，該應用程式會瞭解如何與 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 Toolbox for Databases 中，將這項工具設為資料來源和工具。我們來看看如何操作。
6. 安裝 MCP Toolbox for Databases
在本機電腦上開啟終端機，然後建立名為 mcp-toolbox 的資料夾。
mkdir mcp-toolbox
使用下列指令前往 mcp-toolbox 資料夾：
cd mcp-toolbox
透過下方提供的指令碼，安裝 MCP Toolbox for Databases 的二進位版本。以下指令適用於 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 Toolbox for Databases
接下來，我們需要在 MCP Toolbox for Database 所需的 tools.yaml 檔案中定義 BigQuery 資料集和工具。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
讓我們簡單瞭解這個檔案：
- 來源代表工具可互動的不同資料來源。來源代表工具可互動的資料來源。您可以在 tools.yaml 檔案的 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 Toolbox for Databases
我們已下載並設定 Toolbox，並在 mcp-toolbox 資料夾中使用 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 Toolbox 伺服器會在 5000 通訊埠上執行。如果您發現通訊埠 5000 已在使用中，可以根據下方指令使用其他通訊埠 (例如 7000)。請在後續指令中使用 7000，而非 5000 連接埠。
./toolbox --tools-file "tools.yaml" --port 7000
我們來使用 Cloud Shell 進行測試。
按一下 Cloud Shell 中的「網頁預覽」(Web Preview)，如下所示：
按一下「Change port」(變更通訊埠)，然後將通訊埠設為 5000，如以下所示，然後按一下「Change and Preview」(變更並預覽)。
這應該會產生下列輸出內容：
在瀏覽器網址中，將以下內容加入網址末端：
/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. 使用 Agent Development Kit (ADK) 編寫代理程式
安裝代理開發套件 (ADK)
在 Cloud Shell 中開啟新的終端機分頁，然後建立名為 my-agents 的資料夾，如下所示。並前往 my-agents 資料夾。
mkdir my-agents
cd my-agents
接下來，我們將使用 venv 建立虛擬 Python 環境，如下所示：
python -m venv .venv
請按照下列步驟啟用虛擬環境：
source .venv/bin/activate
安裝 ADK 和 MCP Toolbox for Databases 套件，以及 langchain 依附元件，如下所示：
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 為 Google Cloud Release Notes Agent 應用程式建立結構，方法是透過 adk create 指令，使用應用程式名稱 **(gcp-releasenotes-agent-app)** (如下所示)。
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
這些值表示我們會透過 Vertex AI 使用 Gemini，並提供 Google Cloud 專案 ID 和位置的相對應值。
接著，我們有 __init__.py 檔案，該檔案會將資料夾標示為模組，並包含單一陳述式，可從 agent.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 (通常稱為 Agent) 會使用大型語言模型 (LLM) 做為核心引擎，用於理解自然語言、推理、規劃、產生回覆，並動態決定如何進行或使用哪些工具，因此非常適合用於靈活的以語言為中心的工作。如要進一步瞭解 LLM 代理程式，請參閱這篇文章。
這樣就完成了使用 Agent Development Kit (ADK) 產生基本代理的架構。我們現在要將 Bot 連結至 MCP Toolbox，以便使用該工具回答使用者的查詢 (在本例中為 Google Cloud 發布說明)。
10. 將我們的服務專員連結至工具
我們現在要將這個代理程式連結至工具。在 ADK 的脈絡中，工具代表提供給 AI 代理的特定功能，可讓 AI 代理執行動作並與外界互動，而非僅限於核心文字生成和推理功能。
在本例中，我們會為我們的代理程式提供在 MCP Toolbox for Databases 中設定的工具。
使用下列程式碼修改 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 Toolbox for Databases。如同先前測試的結果，您可能已經在本機的 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 Toolbox for Databases (search_release_notes_bq) 中設定的工具，從 BigQuery 資料集擷取資料，並據此格式化回應。