使用 MCP 和 Cloud Run 部署企业治理感知型智能体

1. 简介

本 Codelab 是一个分为两部分的系列教程，旨在探讨如何构建具有治理意识的 GenAI 代理。

（您可以阅读本系列的第一部分，其中介绍了如何通过将 Dataplex Aspect 应用于 BigQuery 表并使用 Gemini CLI 在本地测试规则来建立数据基础。👉 阅读第 1 部分）

不过，在本地 CLI 中进行测试只是开始。若要将此功能推广到整个公司，您需要集中式安全措施、标准化的 AI 工具连接，以及用于编排智能体逻辑并提供熟悉的聊天界面的适当应用框架。

在第二部分中，您将解决这些挑战并扩展到生产环境。您将把治理规则部署到托管在 Cloud Run 上的中央 MCP 服务器中。然后，您将使用 Google 的智能体开发套件 (ADK) 来构建实际的智能体应用，并将其连接到您的 MCP 工具，从而获得专业的 Web 界面。

前提条件

启用了结算功能的 Google Cloud 项目。
对 Cloud Run、IAM 服务账号和 Python 有基本的了解。
第 1 部分中创建的 BigQuery 数据集和 Dataplex Aspect。（如果您已删除这些文件，请不要担心；我们会在下文中提供一个快速脚本来重新创建它们！）

学习内容

如何使用 Model Context Protocol (MCP) 来规范 AI 代理与 Google Cloud 数据的互动方式。
如何将安全的 MCP 服务器部署到 Cloud Run。
如何使用智能体开发套件 (ADK) 构建 AI 智能体并将其连接到 MCP 后端。
如何运行 ADK 的内置开发者界面来与受管理的代理互动。

所需条件

Google Cloud Shell 访问权限

主要概念

Model Context Protocol (MCP)：可以将 MCP 视为 AI 代理的“通用 USB-C 线缆”。MCP 提供了一种标准方法，让 AI 能够安全地连接到企业数据工具（如 Dataplex 和 BigQuery），而无需为每个 AI 模型编写自定义 API 集成代码。
智能体开发套件 (ADK)：Google 推出的灵活的开源框架，旨在简化 AI 智能体的端到端开发。它将软件工程原理应用于智能体创建，让您能够编排复杂的工具、管理状态，并轻松启动内置的开发者界面以进行测试和部署。

2. 设置和要求

启动 Cloud Shell

虽然可以通过笔记本电脑对 Google Cloud 进行远程操作，但在此 Codelab 中，您将使用 Google Cloud Shell，这是一个在云端运行的命令行环境。

在 Google Cloud 控制台中，点击右上角工具栏中的 Cloud Shell 图标：

激活 Cloud Shell

预配和连接到环境应该只需要片刻时间。完成后，您应该会看到如下内容：

Google Cloud Shell 终端的屏幕截图，显示环境已连接

这个虚拟机已加载了您需要的所有开发工具。它提供了一个持久的 5 GB 主目录，并且在 Google Cloud 中运行，大大增强了网络性能和身份验证功能。您在此 Codelab 中的所有工作都可以在浏览器中完成。您无需安装任何程序。

初始化环境

打开 Cloud Shell 并设置项目变量，以确保所有命令都指向正确的基础设施。

export PROJECT_ID=$(gcloud config get-value project)
gcloud config set project $PROJECT_ID
export REGION="us-central1"

检查点：继续还是重建？

由于这是第 2 部分，因此您的代理需要第 1 部分中的受监管数据才能正常运行。请选择您的学习方向：

路径 A：我刚刚完成第 1 部分，我的资源仍在运行。

太棒了！导航到工作目录，然后即可继续操作。

cd ~/devrel-demos/data-analytics/governance-context

路径 B：我跳过了第 1 部分，或者我已删除资源（已清理）。

没问题！我们在下方提供了一个“快速通道”命令块。这样一来，系统会自动重建 BigQuery 数据湖，并完全按照我们在第 1 部分中的方式应用 Dataplex 治理元数据。

# 1. Clone the repo and navigate to the working directory
git clone --depth 1 --filter=blob:none --sparse https://github.com/GoogleCloudPlatform/devrel-demos.git
cd devrel-demos
git sparse-checkout set data-analytics/governance-context
cd data-analytics/governance-context

# 2. Rebuild the messy data lake with Terraform
cd terraform
terraform init
terraform apply -var="project_id=${PROJECT_ID}" -var="region=${REGION}" -auto-approve

