ADK智能体在Cloud Run上的完整部署指南

在我们之前对Google智能体开发工具包(ADK)的详细介绍中，我向您展示了使用ADK构建AI智能体的三种方法：Python、YAML和可视化构建器。虽然本地开发非常适合原型设计，但生产级智能体需要部署到能够扩展并为真实用户提供服务的环境中。

Google Cloud Run是ADK智能体的天然选择。作为一个完全托管的无服务器平台，它处理基础设施问题，让您专注于智能体逻辑。这种部署特别优雅的原因是ADK内置的adk deploy cloud_run命令，它可以打包您的智能体、构建容器镜像、推送到Artifact Registry并部署到Cloud Run——所有这些都在一个步骤中完成。

在本教程中，我将指导您将天气和时间智能体部署到Cloud Run，包括使用Google Secret Manager进行安全的API密钥管理。最后，您将拥有一个通过公共URL访问的生产级智能体，并启用ADK网络界面进行交互式测试。

部署流程概述

在深入实施之前，让我们了解将ADK智能体部署到Cloud Run时发生的情况。

adk deploy cloud_run命令自动化了几个复杂的操作。它分析您的项目结构和依赖项以生成优化的Docker镜像。然后将此镜像推送到Google Artifact Registry，这是Google Cloud项目内的安全容器存储库。最后，Cloud Run提供运行您智能体的无服务器实例，具有自动扩展、HTTPS和IAM集成功能。

--with_ui标志很有用，因为它将ADK网络开发界面与您智能体的API服务器捆绑在一起，为您提供直接在浏览器中测试对话的交互界面。

准备工作

开始之前，请确保您具备：

安装Python 3.10或更高版本

安装并配置Google Cloud SDK (gcloud)

启用了计费的Google Cloud项目

启用以下API：Cloud Run、Artifact Registry、Secret Manager和Vertex AI

来自Google AI Studio的Google API密钥（用于Gemini访问）

创建智能体项目

让我们创建具有所需目录结构的智能体项目。ADK需要特定的布局才能正常部署。

创建智能体的新目录，ADK要求您的智能体目录中有三个文件：__init__.py、agent.py和requirements.txt。部署工具会在您的智能体代码中查找名为root_agent的变量——这种命名约定是必需的。

创建__init__.py文件，此文件将目录标记为Python包并导入智能体模块。

实现智能体逻辑

创建包含天气和时间工具的agent.py文件。智能体定义了两个工具：get_weather和get_current_time。注意每个函数都包含带有类型提示的详细文档字符串——ADK使用这些来帮助大语言模型理解何时以及如何调用每个工具。root_agent变量是ADK部署命令将查找的入口点。

创建requirements.txt文件。您的项目结构现在应该如下所示：

requirements.txt

weather_time/

├── __init__.py

├── agent.py

本地测试

在部署到Cloud Run之前，验证您的智能体在本地环境中正常工作至关重要。在项目根目录中创建.env文件，将占位符替换为您实际的Google AI Studio API密钥。

导航到父目录并在本地运行智能体。使用以下提示测试智能体：

"纽约的天气如何？"

"纽约现在几点？"

确认智能体正确响应后，输入exit退出本地会话。现在我们准备部署到Cloud Run。

配置秘密管理

生产部署永远不应该硬编码API密钥。Google Secret Manager为敏感凭证提供安全存储和访问控制。让我们在那里存储API密钥。

首先，为您的Google Cloud项目设置环境变量，从API密钥创建秘密。Cloud Run服务账户需要访问此秘密的权限。授予Secret Accessor角色，将PROJECT_NUMBER替换为您实际的Google Cloud项目号码。

执行部署

配置秘密后，我们准备部署。设置部署变量并执行部署命令。

让我们分解这些参数：在部署期间，可能会提示您关于未经身份验证的访问。对于初始测试，您可以允许它；但对于生产部署，建议要求身份验证。

部署过程需要几分钟。完成后，您将看到类似的输出：部署成功！服务URL: https://weather-time-xxxxx.us-central1.run.app

测试已部署的智能体

在浏览器中打开服务URL。由于您包含了--with_ui标志，您将看到ADK开发者界面。这与您在本地开发期间使用的UI相同，现在在Cloud Run上运行。

在右上角启用"Token Streaming"以提高响应性。您现在可以与已部署的智能体交互：询问"今天纽约的天气如何？"智能体应该使用get_weather工具响应，返回纽约的天气信息。

尝试后续问题："那里现在几点？"智能体将调用get_current_time工具提供纽约时区的当前时间。

清理资源

为避免产生未来费用，在完成实验后删除Cloud Run服务。您可能还想删除秘密。

总结

本教程演示了从本地ADK智能体到生产Cloud Run部署的最快路径。adk deploy cloud_run命令抽象了容器化复杂性，让您专注于智能体逻辑，同时利用Cloud Run的无服务器可扩展性。

在后续教程中，我们将探索高级部署场景，包括将ADK智能体连接到MCP服务器进行外部工具集成、使用Cloud SQL实现会话持久性、部署具有顺序和并行编排模式的多智能体系统，以及配置GPU加速后端来运行Gemma等开放模型。

您在这里构建的基础——理解部署工作流程、安全管理秘密和使用网络界面测试——将在我们处理越来越复杂的生产架构时为您提供良好的服务。

Q&A

Q1：Google Cloud Run适合部署ADK智能体的原因是什么？

A：Google Cloud Run是完全托管的无服务器平台，它处理基础设施问题让开发者专注于智能体逻辑。ADK内置的adk deploy cloud_run命令可以一键完成打包智能体、构建容器镜像、推送到Artifact Registry并部署到Cloud Run的全部流程，支持自动扩展、HTTPS和IAM集成。

Q2：为什么生产环境不能硬编码API密钥？

A：生产部署中硬编码API密钥存在严重安全风险。应该使用Google Secret Manager来安全存储和管理敏感凭证，它提供访问控制和权限管理功能，确保只有授权的服务账户才能访问API密钥。

Q3：--with_ui标志在部署中有什么作用？

A：--with_ui标志会将ADK网络开发界面与智能体的API服务器捆绑部署，提供交互式的浏览器界面用于测试对话。部署完成后，可以通过服务URL直接在浏览器中与智能体进行交互测试，无需额外的开发工具。