在 Agent Engine 中测试已部署的智能体¶

这些说明解释了如何测试部署到 Agent Engine 运行时环境的 ADK 智能体。在使用这些说明之前，你需要使用可用方法之一完成将智能体部署到 Agent Engine 运行时环境的操作。本指南向你展示如何通过 Google Cloud Console 查看、交互和测试已部署的智能体，以及使用 REST API 调用或 Vertex AI SDK for Python 与智能体交互。

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

要在 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_ID、RESOURCE_ID) 才能测试部署。你可以使用 Cloud Console 或 gcloud 命令行工具查找此信息。

Vertex AI 快速模式 API 密钥

如果你使用 Vertex AI 快速模式,可以跳过此步骤并使用你的 API 密钥。

要使用 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 调用并从已部署的智能体获取响应：

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

Google Cloud 项目Vertex AI 快速模式

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

curl -X GET \
    -H "x-goog-api-key:YOUR-EXPRESS-MODE-API-KEY" \
    "https://aiplatform.googleapis.com/v1/reasoningEngines"

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

删除连接 URL 的 :query 参数

如果你使用 Cloud Console 的 Agent Engine 部分中提供的 Query URL,请确保从地址末尾删除 :query 参数。

智能体连接的访问权限

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

发送智能体请求¶

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

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

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

Google Cloud 项目Vertex AI 快速模式

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

curl \
    -H "x-goog-api-key:YOUR-EXPRESS-MODE-API-KEY" \
    -H "Content-Type: application/json" \
    https://aiplatform.googleapis.com/v1/reasoningEngines/$(RESOURCE_ID):query \
    -d '{"class_method": "async_create_session", "input": {"user_id": "u_123"},}'

在前一个命令的响应中，从 id 字段提取创建的 Session ID:

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

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

Google Cloud 项目Vertex AI 快速模式

curl \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://$(LOCATION_ID)-aiplatform.googleapis.com/v1/projects/$(PROJECT_ID)/locations/$(LOCATION_ID)/reasoningEngines/$(RESOURCE_ID):query?alt=sse -d '{
"class_method": "async_stream_query",
"input": {
    "user_id": "u_123",
    "session_id": "4857885913439920384",
    "message": "Hey whats the weather in new york today?",
}
}'

curl \
-H "x-goog-api-key:YOUR-EXPRESS-MODE-API-KEY" \
-H "Content-Type: application/json" \
https://aiplatform.googleapis.com/v1/reasoningEngines/$(RESOURCE_ID):query?alt=sse -d '{
"class_method": "async_stream_query",
"input": {
    "user_id": "u_123",
    "session_id": "4857885913439920384",
    "message": "Hey whats the weather in new york today?",
}
}'

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

使用 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': 'The weather in New York is sunny with a temperature of 25 degrees Celsius (41 degrees Fahrenheit).'}}}], 'role': 'user'}
{'parts': [{'text': 'The weather in New York is sunny with a temperature of 25 degrees Celsius (41 degrees Fahrenheit).'}], 'role': 'model'}

有关与 Agent Engine 中已部署的 ADK 智能体交互的更多信息，请参阅 Agent Engine 文档中的管理已部署的智能体和使用智能体开发工具包智能体。

发送多模态查询¶

要向智能体发送多模态查询 (例如，包括图像),你可以使用 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="What is in this image?",
)

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。

清理部署¶

如果你已执行部署作为测试，完成后清理云资源是一个好习惯。你可以删除已部署的 Agent Engine 实例，以避免 Google Cloud 账户上的任何意外费用。

remote_app.delete(force=True)

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