# 3. Generate and apply Dataplex Aspects (Governance rules)
cd ..
chmod +x ./generate_payloads.sh ./apply_governance.sh
./generate_payloads.sh
./apply_governance.sh

3. 使用 MCP 进行扩缩：构建数据控制平面

到目前为止，您已使用 Gemini CLI 成功测试了治理逻辑。这非常适合快速原型设计，但它会在本地使用您的个人用户凭据运行。

在实际的企业环境中，您需要一个集中式数据控制平面。为此，我们将使用 Google 的官方开源项目 GenAI Toolbox for Databases。此工具箱提供了一个预构建的 MCP 服务器，专门用于将 AI 智能体安全地连接到 Google Cloud 数据库和元数据服务（例如 Dataplex）。

通过将此工具箱作为 MCP 服务器部署到 Cloud Run，我们实现了以下目标：

集中式身份：代理以受限的服务账号身份运行，而不是以您的个人用户账号身份运行。
标准化：任何客户端（ADK、Gemini、自定义应用）都可以使用标准 MCP 协议“插入”此服务器。
受控范围（最小权限）：我们不会向 LLM 提供对 BigQuery 的开放式访问权限。我们强制它先通过 Dataplex 元数据目录进行导航。

配置工具定义 (`tools.yaml`)

生成式 AI 工具箱需要声明性配置文件 tools.yaml。此文件定义了 sources（连接位置）和 tools（AI 可以执行的操作）。

前往服务器目录，并将项目 ID 注入到配置文件中：

cd ~/devrel-demos/data-analytics/governance-context/mcp_server
envsubst < tools.yaml > tools.tmp && mv tools.tmp tools.yaml
cat tools.yaml

它应该与以下代码段完全相同。验证项目字段现在是否与您的实际 Google Cloud 项目 ID 相匹配。

sources:
  dataplex:
    kind: dataplex
    project: YOUR-PROJECT-ID

tools:
  search_entries:
    kind: dataplex-search-entries
    source: dataplex
    description: Search for entries in Dataplex Catalog.

  lookup_entry:
    kind: dataplex-lookup-entry
    source: dataplex
    description: Retrieve a specific entry from Dataplex Catalog.

  search_aspect_types:
    kind: dataplex-search-aspect-types
    source: dataplex
    description: Find aspect types relevant to a query.

toolsets:
  dataplex-toolset:
    - search_entries
    - lookup_entry
    - search_aspect_types

🔍 深入探究：治理推理循环

仔细查看 YAML 中的工具部分。我们明确公开了三个特定的 Dataplex 工具。这并非随机，而是形成了一个严格的推理循环，可防止出现幻觉：

dataplex-search-aspect-types（了解规则）：当用户询问“董事会批准的数据”时，LLM 不知道这是什么意思。它使用此工具搜索您的 Dataplex 切面类型。它发现“Board Approved”对应于一个名为 official-data-product-spec 的方面，其层级为 GOLD_CRITICAL。
dataplex-search-entries（查找候选条目）：现在，LLM 知道要查找的内容，因此会使用此工具搜索 Dataplex Catalog（例如，搜索包含关键字“收入”的表）。它会获取匹配资源的列表。
dataplex-lookup-entry（验证事实）：在编写任何 SQL 之前，LLM 会使用此工具检查特定表的精确元数据。如果表格未附加 GOLD_CRITICAL 方面，LLM 会拒绝该表格并继续查找。

通过定义这三个工具，我们可以强制 AI 采用“只读”和“治理优先”模式。

保护配置 (Secret Manager)

在企业架构中，您绝不应将配置文件直接烘焙到容器映像中。我们将 tools.yaml 安全地存储在 Google Cloud Secret Manager 中。

gcloud services enable secretmanager.googleapis.com
gcloud secrets create dataplex-tools-config --data-file=tools.yaml

实施最小权限原则 (IAM)

接下来，我们将为 GenAI Toolbox MCP 服务器创建一个专用服务账号。此身份将仅拥有读取 Dataplex 目录和访问 BigQuery 数据所需的精确权限。

export MCP_SA=mcp-sa
gcloud iam service-accounts create ${MCP_SA} \
    --display-name="Service Account for Dataplex MCP"
export MCP_SERVICE_ACCOUNT="${MCP_SA}@${PROJECT_ID}.iam.gserviceaccount.com"

# Allow the server to read its own config from Secret Manager
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$MCP_SERVICE_ACCOUNT" \
  --role="roles/secretmanager.secretAccessor"

