使用 MCP 伺服器為 BigQuery 和 Google 地圖建構位置智慧 ADK 代理程式

1. 簡介

在本程式碼研究室中，您將使用 ADK 建構以 Gemini 3.0 Pro 為基礎的代理程式。代理程式會配備兩個遠端 (Google 代管) MCP 伺服器的工具，安全地存取 BigQuery 的人口統計、價格和銷售資料，以及 Google 地圖的實際位置分析和驗證。

這個代理程式會協調使用者和 Google Cloud 服務之間的請求，解決與虛構烘焙店資料集相關的業務問題。

執行步驟

設定資料：在 BigQuery 中建立基礎烘焙資料集。
開發代理：使用 Agent Development Kit (ADK) 建構智慧型代理。
整合工具：透過 MCP 伺服器，為代理程式提供 BigQuery 和 Google 地圖功能。
分析市場：與代理互動，評估市場趨勢和飽和度。

軟硬體需求

網路瀏覽器，例如 Chrome
已啟用計費功能的 Google Cloud 專案或 Gmail 帳戶。

本程式碼研究室適合各種程度的開發人員，包括初學者。您將使用 Google Cloud Shell 中的指令列介面和 Python 程式碼進行 ADK 開發。您不必是 Python 專家，但瞭解如何解讀程式碼有助於理解概念。

2. 事前準備

建立 Google Cloud 專案

在 Google Cloud 控制台的專案選取器頁面中，選取或建立 Google Cloud 專案。

確認 Cloud 專案已啟用計費功能。瞭解如何檢查專案是否已啟用計費功能。

啟動 Cloud Shell

Cloud Shell 是在 Google Cloud 中運作的指令列環境，已預先載入必要工具。

點選 Google Cloud 控制台頂端的「啟用 Cloud Shell」：

連線至 Cloud Shell 後，請執行下列指令，在 Cloud Shell 中驗證您的驗證狀態：

gcloud auth list

執行下列指令，確認專案已設定為搭配 gcloud 使用：

gcloud config get project

確認專案符合預期，然後執行下列指令設定專案 ID：

export PROJECT_ID=$(gcloud config get project)

3. 取得代碼

複製存放區

將存放區複製到 Cloud Shell 環境：

git clone https://github.com/google/mcp.git

cd mcp/examples/launchmybakery

驗證

執行下列指令，即可使用您的 Google Cloud 帳戶進行驗證。ADK 必須具備這項權限，才能存取 BigQuery。

gcloud auth application-default login

按照提示完成驗證程序。

4. 設定環境和 BigQuery

執行設定指令碼

執行環境設定指令碼。這個指令碼會啟用 BigQuery 和 Google 地圖 API，並建立包含專案 ID 和 Maps API 金鑰的 .env 檔案。

chmod +x setup/setup_env.sh
./setup/setup_env.sh

執行 BigQuery 設定指令碼。這個指令碼會自動建立 Cloud Storage bucket、上傳資料，以及佈建 BigQuery 資料集和資料表。

chmod +x ./setup/setup_bigquery.sh
./setup/setup_bigquery.sh

指令碼執行完畢後，系統應會建立 mcp_bakery 資料集，並填入下列資料表：

受眾特徵：依郵遞區號劃分的普查資料和人口特徵。
bakery_prices - 各種烘焙食品的競爭對手定價和產品詳細資料。
sales_history_weekly - 依商店和產品劃分的每週銷售成效 (數量和收益)。
foot_traffic - 依郵遞區號和時段估算的來店人潮分數。

前往 Google Cloud 專案中的 BigQuery 控制台，確認資料集和資料表已建立：

5. 安裝 ADK

基礎架構已準備就緒，接下來請建立虛擬 Python 環境，並安裝 ADK 必要的套件。

建立虛擬環境：

python3 -m venv .venv

啟用虛擬環境：

source .venv/bin/activate

安裝 ADK：

pip install google-adk

cd adk_agent/

6. 檢查 ADK 應用程式

在 Cloud Shell 中按一下「Open Editor」(開啟編輯器) 按鈕，開啟 Cloud Shell 編輯器，並在 mcp/examples/launchmybakery 目錄下查看複製的存放區。

代理程式碼已提供於 adk_agent/ 目錄中。讓我們來瞭解解決方案結構：

launchmybakery/
├── data/                        # Pre-generated CSV files for BigQuery
├── adk_agent/                   # AI Agent Application (ADK)
│   └── mcp_bakery_app/          # App directory
│       ├── agent.py             # Agent definition
│       ├── tools.py             # Custom tools for the agent
│       └── .env                 # Project configuration (created by setup script)
├── setup/                       # Infrastructure setup scripts
└── cleanup/                     # Infrastructure cleanup scripts

「mcp_bakery_app」中的重要檔案：

agent.py：定義代理程式、工具和模型 (Gemini 3.0 Pro 預先發布版) 的核心邏輯。
tools.py：包含任何自訂工具定義。
.env：包含專案設定和設定指令碼建立的密鑰 (例如 API 金鑰)。

1. 初始化 MCP 工具組：

現在請在編輯器中開啟 adk_agent/mcp_bakery_app/tools.py，瞭解 MCP 工具集如何初始化。

如要讓代理程式與 BigQuery 和 Google 地圖通訊，我們需要設定 Model Context Protocol (MCP) 用戶端。

程式碼會使用 StreamableHTTPConnectionParams，與 Google 的遠端 MCP 伺服器建立安全連線。

def get_maps_mcp_toolset():
    dotenv.load_dotenv()
    maps_api_key = os.getenv('MAPS_API_KEY', 'no_api_found')
    
    tools = MCPToolset(
        connection_params=StreamableHTTPConnectionParams(
            url=MAPS_MCP_URL,
            headers={    
                "X-Goog-Api-Key": maps_api_key
            }
        )
    )
    print("MCP Toolset configured for Streamable HTTP connection.")
    return tools


