使用 BigQuery MCP 构建 Google 趋势分析师智能体

1. 概览

在此 Codelab 中，您将使用 Google ADK 构建一个 Google 趋势分析师智能体。此代理利用 BigQuery MCP 服务器动态发现并执行查询 Google 趋势公共数据集 (bigquery-public-data.google_trends) 的工具。

学习内容

• 如何设置项目以进行 ADK 开发。
• 如何为 BigQuery 启用和使用受管理的 MCP 服务器。
• 如何构建使用 MCP 工具的智能体。
• 如何在本地运行代理以进行测试。
• 如何将代理部署到 Google Cloud Run。

所需条件

• 启用了结算功能的 Google Cloud 项目
• 网络浏览器，例如 Chrome
• Python 3.11+

此 Codelab 适合对 Python 和 Google Cloud 有一定了解的中级开发者。

完成本 Codelab 大约需要 15-20 分钟。

在此 Codelab 中创建的资源费用应低于 5 美元。

2. 设置您的环境

创建 Google Cloud 项目

1. 在 Google Cloud 控制台的项目选择器页面上，选择或创建一个 Google Cloud 项目。
2. 确保您的 Cloud 项目已启用结算功能。了解如何检查项目是否已启用结算功能。

我们建议您在此 Codelab 中使用 Google Cloud Shell。它提供了一个已安装 Python 和 Google Cloud CLI 的终端环境。

如需激活 Cloud Shell，请点击 Google Cloud 控制台顶部的激活 Cloud Shell 按钮。

设置环境变量

设置以下环境变量。

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 账号，设置有效项目，并配置应用默认凭证。

如果您使用的是 Cloud Shell，则可以跳过此步骤。

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 Web 服务器。您可以使用本地 Web 界面（通常位于 http://localhost:8000）与代理互动。

注意：您也可以使用更简单的 adk run google_trends 命令来测试智能体。

不妨尝试向代理提出以下提示：

• 显示美国的热门趋势
• 本月法国的热门上升趋势有哪些？
• 上周加利福尼亚州的热门趋势有哪些？
• 您有权访问哪些 BigQuery 表？
• 请告诉我您所了解的有关 top_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}[e-mail]" \
  --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}[e-mail]" \
  --role="roles/mcp.toolUser"

gcloud projects add-iam-policy-binding ${GOOGLE_CLOUD_PROJECT} \
  --member="serviceAccount:${PROJECT_NUMBER}[e-mail]" \
  --role="roles/bigquery.jobUser"

gcloud projects add-iam-policy-binding ${GOOGLE_CLOUD_PROJECT} \
  --member="serviceAccount:${PROJECT_NUMBER}[e-mail]" \
  --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}"

快速验证

部署完成后，控制台会输出服务网址。在浏览器中打开此网址；您会看到与本地相同的互动式界面，但现在该界面在云端运行！

您还可以监控日志，确保一切顺利运行：

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

6. 清理

为避免持续产生费用，请删除在本 Codelab 中创建的资源。

删除 Cloud Run 服务：

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

如果您专门为此 Codelab 创建了一个项目，可以删除整个项目：

gcloud projects delete ${GOOGLE_CLOUD_PROJECT}

您还可以删除与此 Codelab 相关的所有文件：

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

7. 恭喜

恭喜！您已成功构建并部署了 Google 趋势分析师代理。

您学到的内容

• 如何使用 MCP 动态扩展智能体功能
• 如何使用 Google ADK 构建和部署 LLM 智能体
• 如何在 Cloud Run 上部署和扩缩智能体

后续步骤

• 尝试修改代理以查询不同的 BigQuery 数据集
• 添加更多 MCP 工具以扩展智能体的功能

参考文档

• ADK 文档
• MCP 工具指南
• BigQuery MCP
• Cloud Run 文档