部署到 Vertex AI Agent Engine¶

Supported in ADKPython

Agent Engine 是一个完全托管的 Google Cloud 服务，使开发者能够在生产环境中部署、管理和扩展 AI 智能体。Agent Engine 处理在生产环境中扩展智能体所需的基础设施，因此你可以专注于创建智能且有影响力的应用程序。本指南为希望快速部署 ADK 项目提供了加速部署指令集，以及为希望仔细管理将智能体部署到 Agent Engine 的标准、逐步指令集。

加速部署¶

本节介绍如何使用 Agent Starter Pack (ASP) 和 ADK 命令行界面 (CLI) 工具执行部署。此方法使用 ASP 工具将项目模板应用到现有项目中，添加部署工件，并准备你的智能体项目以进行部署。这些说明展示了如何使用 ASP 在 Google Cloud 项目中预配部署 ADK 项目所需的服务，如下所示：

先决条件：设置 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 环境: 3.9 到 3.13 之间的 Python 版本。
UV 工具： 管理 Python 开发环境和运行 ASP 工具。有关安装详情，请参阅安装 UV。
Google Cloud CLI 工具: gcloud 命令行界面。有关安装详情，请参阅 Google Cloud 命令行界面。
Make 工具: 构建自动化工具。此工具是大多数基于 Unix 的系统的一部分，有关安装详情，请参阅 Make 工具文档。
Terraform: 在 Google Cloud 上的基础设施和服务部署。有关安装详情，请参阅安装 Terraform。
Google Cloud 账户，具有管理员访问权限：
Google Cloud 项目: 启用了计费功能的空 Google Cloud 项目。有关创建项目的说明，请参阅创建和管理项目。
Python 环境: 3.9 到 3.13 之间的 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 上运行的智能体进行交互。有关测试已部署智能体的详细信息，请参阅下一节。

此过程成功完成后，你应该能够与在 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 的更多信息，请参阅开发指南。

标准部署¶

本节描述如何逐步部署到 Agent Engine。如果你希望仔细管理部署设置，或者正在修改现有的 Agent Engine 部署，则这些说明更为合适。

先决条件¶

这些说明假设你已经定义了一个 ADK 项目。如果你没有 ADK 项目，请参阅定义你的智能体中的说明以创建测试项目。

在开始部署过程之前，请确保你具备以下条件：

Google Cloud 项目：启用了 Vertex AI API 的 Google Cloud 项目。
已认证的 gcloud CLI：你需要通过 Google Cloud 进行身份验证。在终端中运行以下命令：
```
gcloud auth application-default login
```
Google Cloud Storage (GCS) 存储桶：Agent Engine 需要一个 GCS 存储桶来暂存你的智能体代码和依赖项以进行部署。如果你没有存储桶，请按照此处的说明创建一个。
Python 环境：Python 版本在 3.9 到 3.13 之间。
安装 Vertex AI SDK

Agent Engine 是 Python 的 Vertex AI SDK 的一部分。有关更多信息，你可以查看 Agent Engine 快速开始文档。
```
pip install google-cloud-aiplatform[adk,agent_engines]>=1.111
```

定义你的智能体¶

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

初始化 Vertex AI¶

接下来，初始化 Vertex AI SDK。这会告诉 SDK 使用哪个 Google Cloud 项目和区域，以及在哪里暂存文件以进行部署。

对于 IDE 用户

你可以将此初始化代码放在单独的 deploy.py 脚本中，与以下步骤 3 到 6 的部署逻辑一起。

deploy.py

import vertexai
from agent import root_agent # 如果你的智能体不在 agent.py 中，请修改此处

# TODO: 为你的项目填写这些值
PROJECT_ID = "your-gcp-project-id"
LOCATION = "us-central1"  # 其他可选区域见 https://cloud.google.com/vertex-ai/generative-ai/docs/agent-engine/overview#supported-regions
STAGING_BUCKET = "gs://your-gcs-bucket-name"

# 初始化 Vertex AI SDK
vertexai.init(
    project=PROJECT_ID,
    location=LOCATION,
    staging_bucket=STAGING_BUCKET,
)

为部署准备智能体¶

要使你的智能体与 Agent Engine 兼容，你需要将其包装在 AdkApp 对象中。

deploy.py

