使用 Agent Starter Pack 部署到 Agent Engine¶

Supported in ADKPython

此部署过程描述了如何使用 Agent Starter Pack (ASP) 和 ADK 命令行界面 (CLI) 工具执行部署。使用 ASP 部署到 Agent Engine 运行时是一种加速路径，你应该仅将其用于_开发和测试_。ASP 工具配置的 Google Cloud 资源并非运行 ADK 智能体工作流所严格必需的，在将其用于生产部署之前，你应该彻底审查该配置。

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

前置条件: 设置 Google Cloud 账户、项目并安装所需软件。
准备你的 ADK 项目: 修改你现有的 ADK 项目文件以准备部署。
连接到你的 Google Cloud 项目: 将你的开发环境连接到 Google Cloud 和你的 Google Cloud 项目。
部署你的 ADK 项目: 在你的 Google Cloud 项目中配置所需的服务并上传你的 ADK 项目代码。

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

前置条件¶

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

Google Cloud 账户: 具有以下管理员访问权限：
- Google Cloud 项目: 一个空的 Google Cloud 项目，并启用了计费。有关创建项目的信息，请参阅创建和管理项目。
Python 环境: ASP 项目支持的 Python 版本。
uv 工具： 管理 Python 开发环境并运行 ASP 工具。有关安装详细信息，请参阅安装 uv。
Google Cloud CLI 工具: gcloud 命令行界面。有关安装详细信息，请参阅 Google Cloud 命令行界面。
Make 工具: 构建自动化工具。此工具是大多数基于 Unix 的系统的一部分，有关安装详细信息，请参阅 Make 工具文档。

准备你的 ADK 项目¶

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

这些说明假设你有一个现有的 ADK 项目，你正在修改它以进行部署。如果你没有 ADK 项目，或想使用测试项目，请完成 Python 快速入门指南，该指南创建一个 multi_tool_agent 项目。以下说明使用 multi_tool_agent 项目作为示例。

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

在开发环境的终端窗口中，导航到包含你的智能体文件夹的父目录。例如，如果你的项目结构是：
```
your-project-directory/
├── multi_tool_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 项目作为参考示例。原始项目一开始具有以下文件结构：

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

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

multi-tool-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 中测试已部署的智能体。