使用 agents-cli 部署到 Agent Runtime¶

Supported in ADKPython

本部署流程介绍如何使用 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.

Note

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。

Important

在执行这些步骤之前，请确保你的 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 上运行的智能体进行交互。有关测试已部署智能体的详细信息，请参阅测试已部署的智能体。

Changes to your ADK project¶

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

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

After running the agents-cli scaffold enhance command to add Agent Runtime deployment information, the new structure is as follows:

my-agent/
├─ app/                 # Core application code
│   ├─ agent.py         # Main agent logic
│   ├─ agent_engine_app.py # Agent Runtime application logic
│   └─ utils/           # Utility functions and helpers
├─ .cloudbuild/         # CI/CD pipeline configurations for Google Cloud Build
├─ deployment/          # Infrastructure and deployment scripts
├─ notebooks/           # Jupyter notebooks for prototyping and evaluation
├─ tests/               # Unit, integration, and load tests
├─ Makefile             # Makefile for common commands
├─ GEMINI.md            # AI-assisted development guide
└─ pyproject.toml       # Project dependencies and configuration

See the README.md file in your updated ADK project folder for more information. For more information on using agents-cli, see the agents-cli documentation.

测试已部署的智能体¶

After completing deployment of your ADK agent you should test the workflow in its new hosted environment. For more information on testing an ADK agent deployed to Agent Runtime, see Test deployed agents in Agent Runtime.