from vertexai import agent_engines

# 将智能体包装在 AdkApp 对象中
app = agent_engines.AdkApp(
    agent=root_agent,
    enable_tracing=True,
)

Info

当 AdkApp 被部署到 Agent Engine 时，会自动使用 VertexAiSessionService 作为持久化、托管的会话状态服务。这为多轮对话记忆提供了支持，无需额外配置。本地测试时，应用默认使用临时的内存会话服务。

在本地测试智能体（可选）¶

在部署之前，你可以在本地测试智能体的行为。

async_stream_query 方法返回表示智能体执行跟踪的事件流。

deploy.py

# 创建本地会话以维护对话历史
session = await app.async_create_session(user_id="u_123")
print(session)

create_session（本地）的预期输出：

Session(id='c6a33dae-26ef-410c-9135-b434a528291f', app_name='default-app-name', user_id='u_123', state={}, events=[], last_update_time=1743440392.8689594)

向智能体发送查询。将以下代码复制粘贴到你的 "deploy.py" Python 脚本或笔记本中。

deploy.py

events = []
async for event in app.async_stream_query(
    user_id="u_123",
    session_id=session.id,
    message="whats the weather in new york",
):
    events.append(event)

# 完整的事件流展示了智能体的思考过程
print("--- Full Event Stream ---")
for event in events:
    print(event)

# 进行快速测试时，你可以只提取最终的文本响应
final_text_responses = [
    e for e in events
    if e.get("content", {}).get("parts", [{}])[0].get("text")
    and not e.get("content", {}).get("parts", [{}])[0].get("function_call")
]
if final_text_responses:
    print("\n--- Final Response ---")
    print(final_text_responses[0]["content"]["parts"][0]["text"])

了解输出¶

当你运行上述代码时，你会看到几种类型的事件：

工具调用事件：模型请求调用工具（例如，get_weather）。
工具响应事件：系统将工具调用的结果提供给模型。
模型响应事件：智能体处理工具结果后的最终文本响应。

async_stream_query（本地）的预期输出：

{'parts': [{'function_call': {'id': 'af-a33fedb0-29e6-4d0c-9eb3-00c402969395', 'args': {'city': 'new york'}, 'name': 'get_weather'}}], 'role': 'model'}
{'parts': [{'function_response': {'id': 'af-a33fedb0-29e6-4d0c-9eb3-00c402969395', 'name': 'get_weather', 'response': {'status': 'success', 'report': '纽约的天气是晴天，温度为 25 摄氏度 (41 华氏度)。'}}}], 'role': 'user'}
{'parts': [{'text': '纽约的天气是晴天，温度为 25 摄氏度 (41 华氏度)。'}], 'role': 'model'}

部署到 Agent Engine¶

一旦你对智能体的本地行为满意，你就可以部署它。你可以使用 Python SDK 或 adk 命令行工具来执行此操作。

此过程会将你的代码打包，构建到容器中，并将其部署到托管的 Agent Engine 服务。此过程可能需要几分钟。

ADK CLIPython

你可以使用 adk deploy 命令行工具从终端进行部署。以下示例部署命令使用 multi_tool_agent 示例代码作为要部署的项目：

adk deploy agent_engine \
    --project=my-cloud-project-xxxxx \
    --region=us-central1 \
    --staging_bucket=gs://my-cloud-project-staging-bucket-name \
    --display_name="My Agent Name" \
    /multi_tool_agent

在 Google Cloud Console 的 Cloud Storage Bucket 部分中查找可用存储桶的名称。有关使用 adk deploy 命令的更多详细信息，请参阅 ADK CLI 参考。

Tip

确保你的主 ADK 智能体定义 (root_agent) 在部署 ADK 项目时是可发现的。

此代码块从 Python 脚本或笔记本启动部署。

deploy.py

from vertexai import agent_engines

remote_app = agent_engines.create(
    agent_engine=app,
    requirements=[
        "google-cloud-aiplatform[adk,agent_engines]"
    ]
)

print(f"Deployment finished!")
print(f"Resource Name: {remote_app.resource_name}")
# 资源名称: "projects/{PROJECT_NUMBER}/locations/{LOCATION}/reasoningEngines/$(RESOURCE_ID)"
#       注意: PROJECT_NUMBER 与 PROJECT_ID 不同。

