用 Terraform 和 Cloud Run 部署多 Agent 系统

用 Terraform 和 Cloud Run 部署多 Agent 系统 | 前端进阶之旅

Full translation

完整中文译文

Google Cloud 开发者关系团队 AI 工程负责人

为了践行我们加速开发者使用 Google Cloud 之旅的使命，我们构建了 Dev Signal：一个多 Agent 系统，旨在自动完成从信息发现到专家级内容创作的全过程，将原始的社区信号转化为可靠的技术指导。

在本系列的前三部分中，我们通过建立核心能力和本地验证流程，打下了必要的基础：

在第 1 部分中，我们通过 Model Context Protocol（MCP）对 Agent 的能力进行了标准化：连接 Reddit 以发现趋势，连接 Google Cloud Docs 以获得可靠的技术依据。在第 2 部分中，我们构建了多 Agent 架构，并集成 Vertex AI memory bank，让系统能够学习并持久保存用户偏好，在不同对话之间延续这些信息。在第 3 部分中，我们使用专门的测试运行器，在本地验证了完整的端到端生命周期，确保研究、内容创作和云端记忆检索能够完美协同。

如果你想直接查看代码，可以克隆该代码仓库。

部署到 Cloud Run 与迈向生产环境

为了帮助你将这个本地原型转变为生产服务，本系列的最后一部分将重点介绍如何使用 Agent Starter Pack 提供的基础部署模式，为 Agent 构建生产级基础设施。我们将实现云端监控、数据完整性和长期状态管理所需的核心结构组件。你将学习如何实现生产部署所需的应用服务器和辅助工具，然后使用 Terraform 配置安全且可复现的基础设施。

Dockerfile 负责打包 Agent 代码及其专用依赖，例如 Reddit MCP 工具所需的 Node.js；Terraform 则用于构建承载它的平台。Terraform 会自动创建 Artifact Registry、遵循最小权限原则的 Service Account，以及 Secret Manager 集成，确保你的 API key 始终受到保护。

完成这一部分后，你将拥有一个部署在 Google Cloud Run 上的标准化应用框架，并获得一份路线图，帮助你通过持续评估、CI/CD 和高级可观测性，将原型逐步升级为成熟的生产系统。

生产工具与服务器：构建系统的“身体”

在这一节中，你将实现云端监控和长期状态管理所需的结构组件。

应用服务器：初始化 FastAPI 服务器，并与 Vertex AI memory bank 建立关键连接。

实现遥测：启用“Agent Traces”，深入观察内部推理过程。

应用服务器

fast_api_app.py 文件是 Agent 的关键入口点，它将核心逻辑转变为生产级 FastAPI 服务器，充当系统的“身体”。部署到 Cloud Run 时，这台服务器至关重要，因为它提供了必要的 Web 接口，用来监听传入的 HTTP 请求，并将请求分派给 Agent 处理。除了提供基本服务外，它最关键的职责是通过定义 MEMORY_URI 与 Vertex AI memory bank 建立连接，使 ADK 框架能够在不同的生产会话之间持久保存和检索用户偏好。此外，应用服务器还会初始化生产级遥测能力，以便进行实时监控。

返回 dev_signal_agent 文件夹。

将以下代码粘贴到 dev_signal_agent/fast_api_app.py 中：

实现遥测

在生产环境中，能够观察 Agent 的推理过程至关重要。我们通过在应用服务器中设置 otel_to_cloud=True，利用 Google ADK 内置的可观测性功能。仅凭这一个参数，就能自动完成大部分插桩工作，并将“Agent Traces”直接导出到 Google Cloud Console。这些 Trace 会以“可视化瀑布图”的形式呈现 Agent 的运行过程，其中包括各个 Agent 的思考过程、LLM 调用和 MCP 工具调用。

必须理解的是，为了平衡性能和成本，生产环境的 Trace 会进行采样。由于 Cloud Run 只捕获一部分请求，因此并非每一次用户交互都能被看到。