# Allow the server to read Dataplex Metadata and BigQuery Data
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$MCP_SERVICE_ACCOUNT" \
  --role="roles/dataplex.catalogViewer"
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$MCP_SERVICE_ACCOUNT" \
  --role="roles/bigquery.dataViewer"

将 MCP 服务器部署到 Cloud Run

现在，我们部署生成式 AI 工具箱。我们使用 Google 的预构建容器映像 (database-toolbox/toolbox)，并在运行时从 Secret Manager (--set-secrets) 装载我们的配置。

export IMAGE=us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest

gcloud run deploy governance-mcp \
    --image=$IMAGE \
    --service-account $MCP_SERVICE_ACCOUNT \
    --region=$REGION \
    --no-allow-unauthenticated \
    --set-secrets="/app/tools.yaml=dataplex-tools-config:latest" \
    --args="--tools-file=/app/tools.yaml","--address=0.0.0.0","--port=8080"

您现在已建立受管控的 API！您的生成式 AI 前端不会直接访问数据库，而是会连接到此 Cloud Run 网址。代理只能看到此工具箱允许其看到的内容。

4. 使用 ADK 构建智能体后端

您已在 Cloud Run 上建立一个安全且受监管的数据控制平面 (MCP)。现在，您的 AI 代理需要一个框架来编排其逻辑，例如处理用户输入、决定何时调用 MCP 服务器以及设置输出格式。

我们不会从头开始编写所有这些样板代码，而是使用 Google 的智能体开发套件 (ADK)。ADK 是一个代码优先的框架，可自动将您的代理逻辑封装到 FastAPI 后端中。此外，它还附带内置的开发者界面，让您无需先构建自定义前端，即可直观地了解智能体的推理过程和工具调用。

检查代理逻辑 (agent.py)

在配置基础架构之前，我们先来看看此应用的核心。

导航到该目录并输出 agent.py 的内容。此文件是 ADK 部署的“大脑”。

cd ~/devrel-demos/data-analytics/governance-context/mcp_server
cat agent.py

查看代码结构。它以最少的样板代码执行三项关键功能：

MCPToolset 集成：ADK 使用 MCPToolset(server_url=mcp_url)，而不是编写自定义 HTTP 客户端来与 Dataplex 工具互动。此功能会从已部署的 MCP 服务器动态提取 tools.yaml 定义，并将其转换为 LLM 的原生函数调用。
系统指令：instructions 参数包含严格的治理规则（与我们在 CLI GEMINI.md 中使用的逻辑相同）。它明确指示模型执行从阶段 1（元数据查找）到阶段 2（数据查询）的推理循环。
智能体编排：Agent(...) 类将 Gemini 模型、系统提示和 MCP 工具绑定在一起。部署后，ADK 会自动将此对象转换为可扩缩的 FastAPI 端点。

职责分离：配置前端身份

为了安全地运行此代码，我们必须告知代理您的 MCP 服务器位于何处。我们将动态构建网址，并将其保存到 ADK 在运行时会读取的 .env 文件中。

我们还将为此面向用户的应用创建一个单独的身份 (dataplex-agent-sa)。这种职责分离可确保前端代理的权限与后端治理服务器的权限不同。

运行以下命令以配置环境和身份：

export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")
export MCP_SERVER_URL=https://governance-mcp-${PROJECT_NUMBER}.${REGION}.run.app/mcp

export AGENT_SA=dataplex-agent-sa
export AGENT_SERVICE_ACCOUNT="${AGENT_SA}@${PROJECT_ID}.iam.gserviceaccount.com"

gcloud iam service-accounts create ${AGENT_SA} \
    --display-name="Service Account for Dataplex Agent "

配置运行时变量

ADK 框架依赖于环境变量来了解其上下文。我们需要明确设置项目 ID、区域并启用 Vertex AI 使用。我们将这些内容附加到同一 .env 文件中。

echo MCP_SERVER_URL=$MCP_SERVER_URL > .env
echo GOOGLE_GENAI_USE_VERTEXAI=1 >> .env
echo GOOGLE_CLOUD_PROJECT=$PROJECT_ID >> .env
echo GOOGLE_CLOUD_LOCATION=$REGION >> .env

授予权限

即使代理将治理检查委托给 MCP 服务器，它仍然需要基本权限才能运行。我们授予的角色数量正好为两个：

