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

1. 简介

此 Codelab 是一个由两部分组成的系列教程的第二部分，将介绍如何构建具有治理意识的生成式 AI 智能体。

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

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

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

前提条件

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

学习内容

如何使用 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 模型编写自定义 API 集成代码，而是为 AI 提供了一种安全连接到企业数据工具（如 Dataplex 和 BigQuery）的标准方式。
智能体开发套件 (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 数据湖并应用 Dataplex 治理元数据，就像我们在第 1 部分中所做的那样。

# 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 成功测试了治理逻辑。这对于快速原型设计非常有用，但它会在本地使用您的个人用户凭据运行。

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

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

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

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

GenAI Toolbox 需要声明性配置文件 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（了解规则）：当用户询问“董事会批准的数据”时，大语言模型不知道这意味着什么。它使用此工具搜索 Dataplex 切面类型。它发现“董事会批准”对应于一个名为 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

现在，我们部署 GenAI Toolbox。我们使用 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！您的 GenAI 前端不会直接访问数据库，而是会连接到此 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 不会编写自定义 HTTP 客户端来与 Dataplex 工具交互，而是使用 MCPToolset(server_url=mcp_url)。这会从已部署的 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 调用方：安全地调用 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 聊天界面。

端到端架构流程

您现在已完成系统。当用户与 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 以获取特定的切面类型。
合成：相关元数据会返回给 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 切面设置为 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 切面定义。

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 根据列名称猜测正确的表，而是使用 GenAI Toolbox for Databases 强制执行严格的推理循环。通过明确仅公开三个 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 构建自定义服务器。

使用 MCP 和 Cloud Run 部署企业治理感知型智能体 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。