系统 Trace（监控）：用于从整体上分析行为，例如识别延迟瓶颈或系统超时。

推理 Trace（评估）：高质量评估要求有针对性地捕获 Trace。这意味着针对某个测试用例专门调用 Agent，并且你明确知道将对该请求进行完整、细致的评估。

如需查看 Trace，请前往 Google Cloud Console 中的 Trace Explorer，并按你的服务进行筛选，例如 dev-signal。点击某个具体的 Trace ID，会打开一张 Gantt 图，帮助你区分认知推理故障（错误决策）和物理系统问题（超时）。

有关高级配置，请参阅以下文档：

Cloud Run Trace 采样

配置 ADK 遥测

多模态 Trace 捕获

BigQuery Agent Analytics 集成

基础设施即代码：配置安全的云资源

我们采用 Agent Starter Pack 以安全优先为核心设计的基础设施即代码模式。Starter Pack 能够在几秒内构建专业的平台基础，自动创建遵循最小权限原则的 Service Account，并提供可靠的密钥管理能力。

使用 Terraform，可以将整个 Google Cloud 环境——从 IAM role 到 Secret Manager version——都定义为安全、可复现的代码。我们将基础设施划分为以下逻辑模块：

资源与变量：定义 Agent 使用的具体项目、区域和敏感 API secret。

核心基础设施：启用必要的 API，并配置用于托管 Agent 容器镜像的私有 Artifact Registry。

身份与访问管理（IAM）：配置严格遵循最小权限原则的专用 Service Account，确保系统安全。

Secret 管理：将 API 凭据安全地导入 Google Secret Manager，以便在运行时受保护地访问。

Cloud Run 配置：定义最终部署所需的容器环境、资源限制和自动 Secret 注入。

要开始配置，请返回项目的根文件夹 dev-signal，并创建必要的部署目录：

Terraform 资源与变量

variables.tf 文件定义了部署时可配置的参数，使你无须修改底层逻辑即可定制基础设施。其中包括 project_id、部署区域（默认为 us-central1），以及 Cloud Run 实例使用的 service_name。此外，它还定义了一个 secrets map，用于将 Reddit 和 Developer Knowledge key 等敏感 API 凭据安全地导入 Google Secret Manager，供运行时访问。这种模块化方式可确保生产环境具备可复现性、安全性，并能灵活适配不同项目。

将以下代码粘贴到 deployment/terraform/variables.tf 中：

核心基础设施逻辑

我们使用多个逻辑模块来定义基础设施。以下是每个部分的作用：

启用 API：确保项目已启用必要的服务，例如 Cloud Run、Vertex AI 等。我们使用 disable_on_destroy = false，防止 Terraform 被销毁时意外丢失数据。

将以下代码粘贴到 deployment/terraform/main.tf 中：

Artifact Registry：创建一个私有 Docker registry，用于存储 Agent 的容器镜像。
Service Account 与 IAM：遵循最小权限原则——这是至关重要的安全步骤。根据最小权限原则，我们不使用默认的 compute service account，而是配置一个专用的、由用户管理的 Service Account（dev-signal-sa）。将其指定为 Cloud Run service identity 后，我们便可以只授予它最低限度的必要权限，具体包括 roles/aiplatform.user、roles/logging.logWriter 和 roles/storage.objectAdmin。这种细粒度访问控制可确保 Agent 拥有与 Vertex AI 和 Cloud Storage 交互所需的准确权限，同时避免过度授予对其他敏感云资源的访问权，从而显著降低账号遭到入侵时可能造成的影响。你可以进一步了解安全使用 Service Account 的最佳实践。
Secret 管理：这一部分负责安全处理 API key。它会在 Google Secret Manager 中创建 Secret，并授予 Agent 的 Service Account 在运行时访问这些 Secret 的权限。
Cloud Run 配置：

安全最佳实践：为了满足生产环境的安全标准，我们的 main.tf 会向 Service Account 授予 secretmanager.secretAccessor role。随后，Python 应用会使用 Secret Manager SDK，在运行时将这些凭据直接拉取到本地内存中，确保它们永远不会进入容器的环境配置。