def get_bigquery_mcp_toolset():   
        
    credentials, project_id = google.auth.default(
            scopes=["https://www.googleapis.com/auth/bigquery"]
    )

    credentials.refresh(google.auth.transport.requests.Request())
    oauth_token = credentials.token
        
    HEADERS_WITH_OAUTH = {
        "Authorization": f"Bearer {oauth_token}",
        "x-goog-user-project": project_id
    }

    tools = MCPToolset(
        connection_params=StreamableHTTPConnectionParams(
            url=BIGQUERY_MCP_URL,
            headers=HEADERS_WITH_OAUTH
        )
    )
    print("MCP Toolset configured for Streamable HTTP connection.")
    return tools

地圖工具組：使用 API 金鑰設定與地圖 MCP 伺服器的連線。
BigQuery 工具組：此函式會設定與 BigQuery MCP 伺服器的連線。這個函式庫會使用 google.auth 自動擷取 Cloud 憑證、產生 OAuth Bearer 權杖，並將權杖插入 Authorization 標頭。

2. 代理程式定義：

現在，在編輯器中開啟 adk_agent/mcp_bakery_app/agent.py，查看代理的定義方式。

LlmAgent 會使用 gemini-3-pro-preview 模型進行初始化。

maps_toolset = tools.get_maps_mcp_toolset()
bigquery_toolset = tools.get_bigquery_mcp_toolset()

root_agent = LlmAgent(
    model='gemini-3-pro-preview',
    name='root_agent',
    instruction=f"""
                Help the user answer questions by strategically combining insights from two sources:
                
                1.  **BigQuery toolset:** Access demographic (inc. foot traffic index), product pricing, and historical sales data in the  mcp_bakery dataset. Do not use any other dataset.
                Run all query jobs from project id: {project_id}. 

                2.  **Maps Toolset:** Use this for real-world location analysis, finding competition/places and calculating necessary travel routes.
                    Include a hyperlink to an interactive map in your response where appropriate.
            """,
    tools=[maps_toolset, bigquery_toolset]
)

系統指令：系統會提供具體指令，要求代理程式整合 BigQuery (資料) 和 Google 地圖 (位置分析) 的洞察資料。
工具：maps_toolset 和 bigquery_toolset 都指派給代理，讓代理能存取這兩項服務的功能。

代理程式會遵守存放區中定義的指令和工具。歡迎變更指令，看看這對代理程式的行為有何影響。

7. 與虛擬服務專員對話！

返回 Cloud Shell 中的終端機，然後執行下列指令，前往 adk_agent 目錄：

cd adk_agent

執行下列指令，啟動 ADK 網頁介面。這個指令會啟動輕量型網路伺服器，用來代管即時通訊應用程式：

adk web

伺服器啟動後，按一下提供的網址啟動 ADK 網頁介面，即可與代理程式對話。

與代理程式互動，提出下列問題。您應該會看到系統呼叫相關工具。

找出鄰近區域 (巨集)：「我想在洛杉磯開一家烘焙坊，找出上午人潮流量分數最高的郵遞區號。

代理程式應使用 get_table_info 和 execute_sql 等工具，查詢 BigQuery 中的 foot_traffic 資料表。

驗證位置 (微觀)：「您可以在該郵遞區號中搜尋『麵包店』，看看是否已飽和嗎？」

代理程式應使用地圖工具集中的 search places 工具回答這個問題。

快來試試看！請參閱下列範例問題，瞭解 ADK 代理的運作方式：

「我打算在洛杉磯開設第四家麵包店，我需要早晨活動頻繁的社區。找出『早上』人潮流量分數最高的郵遞區號。」
「請在該郵遞區號中搜尋『麵包店』，看看是否已飽和。如果太多，請檢查『特選咖啡』店，這樣我才能在附近找個位置，吸引人潮。」
「好的，我想將這個品牌定位為頂級品牌。在洛杉磯都會區，『酸麵包』的最高收費是多少？
「現在我想要 2025 年 12 月的收益預測。查看我的銷售記錄，並從銷售業績最佳的商店取得「酸種麵包」的資料。執行 2025 年 12 月的預測，估算我將售出的數量。然後，使用我們找到的略低於優質價格的價格 (假設為 $18)，計算預估總收益」
「這樣就夠付房租了。最後，請確認物流資訊。找出離建議區域最近的「Restaurant Depot」，並確保每日補貨的車程時間在 30 分鐘內。」

8. 清除

如要避免系統持續向您的 Google Cloud 帳戶收費，請刪除本程式碼研究室建立的資源。

執行清除指令碼。這個指令碼會刪除設定期間建立的 BigQuery 資料集、Cloud Storage bucket 和 API 金鑰。

chmod +x ../cleanup/cleanup_env.sh
./../cleanup/cleanup_env.sh

9. 恭喜

任務完成！您已使用 Agent Development Kit (ADK) 成功建構 Location Intelligence Agent。

透過連結 BigQuery 中的「企業」資料和 Google 地圖的實際位置資訊，您已建立強大的工具，能夠進行複雜的業務推理，一切都由模型脈絡通訊協定 (MCP) 和 Gemini 提供支援。

您已完成以下事項：

基礎架構即程式碼：您使用 Google Cloud CLI 工具佈建資料堆疊。
MCP 整合：您將 AI 代理程式連線至兩個不同的遠端 MCP 伺服器 (BigQuery 和 Google 地圖)，不必編寫複雜的 API 包裝函式。
統一推理：您建構的單一代理程式能夠策略性地結合兩個不同領域的洞察資料，解決業務問題。