Skip to content

Deploy to Agent Engine with Agent Starter Pack

使用 Agent Starter Pack 部署到 Agent Engine

Supported in ADKPython

This deployment procedure describes how to perform a deployment using the Agent Starter Pack (ASP) and ADK command line interface (CLI) tool. Using ASP for deployment to the Agent Engine runtime is an accelerated path, and you should use it for development and testing only. The ASP tool configures Google Cloud resources that are not strictly necessary for running an ADK agent workflow, and you should thoroughly review that configuration before using it in a production deployment.

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

This deployment guide uses ASP tool to apply a project template to your existing project, add deployment artifacts, and prepare your agent project for deployment. These instructions show you how to use ASP to provision a Google Cloud project with services needed for deploying your ADK project, as follows:

此部署指南使用 ASP 工具将项目模板应用于您的现有项目,添加部署构件,并准备您的智能体项目进行部署。这些说明向您展示如何使用 ASP 配置部署您的 ADK 项目所需的 Google Cloud 项目的服务,如下所示:

For information on testing a deployed agent, see Test deployed agent. For more information on using Agent Starter Pack and its command line tools, see the CLI reference and Development guide.

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

Prerequisites

先决条件

You need to following resources configured to use this deployment path:

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

  • Google Cloud account: with administrator access to the following:
  • Python Environment: A Python version supported by the ASP project.
    • Python 环境: 一个 ASP 项目支持的 Python 版本。
  • uv Tool: Manage Python development environment and running ASP tools. For installation details, see Install uv.
    • uv 工具: 管理 Python 开发环境并运行 ASP 工具。有关安装详细信息,请参阅安装 uv。
  • Google Cloud CLI tool: The gcloud command line interface. For installation details, see Google Cloud Command Line Interface.
  • Make tool: Build automation tool. This tool is part of most Unix-based systems, for installation details, see the Make tool documentation.
    • Make 工具: 构建自动化工具。此工具是大多数基于 Unix 的系统的一部分,有关安装详细信息,请参阅 Make 工具 文档。

Prepare your ADK project

准备您的 ADK 项目

When you deploy an ADK project to Agent Engine, you need some additional files to support the deployment operation. The following ASP command backs up your project and then adds files to your project for deployment purposes.

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

These instructions assume you have an existing ADK project that you are modifying for deployment. If you do not have an ADK project, or want to use a test project, complete the Python Quickstart guide, which creates a multi_tool_agent project. The following instructions use the multi_tool_agent project as an example.

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

To prepare your ADK project for deployment to Agent Engine:

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

  1. In a terminal window of your development environment, navigate to the parent directory that contains your agent folder. For example, if your project structure is:

    1. 在开发环境的终端窗口中,导航到包含智能体文件夹的父目录。例如,如果您的项目结构是:
    your-project-directory/
├── multi_tool_agent/
│   ├── __init__.py
│   ├── agent.py
│   └── .env

    Navigate to your-project-directory/

    导航到 your-project-directory/

  2. Run ASP enhance command to add files required for deployment into your project.

    1. 运行 ASP enhance 命令,将部署所需的文件添加到您的项目中。
    uvx agent-starter-pack enhance --adk -d agent_engine

  3. Follow instructions from the ASP tool. In general, you can accept the default answers to all questions. However for the GCP region, option, make sure you select one of the supported regions for Agent Engine.

    1. 按照 ASP 工具的说明操作。通常,您可以接受所有问题的默认答案。但是,对于 GCP 区域选项,请确保您为 Agent Engine 选择一个支持的区域。

When you successfully complete this process, the tool shows the following message:

当您成功完成此过程时,工具会显示以下消息:

> Success! Your agent project is ready.

Note

The ASP tool may show a reminder to connect to Google Cloud while running, but that connection is not required at this stage.

注意

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

For more information about the changes ASP makes to your ADK project, see Changes to your ADK project.

有关 ASP 对您的 ADK 项目所做的更改的更多信息,请参阅对您的 ADK 项目的更改。

Connect to your Google Cloud project

连接到您的 Google Cloud 项目

Before you deploy your ADK project, you must connect to Google Cloud and your project. After logging into your Google Cloud account, you should verify that your deployment target project is visible from your account and that it is configured as your current project.

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

To connect to Google Cloud and list your project:

要连接到 Google Cloud 并列出您的项目:

  1. In a terminal window of your development environment, login to your Google Cloud account:

    1. 在开发环境的终端窗口中,登录到您的 Google Cloud 账户:
    gcloud auth application-default login

  2. Set your target project using the Google Cloud Project ID:

    1. 使用 Google Cloud 项目 ID 设置您的目标项目:
    gcloud config set project your-project-id-xxxxx

  3. Verify your Google Cloud target project is set:

    1. 验证您的 Google Cloud 目标项目是否已设置:
    gcloud config get-value project

Once you have successfully connected to Google Cloud and set your Cloud Project ID, you are ready to deploy your ADK project files to Agent Engine.

一旦您成功连接到 Google Cloud 并设置了您的 Cloud 项目 ID,您就可以将您的 ADK 项目文件部署到 Agent Engine。

Deploy your ADK project

部署您的 ADK 项目

When using the ASP tool, you deploy in stages. In the first stage, you run a make command that provisions the services needed to run your ADK workflow on Agent Engine. In the second stage, the tool uploads your project code to the Agent Engine service and runs it in the hosted environment.

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

Important

Make sure your Google Cloud target deployment project is set as your current project before performing these steps. The make backend command uses your currently set Google Cloud project when it performs a deployment. For information on setting and checking your current project, see Connect to your Google Cloud project.

重要

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

To deploy your ADK project to Agent Engine in your Google Cloud project:

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

  1. In a terminal window, ensure you are in the parent directory (e.g., your-project-directory/) that contains your agent folder.

    1. 在终端窗口中,确保您在包含智能体文件夹的父目录(例如,your-project-directory/)中。

  2. Deploy code from the updated local project into the Google Cloud development environment, by running the following ASP make command:

    1. 通过运行以下 ASP make 命令,将更新后的本地项目中的代码部署到 Google Cloud 开发环境中:
    make backend

Once this process completes successfully, you should be able to interact with the agent running on Google Cloud Agent Engine. For details on testing the deployed agent, see Test deployed agent.

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

Changes to your ADK project

对您的 ADK 项目的更改

The ASP tools add more files to your project for deployment. The procedure below backs up your existing project files before modifying them. This guide uses the multi_tool_agent project as a reference example. The original project has the following file structure to start with:

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

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

After running the ASP enhance command to add Agent Engine deployment information, the new structure is as follows:

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

multi-tool-agent/
├─ app/                 # Core application code
│   ├─ agent.py         # Main agent logic
│   ├─ agent_engine_app.py # Agent Engine 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 Agent Starter Pack, see the Development guide.

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

Test deployed agents

测试已部署的智能体

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 Engine, see Test deployed agents in Agent Engine.

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