Vertex AI 用户：用于调用 Gemini 模型以生成自然语言回答。
Cloud Run Invoker：用于安全地调用 MCP 服务器 API。它不会获得直接的 BigQuery 或 Dataplex 访问权限！

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$AGENT_SERVICE_ACCOUNT" \
  --role="roles/aiplatform.user"

gcloud run services add-iam-policy-binding governance-mcp \
  --region=$REGION \
  --member="serviceAccount:$AGENT_SERVICE_ACCOUNT" \
  --role="roles/run.invoker"

部署到 Cloud Run

最后，我们将整个堆栈部署到 Cloud Run。

我们使用 uvx 来运行 ADK 工具，而无需手动安装依赖项。以下命令会打包您的 agent.py 逻辑、构建容器映像、注入您的服务账号，并启动 FastAPI 服务器。通过添加 --with_ui 标志，它还会捆绑 ADK Web Playground 以进行调试。

此命令会构建并部署容器。此过程可能需要 1-3 分钟才能完成。

uvx --from google-adk \
adk deploy cloud_run \
  --project=$PROJECT_ID \
  --region=$REGION \
  --service_name=dataplex-agent \
  --with_ui \
  . \
  -- \
  --service-account=$AGENT_SERVICE_ACCOUNT \
  --allow-unauthenticated

