Skip to content

Deploy to Vertex AI Agent Engine

部署到 Vertex AI Agent Engine

Supported in ADKPython

This deployment procedure describes how to perform a standard deployment of ADK agent code to Google Cloud Agent Engine. You should follow this deployment path if you have an existing Google Cloud project and if you want to carefully manage deploying an ADK agent to Agent Engine runtime environment. These instructions use Cloud Console, gcloud command line interface, and ADK command line interface (ADK CLI). This path is recommended for users who are already familiar with configuring Google Cloud projects, and users preparing for production deployments.

此部署过程描述了如何将 ADK 智能体代码标准部署到 Google Cloud Agent Engine。如果您有现有的 Google Cloud 项目,并且想要仔细管理将 ADK 智能体部署到 Agent Engine 运行时环境,则应遵循此部署路径。这些说明使用 Cloud Console、gcloud 命令行界面和 ADK 命令行界面 (ADK CLI)。此路径适用于已经熟悉配置 Google Cloud 项目的用户,以及准备进行生产部署的用户。

These instructions describe how to deploy an ADK project to Google Cloud Agent Engine runtime environment, which includes the following stages:

这些说明描述了如何将 ADK 项目部署到 Google Cloud Agent Engine 运行时环境,其中包括以下阶段:

Setup Google Cloud project

设置 Google Cloud 项目

To deploy your agent to Agent Engine, you need a Google Cloud project:

要将智能体部署到 Agent Engine,您需要一个 Google Cloud 项目:

  1. Sign into Google Cloud:

    • If you're an existing user of Google Cloud:

    • If you are a new user of Google Cloud:

      • You can sign up for the Free Trial program. The Free Trial gets you a $300 Welcome credit to spend over 91 days on various Google Cloud products and you won't be billed. During the Free Trial, you also get access to the Google Cloud Free Tier, which gives you free usage of select products up to specified monthly limits, and to product-specific free trials.

    • 登录到 Google Cloud:

      • 如果您是 Google Cloud 的现有用户:
      • 如果您是 Google Cloud 的新用户:
        • 您可以注册免费试用计划。 免费试用为您提供 $300 的欢迎额度,可在 91 天内用于各种 Google Cloud 产品,您不会被计费。在免费试用期间,您还可以访问 Google Cloud 免费版,该版本为您提供指定月度限额内的选定产品的免费使用,以及特定产品的免费试用。

  2. Create a Google Cloud project

    • If you already have an existing Google Cloud project, you can use it, but be aware this process is likely to add new services to the project.

    • If you want to create a new Google Cloud project, you can create a new one on the Create Project page.

    • 创建 Google Cloud 项目

      • 如果您已经有现有的 Google Cloud 项目,您可以使用它,但请注意此过程可能会向项目添加新服务。
      • 如果您想创建新的 Google Cloud 项目,可以在 创建项目 页面上创建一个新的。

  3. Get your Google Cloud Project ID

    • You need your Google Cloud Project ID, which you can find on your GCP homepage. Make sure to note the Project ID (alphanumeric with hyphens), not the project number (numeric).

    • 获取您的 Google Cloud 项目 ID

      • 您需要您的 Google Cloud 项目 ID,可以在您的 GCP 主页上找到。确保记下项目 ID (带连字符的字母数字),_而不是_项目编号(数字)。

    Google Cloud Project ID

  4. Enable Vertex AI in your project

    • To use Agent Engine, you need to enable the Vertex AI API. Click on the "Enable" button to enable the API. Once enabled, it should say "API Enabled".

    • 在您的项目中启用 Vertex AI

      • 要使用 Agent Engine,您需要启用 Vertex AI API。单击"启用"按钮以启用 API。启用后,它应该显示"API 已启用"。

  5. Enable Cloud Resource Manager API in your project

    • To use Agent Engine, you need to enable the Cloud Resource Manager API. Click on the "Enable" button to enable the API. Once enabled, it should say "API Enabled".

    • 在您的项目中启用 Cloud Resource Manager API

  6. Create a Google Cloud Storage (GCS) Bucket:

    • Agent Engine requires a GCS bucket to stage your agent's code and dependencies for deployment. If you already have a GCS bucket, you should create a new one specifically for deployment use.
    • Create a GCS bucket by following the instructions. You should start with the default settings when creating your first bucket.
    • Once you have created a storage bucket, you should be able to see it on the Cloud Storage Buckets page.

    • You need the GCS bucket path to set as your staging bucket. For example, if your GCS bucket name is "my-bucket", then your bucket path should be "gs://my-bucket".

    • 创建 Google Cloud Storage (GCS) Bucket:

      • Agent Engine 需要 GCS bucket 来暂存您的智能体代码和依赖项以进行部署。如果您已经有 GCS bucket,应该创建一个新的专门用于部署。
      • 按照说明创建 GCS bucket。在创建第一个 bucket 时应该使用默认设置。
      • 创建存储 bucket 后,您应该能够在 Cloud Storage Buckets 页面上看到它。
      • 您需要将 GCS bucket 路径设置为您的暂存 bucket。例如,如果您的 GCS bucket 名称是"my-bucket",则您的 bucket 路径应该是"gs://my-bucket"。
