如何把 ADK 智能体部署到 Vertex AI Agent Engine 并连接 Cloud Run 上的 MCP Toolbox-开发者社区

如何把 ADK 智能体部署到 Vertex AI Agent Engine 并连接 Cloud Run 上的 MCP Toolbox

【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox

这篇文章解决一个具体的部署任务：你已经有一个能在本地运行、并通过ToolboxToolset连接本地 MCP Toolbox 的 ADK（Agent Development Kit）智能体，现在要把它部署到 Vertex AI Agent Engine，同时让智能体在生产环境中连接部署在 Cloud Run 上的 MCP Toolbox 实例。最终结果是：在 Agent Engine Playground 中打开一个可对话的已部署智能体，工具调用经由 Cloud Run 上的 MCP Toolbox 完成。

整条操作链包含两个部署动作：先把 MCP Toolbox 部署到 Cloud Run 并拿到服务 URL，再为智能体项目生成部署配置、把ToolboxToolset指向 Cloud Run URL、最后执行make deploy。

准备条件

开始前需要满足以下条件（来源：部署 ADK Agent 与 MCP Toolbox 和 Cloud Run 部署指南）：

已完成 Python Quickstart (Local)，本地有一个可运行的 ADK 智能体（项目目录结构为包含my_agent文件夹的智能体项目）。
已安装 Google Cloud CLI（gcloud）。
一个已启用计费的 Google Cloud 项目，并且你的数据库已经创建并初始化完成。

账号需要以下 IAM 角色：

创建服务账号：roles/iam.serviceAccountCreator
创建密钥（Secret）：roles/secretmanager.admin
部署 Cloud Run：roles/run.developer和roles/iam.serviceAccountUser

把 MCP Toolbox 部署到 Cloud Run

初始化 gcloud 并启用所需 API

先设置项目环境变量并初始化 CLI：

export PROJECT_ID="my-project-id" gcloud init gcloud config set project $PROJECT_ID

然后启用 Cloud Run 部署所需的 API：

gcloud services enable run.googleapis.com \ cloudbuild.googleapis.com \ artifactregistry.googleapis.com \ iam.googleapis.com \ secretmanager.googleapis.com

创建服务账号并授权

如果还没有后端的后端服务账号，创建一个名为toolbox-identity的服务账号，并授予其读取 Secret Manager 的权限：

gcloud iam service-accounts create toolbox-identity gcloud projects add-iam-policy-binding $PROJECT_ID \ --member serviceAccount:toolbox-identity@$PROJECT_ID.iam.gserviceaccount.com \ --role roles/secretmanager.secretAccessor

此外还要按你使用的数据源追加对应权限，文档给出的两个示例：

AlloyDB for PostgreSQL：参考 AlloyDB 数据源文档的 IAM 认证部分
Cloud SQL for PostgreSQL：参考 Cloud SQL PG 数据源文档的 IAM 权限部分

如果你的数据源使用 VPC 接入（例如 AlloyDB、私网 IP 的 Cloud SQL），需要确保 Cloud Run 服务和数据库处于同一个 VPC 网络。

上传 tools.yaml 并部署

准备好你的tools.yaml配置文件（配置格式见 configuration 文档），然后把它作为 Secret 上传：

gcloud secrets create tools --data-file=tools.yaml

如果 Secrettools已存在、只需要更新版本，用下面这条命令：

gcloud secrets versions add tools --data-file=tools.yaml

设置镜像环境变量，然后部署到 Cloud Run：

export IMAGE=us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest gcloud run deploy toolbox \ --image $IMAGE \ --service-account toolbox-identity \ --region us-central1 \ --set-secrets "/app/tools.yaml=tools:latest" \ --args="--config=/app/tools.yaml","--address=0.0.0.0","--port=8080"

两个必须注意的点：

端口固定为 8080。Cloud Run 通过容器内的$PORT环境变量指定监听端口，默认 8080。--port参数必须与之一致，否则容器启动失败、部署会超时报 "Container failed to start"。
上面的命令保持服务受鉴权保护（命令中被注释的--allow-unauthenticated可选参数可以放开匿名访问，但文档的部署示例默认保留鉴权，后文的智能体连接正是依赖 workload identity 鉴权，不建议放开）。

可选：VPC 网络部署。如果数据库在特定 VPC 子网中，需要加--network和--subnet参数。先用下面两条命令查询你项目的网络和子网值：

gcloud compute networks list gcloud compute networks subnets list --regions=us-central1

然后把部署命令改为：