监控和验证¶

你可以在 Google Cloud Console 的 Agent Engine UI 中监控部署状态。
remote_app.resource_name 是已部署智能体的唯一标识符。你需要它来与智能体交互。你也可以从 ADK CLI 命令返回的响应中获取此信息。
有关更多详细信息，你可以访问 Agent Engine 文档部署智能体和管理已部署的智能体。

测试已部署的智能体¶

将智能体部署到 Agent Engine 后，你可以通过 Google Cloud Console 查看已部署的智能体，并使用 REST 调用或 Python 的 Vertex AI SDK 与智能体进行交互。

在 Cloud Console 中查看已部署的智能体：

导航到 Google Cloud Console 中的 Agent Engine 页面： https://console.cloud.google.com/vertex-ai/agents/agent-engines

此页面列出了当前选定的 Google Cloud 项目中的所有已部署智能体。如果你没有看到你的智能体列出，请确保你在 Google Cloud Console 中选择了你的目标项目。有关选择现有 Google Cloud 项目的更多信息，请参阅创建和管理项目。

查找 Google Cloud 项目信息¶

你需要项目的地址和资源标识 (PROJECT_ID, LOCATION, RESOURCE_ID) 才能测试你的部署。你可以使用 Cloud Console 或 gcloud 命令行工具查找此信息。

使用 Google Cloud Console 查找项目信息：

在 Google Cloud Console 中，导航到 Agent Engine 页面： https://console.cloud.google.com/vertex-ai/agents/agent-engines

在页面顶部，选择 API URLs，然后复制已部署智能体的 Query URL 字符串，其格式应如下：

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

使用 gcloud 查找项目信息：

在你的开发环境中，确保你已通过 Google Cloud 进行身份验证，然后运行以下命令列出你的项目：
```
gcloud projects list
```

获取用于部署的项目 ID，然后运行此命令以获取其他详细信息：

gcloud asset search-all-resources \
    --scope=projects/$(PROJECT_ID) \
    --asset-types='aiplatform.googleapis.com/ReasoningEngine' \
    --format="table(name,assetType,location,reasoning_engine_id)"

使用 REST 调用进行测试¶

与 Agent Engine 中已部署的智能体交互的一种简单方法是使用 curl 工具进行 REST 调用。本节介绍如何检查与智能体的连接，以及如何测试已部署智能体对请求的处理。

检查与智能体的连接¶

你可以使用 Cloud Console 的 Agent Engine 部分中的 Query URL 来检查与正在运行的智能体的连接。此检查不会执行已部署的智能体，但会返回有关智能体的信息。

发送 REST 调用以从已部署的智能体获取响应：

在开发环境的终端窗口中，构建请求并执行它：

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://$(LOCATION)-aiplatform.googleapis.com/v1/projects/$(PROJECT_ID)/locations/$(LOCATION)/reasoningEngines"

如果部署成功，此请求将响应有效的请求列表和预期的数据格式。

智能体连接的访问权限

此连接测试要求调用用户具有已部署智能体的有效访问令牌。从其他环境进行测试时，请确保调用用户有权连接到 Google Cloud 项目中的智能体。

发送智能体请求¶

从智能体项目获取响应时，必须首先创建一个会话，接收会话 ID，然后使用该会话 ID 发送请求。此过程在以下说明中进行了描述。

通过 REST 测试与已部署智能体的交互：

在开发环境的终端窗口中，使用此模板构建请求来创建会话：

curl \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    https://$(LOCATION)-aiplatform.googleapis.com/v1/projects/$(PROJECT_ID)/locations/$(LOCATION)/reasoningEngines/$(RESOURCE_ID):query \
    -d '{"class_method": "async_create_session", "input": {"user_id": "u_123"},}'

在上一个命令的响应中，从 id 字段提取创建的 会话 ID：

{
    "output": {
        "userId": "u_123",
        "lastUpdateTime": 1757690426.337745,
        "state": {},
        "id": "4857885913439920384", # Session ID
        "appName": "9888888855577777776",
        "events": []
    }
}

在开发环境的终端窗口中，使用此模板和上一步中创建的会话 ID 构建请求，向你的智能体发送消息：