Deploy without a GCS bucket

You can avoid using a Google Cloud Storage bucket for deployment using a different configuration method. For details on this method, see Deploy an Agent in the Agent Engine documentation.

不使用 GCS bucket 部署

您可以使用不同的配置方法避免使用 Google Cloud Storage bucket 进行部署。有关此方法的详细信息,请参阅 Agent Engine 文档中的部署智能体。

Set up your coding environment

设置您的编码环境

Now that you have prepared your Google Cloud project, you can return to your coding environment. These steps require access to a terminal within your coding environment to run command line instructions.

既然您已经准备好了 Google Cloud 项目,可以返回到您的编码环境。这些步骤需要访问编码环境中的终端以运行命令行说明。

Authenticate your coding environment with Google Cloud

使用 Google Cloud 对您的编码环境进行身份验证

  • You need to authenticate your coding environment so that you and your code can interact with Google Cloud. To do so, you need the gcloud CLI. If you have never used the gcloud CLI, you need to first download and install it before continuing with the steps below:

    • 您需要验证您的编码环境,以便您和您的代码可以与 Google Cloud 交互。为此,您需要 gcloud CLI。如果您从未使用过 gcloud CLI,需要在继续以下步骤之前先下载并安装它:

  • Run the following command in your terminal to access your Google Cloud project as a user:

    • 在终端中运行以下命令以用户身份访问您的 Google Cloud 项目:
    gcloud auth login

    After authenticating, you should see the message You are now authenticated with the gcloud CLI!.

    身份验证后,您应该看到消息您现在已通过 gcloud CLI 进行身份验证!。

  • Run the following command to authenticate your code so that it can work with Google Cloud:

    • 运行以下命令以验证您的代码,使其可以与 Google Cloud 一起工作:
    gcloud auth application-default login

    After authenticating, you should see the message You are now authenticated with the gcloud CLI!.

    身份验证后,您应该看到消息您现在已通过 gcloud CLI 进行身份验证!。

  • (Optional) If you need to set or change your default project in gcloud, you can use:

    • (可选)如果您需要在 gcloud 中设置或更改默认项目,可以使用:
    gcloud config set project MY-PROJECT-ID

Define your agent

定义您的智能体

With your Google Cloud and coding environment prepared, you're ready to deploy your agent. The instructions assume that you have an agent project folder, such as:

既然您的 Google Cloud 和编码环境已准备就绪,您就可以部署您的智能体了。这些说明假设您有一个智能体项目文件夹,例如:

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

For more details on project files and format, see the multi_tool_agent code sample.

有关项目文件和格式的更多详细信息,请参阅 multi_tool_agent 代码示例。

Deploy agent

部署智能体

You can deploy from your terminal using the adk deploy command line tool. This process packages your code, builds it into a container, and deploys it to the managed Agent Engine service. This process can take several minutes.

您可以使用 adk deploy 命令行工具从终端进行部署。此过程打包您的代码,将其构建到容器中,并将其部署到托管的 Agent Engine 服务。此过程可能需要几分钟时间。

The following example deploy command uses the multi_tool_agent sample code as the project to be deployed:

