使用 BigQuery MCP 建構 Google 搜尋趨勢分析師代理程式

1. 總覽

在本程式碼實驗室中，您將使用 Google ADK 建構 Google 搜尋趨勢分析師代理。這個代理會運用 BigQuery MCP 伺服器，動態探索及執行查詢 Google 搜尋趨勢公開資料集 (bigquery-public-data.google_trends) 的工具。

課程內容

  • 如何設定 ADK 開發專案。
  • 如何啟用及使用 BigQuery 的代管 MCP 伺服器。
  • 如何建構使用 MCP 工具的代理。
  • 如何在本機執行代理程式以進行測試。
  • 如何將代理程式部署至 Google Cloud Run。

軟硬體需求

  • 已啟用計費功能的 Google Cloud 雲端專案
  • 網路瀏覽器，例如 Chrome
  • Python 3.11 以上版本

本程式碼研究室適合對 Python 和 Google Cloud 有基本認識的中階開發人員。

完成本程式碼研究室大約需要 15 到 20 分鐘。

本程式碼研究室建立的資源費用應低於 $5 美元。

2. 設定環境

建立 Google Cloud 專案

  1. 在 Google Cloud 控制台的專案選取器頁面中，選取或建立 Google Cloud 專案。
  2. 確認 Cloud 專案已啟用計費功能。瞭解如何檢查專案是否已啟用計費功能。

設定環境變數

設定下列環境變數。

export GOOGLE_CLOUD_PROJECT=<INSERT_YOUR_GCP_PROJECT_HERE>
export GOOGLE_GENAI_USE_VERTEXAI=1

注意：設定 GOOGLE_GENAI_USE_VERTEXAI=1 會指示 ADK 使用 Vertex AI，並透過 Cloud IAM 進行驗證，而非 GEMINI_API_KEY。

驗證及設定 gcloud

登入 Google 帳戶、設定有效專案，並設定應用程式預設憑證。

gcloud auth login
gcloud auth application-default login

注意：gcloud auth login 會驗證 gcloud CLI 指令，而 gcloud auth application-default login 則會驗證本機應用程式程式碼。

設定 Google Cloud 專案：

gcloud config set project ${GOOGLE_CLOUD_PROJECT}

啟用必要的 API

啟用 Cloud Run、Artifact Registry、BigQuery 和 Vertex AI 的必要 Google Cloud API。

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

啟用 BigQuery 的 MCP

您必須為專案明確啟用代管 MCP 伺服器。

gcloud beta services mcp enable bigquery.googleapis.com

建立專案資料夾

首先，請為代理建立根資料夾，以及代理實作的內部資料夾。

mkdir google-trends-agent
cd google-trends-agent
mkdir google_trends

3. 建立代理程式碼

建立一個名為 google_trends/__init__.py 的空檔案：

touch google_trends/__init__.py

接著，建立名為 google_trends/agent.py 的檔案，並貼上下列程式碼：

import os
import textwrap
import warnings
from datetime import date

import google.auth
from google.adk.agents import LlmAgent
from google.adk.apps import App
from google.adk.tools.mcp_tool import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams
from google.auth.transport.requests import Request

# Suppress experimental ADK credential warnings
warnings.filterwarnings("ignore")

def get_agent_instruction(project_id: str) -> str:
    """Generates a clear and formatted prompt for the data analyst."""
    instruction = f"""
    # ROLE
    You are a Google Search Trends Analyst. Your mission is to provide clear answers using SQL data.

    # DATA CONSTRAINTS
    - BigQuery tool `execute_sql` requires explicit billing project mapping. Use: '{project_id}'.
    - Target dataset strictly: `bigquery-public-data.google_trends`

    # SCHEMA DISCOVERY (CRITICAL)
    1. DO NOT call `get_table_info` or `list_table_ids` (Triggers Permission Errors).
    2. Run `SELECT * FROM table LIMIT 0` via `execute_sql` for field definition mapping.

    # OUTPUT PRESENTATION
    - Render purely as a cleanly aligned Markdown table.
    - Use clear and descriptive headers for each column.
    - Remove conversational preambles. Output only the results.
    """
    return textwrap.dedent(instruction).strip()

def get_auth_headers() -> dict[str, str]:
    """Fetch auth headers for the project using Google Cloud Platform scopes."""
    credentials, _ = google.auth.default(
        scopes=["https://www.googleapis.com/auth/cloud-platform"]
    )
    request = Request()
    credentials.refresh(request)

    return {"Authorization": f"Bearer {credentials.token}"}

def get_todays_date() -> str:
    """Returns today's date in YYYY-MM-DD format."""
    return date.today().isoformat()

# --- Application Initialization ---
project_id = os.environ.get("GOOGLE_CLOUD_PROJECT")
if not project_id:
    raise ValueError("GOOGLE_CLOUD_PROJECT environment variable is not set")

mcp_headers = {
    "Content-Type": "application/json",
    "Accept": "application/json, text/event-stream",
} | get_auth_headers()

# Configure BigQuery Tools via MCP
bq_tools = McpToolset(
    connection_params=StreamableHTTPConnectionParams(
        url="https://bigquery.googleapis.com/mcp",
        headers=mcp_headers,
    )
)

