使用 Agents CLI 部署到 Agent Runtime¶

Supported in ADKPythonGo v1.2.0

本部署过程介绍如何使用 Agent Platform 中的 Agents CLI 以及 ADK 进行部署。通过 Agents CLI 部署到 Agent Runtime 提供了一条通往生产就绪环境的加速路径。Agents CLI 能自动配置 Google Cloud 资源、CI/CD 流水线和基础设施即代码 (Terraform)，以支持整个开发生命周期。作为最佳实践，在生产部署之前，请务必检查所生成的配置，确保其符合你组织的安全和合规标准。

本部署指南使用 Agents CLI 将项目模板应用于你现有的项目，添加工件，并让你的智能体项目为部署做好准备。以下说明将向你展示如何使用 Agents CLI 配置一个 Google Cloud 项目及部署你的 ADK 项目所需的服务，内容如下：

前置条件：设置 Google Cloud 项目、IAM 权限并安装所需的软件。
准备你的 ADK 项目：修改你现有的 ADK 项目文件以便为部署做好准备。
连接到你的 Google Cloud 项目：将你的开发环境连接到 Google Cloud 及你的 Google Cloud 项目。
部署你的 ADK 项目：在你的 Google Cloud 项目中配置所需的服务并上传你的 ADK 项目代码。

有关测试已部署智能体的信息，请参阅测试已部署的智能体。有关使用 Agents CLI 及其命令行工具的更多信息，请参阅CLI 参考和指南。

前置条件¶

你需要配置以下资源才能使用此部署路径：

Google Cloud 项目和权限：一个已启用结算的 Google Cloud 项目。你可以使用现有项目或创建一个新项目。你必须在此项目中拥有以下 IAM 角色之一：
- Agent Platform User 角色 — 足以将智能体部署到 Agent Runtime。
- Owner 角色 — 完整的生产环境设置所需（Terraform 基础设施配置、CI/CD 流水线、IAM 配置）。

注意

建议使用空项目以避免与现有资源冲突。对于新项目，请参阅创建和管理项目。

Python 环境：Agents CLI 所支持的 Python 版本。
uv 工具：管理 Python 开发环境和运行 agents-cli 工具。有关安装详情，请参阅安装 uv。
Google Cloud CLI 工具：gcloud 命令行界面。有关安装详情，请参阅 Google Cloud 命令行界面。
Make 工具：构建自动化工具。此工具是大多数 Unix 系统的一部分，有关安装详情，请参阅 Make 工具文档。

准备你的 ADK 项目¶

当你将 ADK 项目部署到 Agent Runtime 时，需要一些额外的文件来支持部署操作。以下 Agents CLI 命令会备份你的项目，然后为部署目的添加文件到你的项目中。

这些说明假设你有一个为了部署而正在修改的现有 ADK 项目。如果你还没有 ADK 项目，或者想使用测试项目，请完成入门指南之一，它会创建一个智能体项目。以下说明以 my_agent 项目为例。

要为部署到 Agent Runtime 准备你的 ADK 项目：

在开发环境的终端窗口中，导航到包含你的智能体文件夹的父目录。例如，如果你的项目结构是：
```
your-project-directory/
├── my_agent/
│   ├── __init__.py
│   ├── agent.py
│   └── .env
```
导航到 your-project-directory/
运行 Agents CLI scaffold enhance 命令，将部署所需的文件添加到你的项目中。
```
agents-cli scaffold enhance --deployment-target agent_engine
```
按照 Agents CLI 工具的说明进行操作。通常，你可以接受所有问题的默认答案。但针对 GCP 区域选项，请确保选择 Agent Runtime 的支持区域之一。

成功完成此过程后，该工具会显示以下消息：

> Success! Your agent project is ready.

注意

Agents CLI 工具在运行过程中可能会显示连接到 Google Cloud 的提醒，但此阶段不需要进行该连接。

有关 Agents CLI 对你的 ADK 项目所做更改的更多信息，请参阅对你的 ADK 项目的更改。

连接到你的 Google Cloud 项目¶

在部署 ADK 项目之前，你必须连接到 Google Cloud 和你的项目。登录到你的 Google Cloud 账户后，你应该验证你的部署目标项目对你的账户可见，并且它已配置为你的当前项目。

要连接到 Google Cloud 并列出你的项目：

在开发环境的终端窗口中，登录到你的 Google Cloud 账户：
```
gcloud auth application-default login
```
使用 Google Cloud 项目 ID 设置你的目标项目：
```
gcloud config set project your-project-id-xxxxx
```
验证你的 Google Cloud 目标项目已设置：
```
gcloud config get-value project
```

成功连接到 Google Cloud 并设置你的 Cloud 项目 ID 后，你就可以将 ADK 项目文件部署到 Agent Runtime 了。

部署你的 ADK 项目¶

使用 Agents CLI 时，你可以通过 agents-cli deploy 命令进行部署。该命令从你的智能体代码构建容器，将其推送到注册表，并部署到托管环境中的 Agent Runtime。

重要

在执行这些步骤之前，请确保你的 Google Cloud 目标部署项目已设置为你的当前项目*。agents-cli deploy 命令在执行部署时使用你当前设置的 Google Cloud 项目。有关设置和检查当前项目的信息，请参阅连接到你的 Google Cloud 项目。

要将你的 ADK 项目部署到 Google Cloud 项目中的 Agent Runtime：

在终端窗口中，导航到你的智能体项目目录（例如 your-project-directory/）。
将你的智能体代码部署到 Google Cloud 开发环境：
```
agents-cli deploy
```
该命令从 pyproject.toml 读取你的 deployment_target，并部署到配置的目标（Agent Runtime、Cloud Run 或 GKE）。
（可选）要启用提示词-响应日志记录和内容日志等可观测性功能，请配置遥测基础设施：
```
agents-cli infra single-project
```
有关更多详情，请参阅可观测性指南。

成功完成后，你应该可以与 Google Cloud Agent Runtime 上运行的智能体进行交互。有关测试已部署智能体的详细信息，请参阅测试已部署的智能体。

对你的 ADK 项目的更改¶

Agents CLI 工具会为部署添加更多文件到你的项目中。以下过程在修改前会备份你现有的项目文件。本指南使用 multi_tool_agent 项目作为参考示例。原始项目具有以下初始文件结构：

my_agent/
├─ __init__.py
├─ agent.py
└─ .env

运行 Agents CLI scaffold enhance 命令添加 Agent Runtime 部署信息后，新的结构如下：

my-agent/
├─ app/                 # 核心应用代码
│   ├─ agent.py         # 主智能体逻辑
│   ├─ agent_engine_app.py # Agent Runtime 应用逻辑
│   └─ utils/           # 实用函数和辅助工具
├─ .cloudbuild/         # Google Cloud Build 的 CI/CD 流水线配置
├─ deployment/          # 基础设施和部署脚本
├─ notebooks/           # 用于原型设计和评估的 Jupyter Notebook
├─ tests/               # 单元测试、集成测试和负载测试
├─ Makefile             # 常用命令的 Makefile
├─ GEMINI.md            # AI 辅助开发指南
└─ pyproject.toml       # 项目依赖项和配置

有关更多信息，请参阅更新后的 ADK 项目文件夹中的 README.md 文件。有关使用 Agents CLI 的更多信息，请参阅 Agents CLI 文档。

测试已部署的智能体¶

完成 ADK 智能体部署后，你应该在其新的托管环境中测试工作流。有关测试部署到 Agent Runtime 的 ADK 智能体的更多信息，请参阅在 Agent Runtime 中测试已部署的智能体。