部署到 Agent Runtime¶

Supported in ADKPython

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

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

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

设置 Google Cloud 项目¶

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

登录 Google Cloud：
- 如果你是 Google Cloud 的现有用户：
  - 通过 https://console.cloud.google.com 登录
  - 如果你之前使用的免费试用已过期，你可能需要升级到付费计费账户。
- 如果你是 Google Cloud 的新用户：
  - 你可以注册免费试用计划。免费试用为你提供 300 美元的欢迎积分，可在 91 天内用于各种 Google Cloud 产品，并且不会向你收费。在免费试用期间，你还可以访问 Google Cloud 免费层，它为你提供选定产品的免费使用，最高可达指定的月度限制，以及产品特定的免费试用。
创建 Google Cloud 项目
- 如果你已经有现有的 Google Cloud 项目，可以使用它，但请注意，此过程可能会向项目添加新服务。
- 如果你想创建新的 Google Cloud 项目，可以在创建项目页面上创建一个新项目。
获取你的 Google Cloud 项目 ID
- 你需要你的 Google Cloud 项目 ID，可以在你的 GCP 主页上找到它。确保记下项目 ID（带连字符的字母数字），_而不是_项目编号（数字）。
在你的项目中启用 Agent Platform
- 要使用 Agent Runtime，你需要启用 Agent Platform API。点击"启用"按钮启用 API。启用后，应显示"API 已启用"。
在你的项目中启用 Cloud Resource Manager API
- 要使用 Agent Runtime，你需要启用 Cloud Resource Manager API。点击"启用"按钮启用 API。启用后，应显示"API 已启用"。

设置你的编码环境¶

现在你已经准备好了 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 Runtime 服务。这个过程可能需要几分钟。

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

PROJECT_ID=my-project-id
LOCATION_ID=us-central1

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

有关 region，你可以在 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（上例中为 751619551677906944）。要将你的智能体用于 Agent Runtime，你需要此 ID 号以及其他值。

在 Agent Runtime 上使用智能体¶

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

要与 Agent Runtime 上的智能体进行交互，你需要以下信息：

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

查询 URL 结构如下：

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

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

监控和验证¶

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

测试已部署的智能体¶

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