Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

在 Cloud Run 中使用 Gemini 和 BigQuery MCP 服务器构建和部署 AI 智能体

1. 简介

学习内容

如何使用 Agent Platform 中的 Gemini 通过智能体开发套件 (ADK) 创建 AI 智能体。
如何使用 BigQuery MCP 服务器向 AI 智能体授予对 BigQuery 中结构化数据的访问权限。

Cloud Run 是一项全托管式无服务器计算平台，可让您运行容器化应用和服务，而无需管理任何底层基础设施。

智能体开发套件 (ADK) 是一个开源智能体开发框架，可让您以企业级规模构建、调试和部署可靠的 AI 智能体。

BigQuery 是一种全托管式无服务器企业数据仓库，可用于存储、查询和分析海量数据集。

Model Context Protocol (MCP) 可规范大语言模型 (LLM) 和 AI 应用或代理连接到外部数据源的方式。借助 MCP 服务器，您可以使用其工具、资源和提示来执行操作，并从其后端服务获取更新后的数据。借助 BigQuery MCP 服务器，您的 AI 智能体可以直接且安全地分析 BigQuery 中的数据。这一全托管式 MCP 服务器不会带来额外的管理开销，让您可以专注于智能体的开发。

2. 设置和要求

首先设置默认项目和 Cloud Run 区域：

# set the project
gcloud config set project YOUR_PROJECT_ID

将 YOUR_PROJECT_ID 替换为您的 Google Cloud 项目 ID。

# set Cloud Run region
gcloud config set run/region CLOUD-RUN-REGION

将 CLOUD-RUN-REGION 替换为 Cloud Run 支持的区域之一。

以下是本 Codelab 中将使用的环境变量。您可以将这些变量保存在环境文件中，然后“source”该文件。请务必正确设置项目 ID 的值，还可以选择设置区域。

# Cloud Project Id and Cloud Run region
export GOOGLE_CLOUD_PROJECT="${GOOGLE_CLOUD_PROJECT:-$(gcloud config get-value project -q)}"
export GOOGLE_CLOUD_REGION="${GOOGLE_CLOUD_REGION:-$(CR_REGION=$(gcloud config get-value run/region -q 2>/dev/null); echo "${CR_REGION:-us-central1}")}"
# Gemini API in Agent Platform
export GOOGLE_GENAI_USE_ENTERPRISE="True" # Use Agent Platform
export GOOGLE_CLOUD_LOCATION="global" # Use global Gemini API endpoint

启用本 Codelab 所需的 API。API 更改可能需要 2-3 分钟才能生效。

gcloud services enable --project "${GOOGLE_CLOUD_PROJECT}" \
    run.googleapis.com \
    cloudbuild.googleapis.com \
    artifactregistry.googleapis.com \
    bigquery.googleapis.com \
    aiplatform.googleapis.com

3. 使用智能体开发套件创建数据智能体

编写智能体的代码

在 Cloud Shell 终端或本地终端中，为您的智能体应用创建一个根目录：

mkdir data_agent

打开 Cloud Shell Editor 或其他文本编辑器，然后在 data_agent 目录中创建 agent.py：

data_agent/
    agent.py

agent.py

import os

from google.adk.agents import LlmAgent
from google.adk.tools.mcp_tool.mcp_toolset import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams

import google.auth
from google.auth.transport.requests import Request

# Fetch Application Default Credentials (ADC)
# to use as agent's own identity for accessing BigQuery MCP Server
_application_default_credentials, project_id = google.auth.default()
_request = Request()
_application_default_credentials.refresh(_request)

# Retrieve Google Cloud project to use.
project_id = os.getenv("GOOGLE_CLOUD_PROJECT", project_id)
if not project_id:
    raise ValueError("GOOGLE_CLOUD_PROJECT environment variable is not set.")

# Builds authentication headers for MCP Server requests,
# and refreshes credentials if needed.
def _adc_auth_header_provider(context = None) -> dict[str, str]:
    if not _application_default_credentials.valid:
        _application_default_credentials.refresh(_request)

    return {
        "Authorization": f"Bearer {_application_default_credentials.token}",
        "x-goog-user-project": project_id
    }

# Initialize the MCP Toolset with the connection parameters
bigquery_toolset = McpToolset(
    connection_params=StreamableHTTPConnectionParams(
        url="https://bigquery.googleapis.com/mcp",
        tool_filter=[
            'get_dataset_info',
            'list_table_ids',
            'get_table_info',
            # Using readonly is a security measure to prevent accidental data modification.
            'execute_sql_readonly',
        ]
    ),
    header_provider=_adc_auth_header_provider # Auth header provider function
)

# Configure the agent