此命令完成后，系统会输出一个服务网址 (e.g., https://dataplex-agent-xyz.run.app)。点击该链接即可打开完全受监管的 GenAI Chat 界面。

端到端架构流程

您现已完成该系统。当用户与 ADK 界面互动时，会发生以下序列：

用户在 ADK 代理（开发者界面）中提交提示。
ADK 智能体 (agent.py) 处理输入内容并调用 Gemini 模型。
Gemini 确定需要上下文，并要求 MCP 服务器 执行 Dataplex 工具。
MCP 服务器会强制执行 Dataplex 治理规则并返回元数据。
Gemini 会根据元数据合成可信的回答，并将其返回给用户。

5. 测试企业版代理

现在，您的代理已上线，让我们重新访问之前使用 CLI 测试过的治理方案。逻辑保持不变，但您现在与已部署的 ADK Web Playground 进行互动，该 Playground 可直观呈现内部状态和工具执行情况。

编排：ADK 代理（在 Cloud Run 上运行）接收您的文本。
工具路由：Gemini 识别出您的问题需要数据上下文，并将请求转发到 MCP 服务器。
治理检查：MCP 服务器（在单独的 Cloud Run 实例上运行）向 Dataplex 查询特定的 Aspect 类型。
合成：相关元数据会返回给 Gemini，以生成最终答案。

验证治理逻辑

在浏览器中打开您在上一步中生成的服务网址 (e.g., https://dataplex-agent-xyz.run.app)。粘贴以下提示：

"My dashboard needs to show what's happening right now with our ad spend. I can't wait for the overnight load. What do you recommend?"

在开发者界面中观察智能体的推理过程：

意图识别：代理会解析“现在”和“等不及过夜”。
元数据查找：它会调用 MCP 工具 search_aspect_types。它会查找 update_frequency Aspect 设置为 REALTIME 或 STREAMING 而不是 DAILY 或 MONTHLY 的数据资产。
选择：它会识别出表 mkt_realtime_campaign_performance 符合这些条件，而 fin_monthly_closing_internal（尽管质量很高）对于您的请求来说速度太慢。
回答：智能体建议使用实时表。

重要性：

如果没有这种治理元数据，LLM 可能会推荐 fin_monthly_closing_internal 表，仅仅是因为它有一个名为“ad_spend”的列，而忽略了数据是 24 小时前的事实。您的元数据上下文避免了业务错误。

您还可以测试“董事会会议”提示，看看代理如何根据“数据产品层级”方面切换到不同的表格：

"We are preparing the deck for an internal Board of Directors meeting next week. I need the numbers to be absolutely finalized, trustworthy, and kept strictly confidential. Which table is safe to use?"

6. 清理

为避免系统因本 Codelab 中使用的资源向您的 Google Cloud 账号收取费用，请按照以下步骤销毁在第 1 部分和第 2 部分中创建的所有基础架构。

销毁数据湖 (Terraform)

使用 Terraform 拆除 BigQuery 表、数据集和 Dataplex Aspect 定义。

cd ~/devrel-demos/data-analytics/governance-context/terraform
terraform destroy -var="project_id=${PROJECT_ID}" -var="region=${REGION}" -auto-approve

删除 Cloud Run 服务

移除计算资源，以停止对运行中的容器进行任何有效结算。

gcloud run services delete governance-mcp --region=$REGION --quiet
gcloud run services delete dataplex-agent --region=$REGION --quiet

清理 build 工件和临时存储空间

当您使用 uvx 部署 ADK 代理时，系统会自动构建容器映像，并将您的源代码上传到临时 Cloud Storage 存储分区。即使在删除 Cloud Run 服务后，这些制品也会保留，并会持续产生存储费用。

移除 Artifact Registry 代码库和 Cloud Storage 临时存储分区：

# Delete the repository used for the agent build
gcloud artifacts repositories delete cloud-run-source-deploy \
    --location=$REGION \
    --quiet

# Delete the staging bucket created by Cloud Run source deploy
gcloud storage rm --recursive gs://run-sources-${PROJECT_ID}-${REGION}

删除身份、权限和 Secret

请先移除 IAM 政策绑定，以防止“标记为已删除”的条目（孤立的记录）保留在项目的 IAM 页面中。然后，删除服务账号和配置 Secret。

# Remove IAM roles granted to the MCP Service Account
gcloud projects remove-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$MCP_SERVICE_ACCOUNT" \
  --role="roles/secretmanager.secretAccessor" --quiet
gcloud projects remove-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$MCP_SERVICE_ACCOUNT" \
  --role="roles/dataplex.catalogViewer" --quiet
gcloud projects remove-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$MCP_SERVICE_ACCOUNT" \
  --role="roles/bigquery.dataViewer" --quiet

# Remove IAM roles granted to the Agent Service Account
gcloud projects remove-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$AGENT_SERVICE_ACCOUNT" \
  --role="roles/aiplatform.user" --quiet

# Delete the Service Accounts
gcloud iam service-accounts delete $MCP_SERVICE_ACCOUNT --quiet
gcloud iam service-accounts delete $AGENT_SERVICE_ACCOUNT --quiet

# Delete the Secret Manager entry
gcloud secrets delete dataplex-tools-config --quiet

移除本地配置

最后，清理 Cloud Shell 中的本地配置文件和环境变量。

# Uninstall the Gemini CLI extension (installed in Part 1)
gemini extensions uninstall dataplex

# Remove local repository files and unset variables
cd ~
rm -rf ~/devrel-demos
unset MCP_SERVER_URL
unset MCP_SERVICE_ACCOUNT
unset AGENT_SERVICE_ACCOUNT

7. 恭喜！

您已成功部署端到端、具有治理意识的生成式 AI 代理。

在此分为两部分的 Codelab 中，您不仅学习了简单的提示工程，还实现了稳健且可用于生产环境的架构。通过将数据治理视为生成式 AI 的前提条件，您建立了一种系统性方法，可防止模型检索未经认证或虚假的数据。

重点小结

通过元数据实现确定性 AI：您没有依赖 LLM 根据列名称猜测正确的表格，而是使用生成式 AI 数据库工具包强制执行严格的推理循环。通过仅明确公开三个 Dataplex 工具（search_aspect_types、search_entries、lookup_entry），您强制模型在合成答案之前验证数据认证。
解耦架构 (MCP)：通过在 Cloud Run 上部署 Model Context Protocol (MCP) 服务器，您可以将数据治理规则抽象为集中式标准化 API。前端代理不需要包含数据库逻辑，只需要通过 MCP 标准进行通信。这意味着，您可以将任何未来的 AI 模型或客户端插入到同一受监管的后端中。
职责分离：您通过隔离 IAM 身份应用了最小权限原则。面向用户的 ADK 代理在权限受限的情况下运行，仅限于模型调用和 API 路由，而后端 MCP 服务器则安全地处理 Dataplex 目录查询和 BigQuery 数据检索。
代码优先的智能体编排：您利用 Google 智能体开发套件 (ADK) 将 Python 智能体逻辑立即封装到可扩缩的 FastAPI 后端中，并利用其内置的开发者界面来直观呈现和调试智能体的内部工具执行情况。

后续还有哪些变化？

Dataplex 基础治理 Codelab：在添加 AI 层之前，先掌握 Dataplex 中的数据治理基础知识。
Dataplex 工具文档：探索本实验中使用的预构建 Dataplex 工具和扩展程序的官方文档。
Gemini CLI 扩展程序使用入门：了解如何构建自己的自定义扩展程序，以便为 GenAI 代理提供更多功能。
深入了解 MCP：查看官方 MCP 规范，了解如何为内部企业 API 构建自定义服务器。