配置基础设施

在部署代码之前，需要先配置刚刚定义的 Google Cloud 基础设施。

初始化 Terraform：此操作会下载所需的 provider plugin。请在 deployment/terraform 文件夹中运行：

创建变量文件：

将这段代码粘贴到 deployment/terraform/terraform.tfvars 中，并使用你的项目详细信息和 Secret 更新文件内容。

规划配置：这一步允许你在应用变更之前进行检查。请在 deployment/terraform 文件夹中运行：

应用配置：检查 plan 并确认其符合预期后，运行：

部署：容器化与 Cloud Build Pipeline

在构建过程的最后阶段，我们会将 Agent 的“身体”和“大脑”打包进一个可移植、可用于生产的容器。这可以确保从 Python 逻辑到 Reddit MCP 工具所需的 Node.js 环境，所有组件及其确切依赖都被打包在一起。

我们使用 Dockerfile 定义这一环境，并使用 Makefile 编排部署 pipeline。触发部署时，Google Cloud Build 会获取本地源代码，按照 Dockerfile 构建容器镜像，并将其存储到之前由 Terraform 创建的私有 Artifact Registry 中。最后，pipeline 会自动更新 Cloud Run 服务，使其使用这个新镜像处理流量，从而完成从本地代码到在线、安全的云工作负载的整个过程。

将以下代码粘贴到 dev-signal/Dockerfile 中：

Makefile 会自动完成构建和部署。

将以下代码粘贴到 dev-signal/Makefile 中：

现在基础设施已经准备完毕，我们可以构建并部署应用代码。

在项目根目录中运行以下命令：

运行后会发生什么？

构建：Google Cloud Build 获取本地代码和 Dockerfile，构建容器镜像，并将其存储到 Artifact Registry 中。

部署：更新 Terraform 中定义的 Cloud Run 服务，使其使用这个新镜像。

部署完成后，你应该会看到类似下面的消息：

Service [dev-signal] revision [dev-signal...] has been deployed and is serving 100 percent of traffic.

Service URL: https://dev-signal-...-.us-central1.run.app

验证：访问并测试已部署的 Agent

由于生产服务默认处于私有状态，本节将介绍如何授予权限并安全地访问 Agent。

管理 IAM 权限：向获得授权的用户授予必要的 run.invoker role。

通过 Cloud Run Proxy 安全访问：使用 gcloud proxy 与在线服务交互。

授予用户权限

在调用该服务之前，你必须为自己的 Google 账号授予此特定服务的 roles/run.invoker role。运行以下命令：

现在，通过 proxy 安全访问你的私有服务：

访问 http://localhost:8080，与已部署的 Agent 对话！你可以在本系列第 3 部分中查看一个可能的测试场景。

恭喜！你已经成功构建了 Dev Signal。

工具（MCP）：你使用 Model Context Protocol，将 Agent 连接到了 Reddit、Google Docs 和本地 Image Generator。

架构：你实现了一个 Root Orchestrator，用来管理多个专用 Agent（Scanner、Expert、Drafter）。

记忆：你集成了 Vertex AI memory bank，使 Agent 能够跨会话长期保存信息。

生产部署：你使用 Terraform 将整个技术栈部署到了 Google Cloud Run，获得了安全且可复现的基础设施。

现在，你已经拥有了坚实的基础，可以在 Google Cloud 上构建复杂且有状态的 AI 应用。

开发者与从业者

使用任意 coding agent 自动化 Agent 开发生命周期

作者：Shubham Saboo · 阅读时长 7 分钟

为什么 AI 应用会在生产环境中失败（以及 Google 如何解决这一问题）

作者：Stephanie Wong · 阅读时长 4 分钟

有条件的宽容：强化 Google Cloud 访问管理

作者：Leonid Yankulin · 阅读时长 5 分钟

在 Gemini Enterprise Agent Platform 上构建应用的 13 个实操演示

作者：Shubham Saboo · 阅读时长 6 分钟