Test deployed agents in Agent Engine

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

These instructions explain how to test an ADK agent deployed to Agent Engine runtime environment. Before using these instructions, you need to have completed the deployment of your agent to Agent Engine runtime environment using one of the available methods. This guide shows you how to view, interact, and test your deployed agent through Google Cloud Console, and interact with agent using REST API calls or Vertex AI SDK for Python.

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

View deployed agent in Cloud Console

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

To view your deployed agent in Cloud Console:

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

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

This page lists all deployed agents in your currently selected Google Cloud project. If you do not see your agent listed, make sure you have your target project selected in Google Cloud Console. For more information on selecting an existing Google Cloud project, see Creating and managing projects.

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

Find Google Cloud project information

查找 Google Cloud 项目信息

You need to address and resource identification for your project (PROJECT_ID, LOCATION_ID, RESOURCE_ID) to be able to test your deployment. You can use Cloud Console or gcloud command line tool to find this information.

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

Vertex AI express mode API key

If you are using Vertex AI express mode, you can skip this step and use your API key.

Vertex AI 快速模式 API 密钥

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

To find your project information with Google Cloud Console:

使用 Google Cloud Console 查找您的项目信息:

1. In Google Cloud Console, navigate to Agent Engine page: https://console.cloud.google.com/vertex-ai/agents/agent-engines

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

2. At top of page, select API URLs, and then copy Query URL string for your deployed agent, which should be in this format:

   1. 在页面顶部,选择 API URLs,然后复制已部署智能体的 查询 URL字符串,其格式应如下:

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

To find your project information with gcloud command line tool:

使用 gcloud 命令行工具查找您的项目信息:

1. In your development environment, make sure you are authenticated to Google Cloud and run the following command to list your project:

   1. 在开发环境中,确保您已向 Google Cloud 进行身份验证并运行以下命令以列出您的项目:

   gcloud projects list
   

2. With Project ID you used for deployment, run this command to get additional details:

   1. 使用部署时使用的项目 ID,运行此命令以获取其他详细信息:

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

Test using REST calls

使用 REST 调用进行测试

A simple way to interact with your deployed agent in Agent Engine is to use REST calls with curl tool. This section describes how to check your connection to agent and also to test processing of a request by deployed agent.

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

Check connection to agent

检查与智能体的连接

You can check your connection to running agent using Query URL available in Agent Engine section of Cloud Console. This check does not execute the deployed agent, but returns information about agent.

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

To send a REST call and get a response from deployed agent:

要发送 REST 调用并从已部署的智能体获取响应:

• In a terminal window of your development environment, build a request and execute it:

  • 在开发环境的终端窗口中,构建请求并执行它:
  Google Cloud ProjectVertex AI express mode

  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"
  

If your deployment was successful, this request responds with a list of valid requests and expected data formats.

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

Remove :query parameter for connection URL

If you use the Query URL available in Agent Engine section of Cloud Console, make sure to remove the :query parameter from the end of the address.

移除连接 URL 的 :query 参数

如果您使用 Cloud Console 中 Agent Engine 部分可用的 查询 URL,请确保从地址末尾移除 :query 参数。

Access for agent connections

This connection test requires the calling user has a valid access token for the deployed agent. When testing from other environments, make sure the calling user has access to connect to the agent in your Google Cloud project.

智能体连接的访问权限

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

Send an agent request

发送智能体请求

When getting responses from your agent project, you must first create a session, receive a Session ID, and then send your requests using that Session ID. This process is described in the following instructions.

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

To test interaction with deployed agent via REST:

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

1. In a terminal window of your development environment, create a session by building a request using this template:

   1. 在开发环境的终端窗口中,使用此模板构建请求来创建会话:
   Google Cloud ProjectVertex AI express mode

   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"},}'
   

2. In response from the previous command, extract the created Session ID from the id field:

   1. 在上一个命令的响应中,从 id 字段提取创建的 会话 ID:

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

3. In a terminal window of your development environment, send a message to your agent by building a request using this template and the Session ID created in the previous step:

   1. 在开发环境的终端窗口中,使用此模板和在上一步中创建的会话 ID 构建请求向您的智能体发送消息:
   Google Cloud ProjectVertex AI express mode

   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 what's 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 what's the weather in new york today?",
   }
   }'
   

This request should generate a response from your deployed agent code in JSON format. For more information about interacting with a deployed ADK agent in Agent Engine using REST calls, see Manage deployed agents and Use an Agent Development Kit agent in Agent Engine documentation.

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

Test using Python

使用 Python 进行测试

You can use Python code for more sophisticated and repeatable testing of your agent deployed in Agent Engine. These instructions describe how to create a session with the deployed agent, and then send a request to the agent for processing.

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

Create a remote session

创建远程会话

Use the remote_app object to create a connection to a deployed, remote agent:

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

# If you are in a new script or used the ADK CLI to deploy, you can connect like this:
# remote_app = agent_engines.get("your-agent-resource-name")
remote_session = await remote_app.async_create_session(user_id="u_456")
print(remote_session)

Expected output for create_session (remote):

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

The id value is the session ID, and app_name is the resource ID of the deployed agent on Agent Engine.

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

Send queries to your remote agent

向您的远程智能体发送查询

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

Expected output for async_stream_query (remote):

{'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'}

For more information about interacting with a deployed ADK agent in Agent Engine, see Manage deployed agents and Use an Agent Development Kit agent in Agent Engine documentation.

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

Sending Multimodal Queries

发送多模态查询

To send multimodal queries (e.g., including images) to your agent, you can construct the message parameter of async_stream_query with a list of types.Part objects. Each part can be text or an image.

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

To include an image, you can use types.Part.from_uri, providing a Google Cloud Storage (GCS) URI for the image.

要包含图像,您可以使用 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

While the underlying communication with the model may involve Base64 encoding for images, the recommended and supported method for sending image data to an agent deployed on Agent Engine is by providing a GCS URI.

注意

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

Clean up deployments

清理部署

If you have performed deployments as tests, it is a good practice to clean up your cloud resources after you have finished. You can delete the deployed Agent Engine instance to avoid any unexpected charges on your Google Cloud account.

如果您作为测试执行了部署,在完成后清理云资源是一个良好的做法。您可以删除已部署的 Agent Engine 实例以避免您的 Google Cloud 账户产生任何意外费用。

remote_app.delete(force=True)

The force=True parameter also deletes any child resources that were generated from the deployed agent, such as sessions. You can also delete your deployed agent via the Agent Engine UI on Google Cloud.

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