# 如果数据库使用不同的 VPC 网络或子网，替换 default 值 gcloud run deploy toolbox \ --image $IMAGE \ --service-account toolbox-identity \ --region us-central1 \ --set-secrets "/app/tools.yaml=tools:latest" \ --args="--config=/app/tools.yaml","--address=0.0.0.0","--port=8080" \ --network default \ --subnet default

可选：加固已部署的服务。为防止 DNS rebinding 攻击，用--allowed-hosts指定允许的主机列表；为实现 CORS 检查，用--allowed-origins指定允许的源。两者都需要重新部署一次：

export URL=<你的 Cloud Run 服务 URL> export HOST=<你的 Cloud Run 主机名> gcloud run deploy toolbox \ --image $IMAGE \ --service-account toolbox-identity \ --region us-central1 \ --set-secrets "/app/tools.yaml=tools:latest" \ --args="--config=/app/tools.yaml","--address=0.0.0.0","--port=8080","--allowed-origins=$URL","--allowed-hosts=$HOST"

记录服务 URL

部署完成后，记下 MCP Toolbox 的 Cloud Run Service URL——后面配置智能体要用到：

gcloud run services describe toolbox --format 'value(status.url)'

准备 ADK 智能体项目

回到本地的智能体项目。用agent-starter-pack工具为项目补齐部署到 Vertex AI Agent Engine 所需的配置：

打开终端，进入智能体项目的父目录（即包含my_agent文件夹的那一层）。

运行增强命令：

uvx agent-starter-pack enhance --adk -d agent_engine

按交互提示配置部署设置。该过程会在项目目录中生成部署配置文件（包括Makefile和Dockerfile）。
给新项目添加依赖：
```
uv add google-adk[toolbox]
```

配置本地认证

执行部署前，确保本地环境已通过 Google Cloud 认证：

gcloud auth application-default login

设置当前活动项目（<YOUR_PROJECT_ID>替换为你的项目 ID）：

gcloud config set project <YOUR_PROJECT_ID>

把智能体指向 Cloud Run 上的 Toolbox

打开智能体文件my_agent/agent.py，把ToolboxToolset的初始化从本地地址改为指向 Cloud Run 服务 URL。因为 Cloud Run 服务默认受鉴权保护，需要同时提供 workload identity（该策略会用你的 ADC 生成针对目标 URL 的 ID token）：

from google.adk import Agent from google.adk.apps import App from google.adk.tools.toolbox_toolset import ToolboxToolset from toolbox_adk import CredentialStrategy # 替换为上面 gcloud run services describe 查到的 Toolbox Cloud Run Service URL TOOLBOX_URL = "https://your-toolbox-service-xyz.a.run.app" # 用 Workload Identity 初始化 toolset（为 URL 生成 ID token） toolset = ToolboxToolset( server_url=TOOLBOX_URL, credentials=CredentialStrategy.workload_identity(target_audience=TOOLBOX_URL) ) root_agent = Agent( name='root_agent', model='gemini-2.5-flash', instruction="You are a helpful AI assistant designed to provide accurate and useful information.", tools=[toolset], ) app = App(root_agent=root_agent, name="my_agent")

其中TOOLBOX_URL是唯一需要替换的值，来自前面gcloud run services describe的输出；workload_identity策略是 Cloud Run/GKE 场景的推荐认证方式（参见 toolbox-adk 的 Authentication 文档）。

注意App初始化中的name参数必须与智能体父目录名一致（例如my_agent）：

app = App(root_agent=root_agent, name="my_agent")

部署到 Agent Engine 并验证

在智能体项目目录中执行部署：

make deploy

这条命令会构建智能体的容器镜像并部署到 Vertex AI。make deploy完成后会输出 Agent Engine Playground 的 URL，在浏览器中打开该 URL，就可以与已部署的智能体对话、触发工具调用，确认整条链路（Playground → Agent Engine 上的智能体 → Cloud Run 上的 MCP Toolbox → 数据库）工作正常。

常见问题排查

部署或连接出错时，文档给出的第一排查动作是：在 Google Cloud Console 的 Cloud Run 部分查看服务日志，日志里通常包含定位问题所需的错误信息。

部署失败，报 "Container failed to start"：几乎都是端口不匹配。确认--port参数设为8080，与 Cloud Run 注入的$PORT一致。
客户端收到 401/403：调用方没有正确获得 invoker 身份。确认调用服务所用的用户或服务账号拥有Cloud Run Invoker（roles/run.invoker）角色；本地运行时确认已执行gcloud auth application-default login完成 ADC 配置。
日志显示访问 Secret 时 "permission denied"：toolbox-identity服务账号缺少权限，确认它拥有roles/secretmanager.secretAccessor角色。
IAP 限制：目前不支持通过 IAP 连接 Cloud Run。如果项目上启用了 IAP，需要将其关闭。