使用 Agent Starter Pack 部署到 Agent Engine¶

Supported in ADKPython

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

本部署指南使用 ASP 工具将项目模板应用于你的现有项目，添加部署产物，并为你的智能体项目做好部署准备。这些说明向你展示如何使用 ASP 为部署 ADK 项目所需的服务配置 Google Cloud 项目，如下所示：

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

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

前置条件¶

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

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

注意

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

Python 环境：ASP 项目支持的 Python 版本。
uv 工具：管理 Python 开发环境及运行 ASP 工具。有关安装详细信息，请参阅安装 uv。
Google Cloud CLI 工具：gcloud 命令行界面。有关安装详细信息，请参阅 Google Cloud 命令行界面。
Make 工具：构建自动化工具。该工具是大多数类 Unix 系统的一部分，有关安装详细信息，请参阅 Make 工具文档。

准备你的 ADK 项目¶

当你将 ADK 项目部署到 Agent Engine 时，你需要一些额外的文件来支持部署操作。以下 ASP 命令会备份你的项目，然后向你的项目添加用于部署目的的文件。

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

要准备你的 ADK 项目以部署到 Agent Engine:

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

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

> Success! Your agent project is ready.

注意

ASP 工具在运行时可能会显示连接到 Google Cloud 的提醒，但在此阶段不需要该连接。

有关 ASP 对你的 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 Engine 了。

部署你的 ADK 项目¶

使用 ASP 工具时，你分阶段部署。在第一阶段，你运行一个 make 命令，该命令配置在 Agent Engine 上运行 ADK 工作流所需的服务。在第二阶段，该工具将你的项目代码上传到 Agent Engine 服务并在托管环境中运行它。

重要

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

要将 ADK 项目部署到 Google Cloud 项目中的 Agent Engine:

在终端窗口中，确保你位于包含智能体文件夹的父目录 (例如 your-project-directory/) 中。
通过运行以下 ASP make 命令，将更新后的本地项目中的代码部署到 Google Cloud 开发环境：
```
make backend
```

一旦此过程成功完成，你应该能够与运行在 Google Cloud Agent Engine 上的智能体进行交互。有关测试已部署智能体的详细信息，请参阅测试已部署的智能体。

对你的 ADK 项目的更改¶

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

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

运行 ASP enhance 命令以添加 Agent Engine 部署信息后，新结构如下：

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

有关更多信息，请参阅更新后的 ADK 项目文件夹中的 README.md 文件。有关使用 Agent Starter Pack 的更多信息，请参阅开发指南。

测试已部署的智能体¶

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