# Initialize the LLM Agent
root_agent = LlmAgent(
    name="google_trends",
    model="gemini-3-flash-preview",
    tools=[get_todays_date, bq_tools],
    instruction=get_agent_instruction(project_id),
)

# Create the ADK App
app = App(name=root_agent.name, root_agent=root_agent)

4. 執行代理程式

在這個步驟中，您將設定本機 Python 虛擬環境、安裝依附元件，並執行代理程式，在電腦 (或 Google Cloud Shell) 上驗證其行為。

  • 前往應用程式根目錄 (google-trends-agent)。
  • 建立虛擬環境：
python -m venv mcp_demo_env
source mcp_demo_env/bin/activate
  • 安裝必要的 Python 套件：
pip install google-auth google-adk

我們會使用 ADK Web 測試新代理。

如要在本機開發及測試，請執行下列指令：

adk web

如要在 Google Cloud Shell 中進行開發和測試，請執行下列指令：

adk web --allow_origins="*"

這項操作會啟動 ADK 網路伺服器。你可以使用本機網頁介面 (通常位於 http://localhost:8000) 與代理程式互動。

注意：您也可以使用較簡單的 adk run google_trends 指令測試代理程式。

5. 部署至 Cloud Run

請按照下列步驟，將代理程式安全地部署至 Google Cloud Run。

授予權限

Cloud Run 需要存取 Vertex AI 和使用 BigQuery MCP 工具的權限。

# Get your project number automatically
PROJECT_NUMBER=$(gcloud projects describe $GOOGLE_CLOUD_PROJECT --format='value(projectNumber)')

# Vertex AI Access: To talk to the Gemini model
gcloud projects add-iam-policy-binding ${GOOGLE_CLOUD_PROJECT} \
  --member="serviceAccount:${PROJECT_NUMBER}-compute@developer.gserviceaccount.com" \
  --role="roles/aiplatform.user"

# MCP & BigQuery: To execute tools and run SQL jobs
gcloud projects add-iam-policy-binding ${GOOGLE_CLOUD_PROJECT} \
  --member="serviceAccount:${PROJECT_NUMBER}-compute@developer.gserviceaccount.com" \
  --role="roles/mcp.toolUser"

gcloud projects add-iam-policy-binding ${GOOGLE_CLOUD_PROJECT} \
  --member="serviceAccount:${PROJECT_NUMBER}-compute@developer.gserviceaccount.com" \
  --role="roles/bigquery.jobUser"

gcloud projects add-iam-policy-binding ${GOOGLE_CLOUD_PROJECT} \
  --member="serviceAccount:${PROJECT_NUMBER}-compute@developer.gserviceaccount.com" \
  --role="roles/bigquery.dataViewer"

建立 Dockerfile

在專案根目錄 (google-trends-agent) 中，建立名為 Dockerfile 的檔案，並貼上下列內容：

FROM python:3.11-slim
WORKDIR /app

# Create a non-root user
RUN adduser --disabled-password --gecos "" myuser
USER myuser
ENV PATH="/home/myuser/.local/bin:$PATH"

# Copy the agent folder into the container
COPY --chown=myuser:myuser google_trends/ /app/agents/google_trends/

# Install the python packages
RUN pip install google-auth google-adk

# Set environment variables
ENV GOOGLE_GENAI_USE_VERTEXAI=1

# Expose port
EXPOSE 8080

# Run ADK web server
CMD ["adk", "web", "--port=8080", "--host=0.0.0.0", "/app/agents"]

部署代理程式

從根目錄執行下列指令。這會將代理程式容器化並部署至 Cloud Run。

gcloud run deploy google-trends-agent \
  --source . \
  --region us-west1 \
  --allow-unauthenticated \
  --set-env-vars="GOOGLE_CLOUD_PROJECT=${GOOGLE_CLOUD_PROJECT}"

快速驗證

部署完成後，主控台會輸出「服務網址」。在瀏覽器中開啟這個網址，您會看到與在本機上相同的互動式 UI，但現在是在雲端執行！

您也可以監控記錄，確保一切運作順暢：

gcloud logging read "resource.type=cloud_run_revision AND resource.labels.service_name=google-trends-agent" --limit 10

6. 清除

如要避免持續產生費用，請刪除在本程式碼研究室中建立的資源。

刪除 Cloud Run 服務：

gcloud run services delete google-trends-agent --region us-west1

如果您是特地為了這個程式碼研究室建立專案，可以刪除整個專案：

gcloud projects delete ${GOOGLE_CLOUD_PROJECT}

您也可以刪除與這個程式碼研究室相關的所有檔案：

deactivate
cd ..
rm -rf google-trends-agent

7. 恭喜

恭喜！您已成功建構及部署 Google 搜尋趨勢分析師代理程式。

目前所學內容

  • 如何使用 MCP 動態擴充代理能力
  • 如何使用 Google ADK 建構及提供 LLM 代理
  • 如何在 Cloud Run 上部署及擴充代理程式

後續步驟

  • 嘗試修改代理程式，查詢不同的 BigQuery 資料集
  • 新增更多 MCP 工具，擴充代理的功能

參考文件