以下示例部署命令使用 multi_tool_agent 示例代码作为要部署的项目:

PROJECT_ID=my-project-id
LOCATION_ID=us-central1
GCS_BUCKET=gs://MY-CLOUD-STORAGE-BUCKET

adk deploy agent_engine \
        --project=$PROJECT_ID \
        --region=$LOCATION_ID \
        --staging_bucket=$GCS_BUCKET \
        --display_name="My First Agent" \
        multi_tool_agent

For region, you can find a list of supported regions on the Vertex AI Agent Builder locations page. To learn about the CLI options for the adk deploy agent_engine command, see the ADK CLI Reference.

对于 region,您可以在 Vertex AI Agent Builder 位置页面上找到支持的区域列表。要了解 adk deploy agent_engine 命令的 CLI 选项,请参阅 ADK CLI 参考。

Deploy command output

部署命令输出

Once successfully deployed, you should see the following output:

成功部署后,您应该看到以下输出:

Creating AgentEngine
Creating AgentEngine backing LRO: projects/123456789/locations/us-central1/reasoningEngines/751619551677906944/operations/2356952072064073728
View progress and logs at https://console.cloud.google.com/logs/query?project=hopeful-sunset-478017-q0
AgentEngine created. Resource name: projects/123456789/locations/us-central1/reasoningEngines/751619551677906944
To use this AgentEngine in another session:
agent_engine = vertexai.agent_engines.get('projects/123456789/locations/us-central1/reasoningEngines/751619551677906944')
Cleaning up temp folder: /var/folders/k5/pv70z5m92s30k0n7hfkxszfr00mz24/T/agent_engine_deploy_src/20251219_134245

Note that you now have a RESOURCE_ID where your agent has been deployed (which in the example above is 751619551677906944). You need this ID number along with other values to use your agent on Agent Engine.

请注意,您现在拥有一个 RESOURCE_ID,您的智能体已部署到该位置(在上面的示例中为751619551677906944)。您需要此 ID 号码以及其他值才能在 Agent Engine 上使用您的智能体。

Using an agent on Agent Engine

在 Agent Engine 上使用智能体

Once you have completed deployment of your ADK project, you can query the agent using the Vertex AI SDK, Python requests library, or a REST API client. This section provides some information on what you need to interact with your agent and how to construct URLs to interact with your agent's REST API.

完成您的 ADK 项目部署后,您可以使用 Vertex AI SDK、Python requests 库或 REST API 客户端查询智能体。本节提供了一些关于您需要什么来与智能体交互以及如何构建 URL 以与智能体的 REST API 交互的信息。

To interact with your agent on Agent Engine, you need the following:

要与 Agent Engine 上的智能体交互,您需要以下信息:

  • PROJECT_ID (example: "my-project-id") which you can find on your project details page
  • LOCATION_ID (example: "us-central1"), that you used to deploy your agent
    • LOCATION_ID(例如:"us-central1"),您用来部署智能体的
  • RESOURCE_ID (example: "751619551677906944"), which you can find on the Agent Engine UI
    • RESOURCE_ID(例如:"751619551677906944"),可以在Agent Engine UI上找到

The query URL structure is as follows:

查询 URL 结构如下:

https://$(LOCATION_ID)-aiplatform.googleapis.com/v1/projects/$(PROJECT_ID)/locations/$(LOCATION_ID)/reasoningEngines/$(RESOURCE_ID):query

You can make requests to your agent using this URL structure. For more information on how to make requests, see the instructions in the Agent Engine documentation Use an Agent Development Kit agent. You can also check the Agent Engine documentation to learn about how to manage your deployed agent. For more information on testing and interacting with a deployed agent, see Test deployed agents in Agent Engine.

您可以使用此 URL 结构向您的智能体发出请求。有关如何发出请求的更多信息,请参阅 Agent Engine 文档中的使用 Agent Development Kit 智能体的说明。您还可以查看 Agent Engine 文档以了解如何管理已部署的智能体。有关测试和与已部署的智能体交互的更多信息,请参阅在 Agent Engine 中测试已部署的智能体。

Monitoring and verification

监控和验证

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