curl \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://$(LOCATION)-aiplatform.googleapis.com/v1/projects/$(PROJECT_ID)/locations/$(LOCATION)/reasoningEngines/$(RESOURCE_ID):streamQuery?alt=sse -d '{
"class_method": "async_stream_query",
"input": {
    "user_id": "u_123",
    "session_id": "4857885913439920384",
    "message": "嘿，纽约今天天气怎么样？",
}
}'

此请求应以 JSON 格式生成来自已部署智能体代码的响应。有关使用 REST 调用与 Agent Engine 中部署的 ADK 智能体交互的更多信息，请参阅 Agent Engine 文档中的管理已部署的智能体和使用 Agent Development Kit 智能体。

使用 Python 进行测试¶

你可以使用 Python 代码对部署在 Agent Engine 中的智能体进行更复杂和可重复的测试。这些说明描述了如何创建与已部署智能体的会话，然后向智能体发送请求以进行处理。

创建远程会话¶

使用 remote_app 对象创建与已部署远程智能体的连接：

# 如果你在一个新的脚本中，或是使用 ADK CLI 完成部署，你可以这样连接：
# remote_app = agent_engines.get("your-agent-resource-name")
remote_session = await remote_app.async_create_session(user_id="u_456")
print(remote_session)

create_session（远程）的预期输出：

{'events': [],
'user_id': 'u_456',
'state': {},
'id': '7543472750996750336',
'app_name': '7917477678498709504',
'last_update_time': 1743683353.030133}

id 值是会话 ID，app_name 是在 Agent Engine 上部署的智能体的资源 ID。

向远程智能体发送查询¶

async for event in remote_app.async_stream_query(
    user_id="u_456",
    session_id=remote_session["id"],
    message="whats the weather in new york",
):
    print(event)

async_stream_query（远程）的预期输出：

{'parts': [{'function_call': {'id': 'af-f1906423-a531-4ecf-a1ef-723b05e85321', 'args': {'city': 'new york'}, 'name': 'get_weather'}}], 'role': 'model'}
{'parts': [{'function_response': {'id': 'af-f1906423-a531-4ecf-a1ef-723b05e85321', 'name': 'get_weather', 'response': {'status': 'success', 'report': '纽约的天气是晴天，温度为 25 摄氏度 (41 华氏度)。'}}}], 'role': 'user'}
{'parts': [{'text': '纽约的天气是晴天，温度为 25 摄氏度 (41 华氏度)。'}], 'role': 'model'}

有关与部署在 Agent Engine 中的 ADK 智能体进行交互的更多信息，请参阅 Agent Engine 文档中的管理已部署的智能体和使用 Agent Development Kit 智能体。

发送多模态查询¶

要向你的智能体发送多模态查询（例如，包含图像），你可以使用 types.Part 对象列表构造 async_stream_query 的 message 参数。每个部分可以是文本或图像。

要包含图像，你可以使用 types.Part.from_uri，为图像提供 Google Cloud Storage (GCS) URI。

from google.genai import types

image_part = types.Part.from_uri(
    file_uri="gs://cloud-samples-data/generative-ai/image/scones.jpg",
    mime_type="image/jpeg",
)
text_part = types.Part.from_text(
    text="这张图片中有什么？",
)

async for event in remote_app.async_stream_query(
    user_id="u_456",
    session_id=remote_session["id"],
    message=[text_part, image_part],
):
    print(event)

Note

虽然与模型的底层通信可能涉及图像的 Base64 编码，但向部署在 Agent Engine 上的智能体发送图像数据的推荐和支持方法是提供 GCS URI。

部署负载¶

将 ADK 智能体项目部署到 Agent Engine 时，以下内容将上传到服务：

你的 ADK 智能体代码
在 ADK 智能体代码中声明的任何依赖项

部署不包括 ADK API 服务器或 ADK Web 用户界面库。Agent Engine 服务提供 ADK API 服务器功能所需的库。

清理部署¶

如果你进行了测试部署，最好在完成后清理你的云资源。你可以删除已部署的 Agent Engine 实例，以避免在 Google Cloud 账户上产生任何意外费用。

remote_app.delete(force=True)

force=True 参数还会删除从已部署智能体生成的任何子资源，例如会话。你也可以通过 Google Cloud 上的 Agent Engine UI 删除已部署的智能体。