system_instruction = f"""
You are a helpful assistant that can answer questions about data in BigQuery.
To answer the user's question, use data you have access to by using tools `list_table_ids` and `get_table_info`.
Your data is in `bigquery-public-data.new_york_citibike` dataset (Citi Bike trips and stations in the NYC area.)

Plan of action:
0. ALWAYS start by analyzing dataset.
1. Analyze your data, investigate schema and dimensions by querying distrinct values of columns using `execute_sql_readonly`.
   Output information about tables, columns, their data types and sets of values (for dimensions).
   Note which columns can be joined or used in aggregations/filters, and what type conversion may be needed for joining or aggregating.
   DO NOT MAKE ASSUMPTIONS ABOUT DATA (structure, type, values, relationships) BASED ON YOUR PRIOR KNOWLEDGE. ALWAYS VERIFY YOUR ASSUMPTIONS.
2. Understand and interpret the user's question.
3. Formulate a plan to answer the user's question.
4. Write a SQL query to retrieve relevant data in necessary form.
   This is where you must pay extra attention to column types and dimensions' sets of values.
5. Retrieve data by generating BigQuery SQL and using `execute_sql_readonly`.
   Always use Dry Run to verify SQL correctness.
   Use `{project_id}` to run BigQuery queries (`project_id` parameter of `execute_sql_readonly`).

Do not use LaTeX in your responses. When giving a final answer, use Markdown.
"""

root_agent = LlmAgent(
    model="gemini-3.6-flash",
    name="data_agent",
    instruction=system_instruction,
    description="A helpful assistant that can answer questions using NYC Citibike data.",
    tools=[bigquery_toolset]
)

ADK 在部署时还需要 __init__.py 和 requirements.txt：

__init__.py 必须具有代理的导入。
requirements.txt 列出 Python 依赖项：google-adk 适用于智能体开发套件，mcp 适用于 Model Context Protocol 客户端。

这些命令可帮助您创建 __init__.py 和 requirements.txt：

echo "from . import agent" > data_agent/__init__.py
echo -e "google-adk==2.4.*\nmcp==1.29.*" > data_agent/requirements.txt

最终的文件夹结构应如下所示：

data_agent/
    __init__.py
    agent.py
    requirements.txt

在本地试用智能体

智能体开发套件随附 adk CLI 工具，这是一个用于测试智能体的交互式终端界面。这对于快速测试、脚本化互动和 CI/CD 流水线非常有用。它提供的一项功能是 adk web - ADK 网页界面 - 一种以交互方式开发和调试智能体的简单方法。ADK Web 不适用于生产部署，但可让您非常轻松地试用智能体。

此命令会启动 adk web，后者会在端口 8080 上启动本地网络服务器。

uv tool run --with "mcp==1.29.*" --from "google-adk[mcp]==2.4.*" adk web --allow_origins="*" --port 8080 .

服务启动后，打开本地 ADK 网页：http://localhost:8080/。

如果您使用的是 Google Cloud Shell，请点击“网页预览” 按钮，然后选择“在端口 8080 上预览”菜单项。

在 ADK 网页界面中，向智能体询问其有权访问的数据：

What data do you have?

智能体将使用 BigQuery MCP 工具探索 citibike 数据集。它将为您简要介绍 Citibike 数据集中的可用表格和字段。

4. 将代理部署到 Cloud Run

此命令将使用 ADK CLI 将智能体部署到 Cloud Run。

uv tool run --from google-adk==2.4.0 \
  adk deploy cloud_run \
      --with_ui \
      --project $GOOGLE_CLOUD_PROJECT \
      --region $GOOGLE_CLOUD_REGION \
      --service_name bq-data-agent \
      --app_name data_agent \
      data_agent \
      -- \
      --allow-unauthenticated \
      --max-instances 1 \
      --set-env-vars GOOGLE_GENAI_USE_ENTERPRISE=True,GOOGLE_CLOUD_PROJECT="${GOOGLE_CLOUD_PROJECT},GOOGLE_CLOUD_LOCATION=${GOOGLE_CLOUD_LOCATION}"

试用代理

我们为代理部署使用了 --with_ui 选项。它使用 ADK 网页界面部署了智能体。

在网络浏览器中打开代理网址。adk deploy 命令返回了该网址，您还可以通过运行 gcloud run services 命令来检索该网址：

gcloud run services describe bq-data-agent \
  --project $GOOGLE_CLOUD_PROJECT \
  --region $GOOGLE_CLOUD_REGION \
  --format 'value(status.url)'

让智能体根据可用的 Citibike 数据进行推理：

We have budget for 3 coffee trucks.
We want to find the best city bike stations to place our coffee trucks.

智能体应使用 BigQuery MCP 服务器探索 Citibike 数据集，运行一些 SQL 查询，并返回 3 个 Citibike 站点的列表。

5. 恭喜！

恭喜您完成此 Codelab！

建议您查看 Cloud Run 文档。

所学内容

如何使用智能体开发套件和 Gemini 创建 AI 智能体
如何将代理连接到 BigQuery MCP 服务器。
如何将代理部署到 Cloud Run。

6. 清理

为避免因本教程中使用的资源导致您的 Google Cloud 账号产生费用，您可以删除项目或删除各个资源。

方法 1：删除服务

删除 Cloud Run 服务

gcloud run services delete bq-data-agent \
      --project "${GOOGLE_CLOUD_PROJECT}" \
      --region "${GOOGLE_CLOUD_REGION}" \
      --quiet

方法 2：删除项目

如需删除整个项目，请前往管理资源，选择您在第 2 步中创建的项目，然后选择“删除”。如果您删除项目，则需要在 Cloud SDK 中更改项目。您可以运行 gcloud projects list 查看所有可用项目的列表。如果您想坚持使用命令行，也可以使用以下命令：

gcloud projects delete ${GOOGLE_CLOUD_PROJECT}