使用直接 API 调用管理会话

本部分介绍了如何使用 Vertex AI Agent Engine 会话通过直接 API 调用来管理会话。如果您不想使用 ADK 代理来管理会话，可以直接调用 API。

如需使用 ADK 代理管理会话，请参阅使用智能体开发套件管理会话。

创建 Vertex AI Agent Engine 实例

如需访问 Vertex AI Agent Engine 会话，您需要使用 Vertex AI Agent Engine 实例。您无需部署任何代码即可开始使用会话。无需部署代码，只需几秒钟即可创建 Vertex AI Agent Engine 实例。

如果您没有现有的 Vertex AI Agent Engine 实例，请使用以下代码创建一个：

import vertexai
from vertexai import agent_engines

# Create an agent engine instance
agent_engine = agent_engines.create()

列出会话

列出与您的 Vertex AI Agent Engine 实例关联的所有会话。

REST API

使用 sessions.list 方法：

在使用任何请求数据之前，请先进行以下替换：

  • PROJECT_ID：您的项目 ID。
  • LOCATION：您创建 Agent Engine 实例的区域。
  • AGENT_ENGINE_ID： Agent Engine 实例的资源 ID。

HTTP 方法和网址：

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions

如需发送请求，请选择以下方式之一：

curl

执行以下命令：

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

PowerShell

执行以下命令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions" | Select-Object -Expand Content

您应该会看到返回的会话列表。

创建会话

创建与用户 ID 相关联的会话。

REST API

使用 sessions.create 方法。

在使用任何请求数据之前，请先进行以下替换：

  • PROJECT_ID：您的项目 ID。
  • LOCATION：您创建 Agent Engine 实例的区域。
  • AGENT_ENGINE_ID： Agent Engine 实例的资源 ID。
  • USER_ID：用户 ID

HTTP 方法和网址：

POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions

请求 JSON 正文： 

{
  "userId": USER_ID
}

如需发送请求，请选择以下方式之一：

curl

将请求正文保存在名为 request.json 的文件中，然后执行以下命令： 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions"

PowerShell

将请求正文保存在名为 request.json 的文件中，然后执行以下命令： 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions" | Select-Object -Expand Content

您应该会收到一个长时间运行的操作，您可以查询该操作以检查会话的创建状态。

获取会话

获取与 Vertex AI Agent Engine 实例关联的特定会话。

REST API

使用 sessions.get 方法。

在使用任何请求数据之前，请先进行以下替换：

  • PROJECT_ID：您的项目 ID。
  • LOCATION：您创建 Agent Engine 实例的区域。
  • AGENT_ENGINE_ID： Agent Engine 实例的资源 ID。
  • SESSION_ID：您要检索的会话的资源 ID。 您可以从创建会话时收到的响应中获取会话 ID。

HTTP 方法和网址：

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions/SESSION_ID

如需发送请求，请选择以下方式之一：

curl

执行以下命令：

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

PowerShell

执行以下命令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions/SESSION_ID" | Select-Object -Expand Content

在响应中，您应该会看到有关会话的信息。

删除会话

删除与 Vertex AI Agent Engine 实例关联的会话。

REST API

使用 sessions.delete 方法。

在使用任何请求数据之前，请先进行以下替换：

  • PROJECT_ID：您的项目 ID。
  • LOCATION：要在其中创建示例商店实例的区域。
  • AGENT_ENGINE_ID： Agent Engine 实例的资源 ID。
  • SESSION_ID：您要检索的会话的资源 ID。

HTTP 方法和网址：

DELETE https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/sessions/SESSION_ID

如需发送请求，请选择以下方式之一：

curl

执行以下命令：

curl -X DELETE \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/sessions/SESSION_ID"

PowerShell

执行以下命令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method DELETE `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/sessions/SESSION_ID" | Select-Object -Expand Content

您应该会收到一个成功的状态代码 (2xx) 和一个空响应。

列出会议中的活动

列出与 Vertex AI Agent Engine 实例关联的会话中的事件。

REST API

使用 events.list 方法。

在使用任何请求数据之前，请先进行以下替换：

  • PROJECT_ID：您的项目 ID。
  • LOCATION：您创建 Agent Engine 实例的区域。
  • AGENT_ENGINE_ID： Agent Engine 实例的资源 ID。
  • SESSION_ID：您要检索的会话的资源 ID。

HTTP 方法和网址：

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions/SESSION_ID/events

如需发送请求，请选择以下方式之一：

curl

执行以下命令：

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

PowerShell

执行以下命令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions/SESSION_ID/events" | Select-Object -Expand Content

在响应中，您应该会看到与您的会话相关联的事件列表。

向会话附加事件

将事件附加到与 Vertex AI Agent Engine 实例关联的会话。

REST API

使用 sessions.appendEvent 方法。

在使用任何请求数据之前，请先进行以下替换：

  • PROJECT_ID：您的项目 ID。
  • LOCATION：您创建 Agent Engine 实例的区域。
  • AGENT_ENGINE_ID： Agent Engine 实例的资源 ID。
  • SESSION_ID：您要向其附加事件的会话的资源 ID。
  • AUTHOR：事件的作者。可以是 'user'，也可以是代理名称。
  • INVOCATION_ID：调用的标识符。
  • TIMESTAMP：相应事件的时间戳。

HTTP 方法和网址：

POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions/SESSION_ID

请求 JSON 正文： 

{
  "author": AUTHOR,
  "invocationId": INVOCATION_ID,
  "timestamp": TIMESTAMP,
}

如需发送请求，请选择以下方式之一：

curl

将请求正文保存在名为 request.json 的文件中，然后执行以下命令： 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions/SESSION_ID"

PowerShell

将请求正文保存在名为 request.json 的文件中，然后执行以下命令： 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions/SESSION_ID" | Select-Object -Expand Content

您应该会收到一个成功的状态代码 (2xx) 和一个空响应。