部署到 Vertex AI Agent Engine

Supported in ADKPython

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

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

• 设置 Google Cloud 项目
• 准备智能体项目文件夹
• 部署智能体

设置 Google Cloud 项目

要将你的智能体部署到 Agent Engine，你需要一个 Google Cloud 项目：

1. 登录 Google Cloud：

   • 如果你是 Google Cloud 的现有用户：
     • 通过 https://console.cloud.google.com 登录
     • 如果你之前使用的免费试用已过期，你可能需要升级到 付费计费账户。
   • 如果你是 Google Cloud 的新用户：
     • 你可以注册免费试用计划。 免费试用为你提供 300 美元的欢迎积分，可在 91 天内用于各种 Google Cloud 产品，并且不会向你收费。在免费试用期间，你还可以访问 Google Cloud 免费层，它为你提供选定产品的免费使用，最高可达指定的月度限制，以及产品特定的免费试用。

2. 创建 Google Cloud 项目

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

3. 获取你的 Google Cloud 项目 ID

   • 你需要你的 Google Cloud 项目 ID，可以在你的 GCP 主页上找到它。确保记下项目 ID（带连字符的字母数字），_而不是_项目编号（数字）。

   

4. 在你的项目中启用 Vertex AI

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

5. 在你的项目中启用 Cloud Resource Manager API

   • 要使用 Agent Engine，你需要启用 Cloud Resource Manager API。点击"启用"按钮以启用 API。启用后，它应该显示"API 已启用"。

6. 创建 Google Cloud Storage (GCS) 存储桶：

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

不使用 GCS 存储桶进行部署

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

设置你的编码环境

现在你已经准备好了 Google Cloud 项目，可以返回到你的编码环境。 这些步骤需要访问编码环境中的终端以运行命令行指令。

使用 Google Cloud 验证你的编码环境

• 你需要验证你的编码环境，以便你和你的代码可以与 Google Cloud 交互。 为此，你需要 gcloud CLI。如果你从未使用过 gcloud CLI，你需要先下载并安装它，然后再继续执行以下步骤：

• 在终端中运行以下命令以作为用户访问你的 Google Cloud 项目：

  gcloud auth login
  

  验证后，你应该看到消息 You are now authenticated with the gcloud CLI!。

• 运行以下命令以验证你的代码，以便它可以与 Google Cloud 一起使用：

  gcloud auth application-default login
  

  验证后，你应该看到消息 You are now authenticated with the gcloud CLI!。

• (可选) 如果你需要在 gcloud 中设置或更改默认项目，可以使用：

  gcloud config set project MY-PROJECT-ID
  

定义你的智能体

准备好 Google Cloud 和编码环境后，你就可以部署智能体了。这些说明假设你有一个智能体项目文件夹，例如：

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

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

部署智能体

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

以下示例部署命令使用 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

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

部署命令输出

成功部署后，你应该看到以下输出：

Creating AgentEngine
Create 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 the temp folder: /var/folders/k5/pv70z5m92s30k0n7hfkxszfr00mz24/T/agent_engine_deploy_src/20251219_134245

请注意，你现在有一个 RESOURCE_ID，你的智能体已部署到该 ID（在上面的示例中是 751619551677906944）。你需要此 ID 号以及其他值才能在 Agent Engine 上使用你的智能体。

在 Agent Engine 上使用智能体

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

要在 Agent Engine 上与你的智能体交互，你需要以下内容：

• PROJECT_ID（示例："my-project-id"），你可以在项目详细信息页面上找到它
• LOCATION_ID（示例："us-central1"），你用于部署智能体的位置
• RESOURCE_ID（示例："751619551677906944"），你可以在 Agent Engine UI 上找到它

查询 URL 结构如下：

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

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

监控和验证

• 你可以在 Google Cloud Console 的 Agent Engine UI 中监控部署状态。
• 有关其他详细信息，你可以访问 Agent Engine 文档的部署智能体和管理已部署的智能体。

测试已部署的智能体

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