此页面由 Cloud Translation API 翻译。

使用 Google Cloud 控制台或 API 调用管理会话

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

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

创建 Vertex AI Agent Engine 实例

如需访问 Vertex AI Agent Engine 会话，您首先需要使用 Vertex AI Agent Engine 实例。您无需部署任何代码即可开始使用会话。如果您之前使用过 Agent Engine，那么创建 Vertex AI Agent Engine 实例只需几秒钟，无需部署任何代码。如果您是首次使用 Agent Engine，可能需要更长时间。

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

import vertexai

client = vertexai.Client(
  project="PROJECT_ID",
  location="LOCATION"
)
# If you don't have an Agent Engine instance already, create an instance.
agent_engine = client.agent_engines.create()

# Optionally, print out the Agent Engine resource name. You will need the
# resource name to interact with Sessions later on.
print(agent_engine.api_resource.name)

替换以下内容：

PROJECT_ID：您的项目 ID。
LOCATION：您的区域。请参阅会话的支持的区域。

列出会话

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

Google Cloud 控制台

对于已部署的代理，您可以使用 Google Cloud 控制台列出与代理关联的会话：

在 Google Cloud 控制台中，前往 Vertex AI Agent Engine 页面。

前往 Agent Engine

属于所选项目的 Agent Engine 实例会显示在列表中。您可以使用过滤字段按指定列过滤列表。
点击 Agent Engine 实例的名称。
点击会话标签页。系统会按 ID 显示会话列表。

Python 版 Vertex AI SDK

for session in client.agent_engines.sessions.list(
    name=agent_engine.api_resource.name,  # Required
):
    print(session)

# To list sessions for a specific user:
for session in client.agent_engines.sessions.list(
    name=agent_engine.api_resource.name,  # Required
    config={"filter": "user_id=USER_ID"},
):
    print(session)

USER_ID：自行选择用户 ID，字符数限制为 128。例如 user-123。

REST

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

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

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI，或者使用了 Cloud Shell，这会使您自动登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

执行以下命令：

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

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

执行以下命令：

$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

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

（可选）如需列出特定用户的会话，您可以添加查询参数 ?filter=user_id=\"USER_ID\"，其中 USER_ID 是您要查询的用户的 ID。

创建会话

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

Google Cloud 控制台

对于已部署的代理，您可以使用 Google Cloud 控制台创建会话：

在 Google Cloud 控制台中，前往 Vertex AI Agent Engine 页面。

前往 Agent Engine

属于所选项目的 Agent Engine 实例会显示在列表中。您可以使用过滤字段按指定列过滤列表。
点击 Agent Engine 实例的名称。
点击 Playground 标签页。
点击新会话以创建新会话。

Python 版 Vertex AI SDK

session = client.agent_engines.sessions.create(
    name=agent_engine.api_resource.name,  # Required
    user_id=USER_ID, # Required
)

其中，USER_ID 是您定义的用户 ID。例如 user-123。

REST

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

PROJECT_ID：您的项目 ID。
LOCATION：您在其中创建 Agent Engine 实例的区域。
AGENT_ENGINE_ID：Agent Engine 实例的资源 ID。
USER_ID：您定义的用户 ID。例如 sessions-agent。

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

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 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 实例关联的特定会话。

Google Cloud 控制台

对于已部署的代理，您可以使用 Google Cloud 控制台创建会话：

在 Google Cloud 控制台中，前往 Vertex AI Agent Engine 页面。

前往 Agent Engine

属于所选项目的 Agent Engine 实例会显示在列表中。您可以使用过滤字段按指定列过滤列表。
点击 Agent Engine 实例的名称。
点击 Playground 标签页。
点击会话标签页。系统会按 ID 显示会话列表。
点击要查看更多详细信息的会话。

Python 版 Vertex AI SDK

session = client.agent_engines.sessions.get(
    name='projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions/SESSION_ID',  # Required
    user_id=USER_ID, # Required
)
# session.name will correspond to
#   'projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions/SESSION_ID'

REST

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

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

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

执行以下命令：

$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 实例关联的会话。

Google Cloud 控制台

对于已部署的代理，您可以使用 Google Cloud 控制台删除与代理关联的会话：

在 Google Cloud 控制台中，前往 Vertex AI Agent Engine 页面。

前往 Agent Engine

属于所选项目的 Agent Engine 实例会显示在列表中。您可以使用过滤字段按指定列过滤列表。
点击 Agent Engine 实例的名称。
点击会话标签页。系统会按 ID 显示会话列表。
点击要删除的会话的更多操作菜单 ()。
点击删除。
点击删除会话。

Python 版 Vertex AI SDK

client.agent_engines.sessions.delete(name=session.name)

REST

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

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

HTTP 方法和网址：

DELETE https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/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/reasoningEngines/AGENT_ENGINE_ID/sessions/SESSION_ID"

PowerShell

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

执行以下命令：

$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/reasoningEngines/AGENT_ENGINE_ID/sessions/SESSION_ID" | Select-Object -Expand Content

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

列出会话中的事件

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

Google Cloud 控制台

对于已部署的代理，您可以使用 Google Cloud 控制台创建会话：

在 Google Cloud 控制台中，前往 Vertex AI Agent Engine 页面。

前往 Agent Engine

属于所选项目的 Agent Engine 实例会显示在列表中。您可以使用过滤字段按指定列过滤列表。
点击 Agent Engine 实例的名称。
点击 Playground 标签页。
点击会话标签页。系统会按 ID 显示会话列表。
点击要查看更多详细信息的会话。
点击活动标签页，查看与会话相关联的活动。

Python 版 Vertex AI SDK

for session_event in client.agent_engines.list_session_events(
    name=session.name,
):
    print(session_event)

REST

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

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

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

执行以下命令：

$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 实例关联的会话。

Google Cloud 控制台

对于已部署的代理，您可以使用 Google Cloud 控制台创建会话：

在 Google Cloud 控制台中，前往 Vertex AI Agent Engine 页面。

前往 Agent Engine

属于所选项目的 Agent Engine 实例会显示在列表中。您可以使用过滤字段按指定列过滤列表。
点击 Agent Engine 实例的名称。
点击 Playground 标签页。
点击会话标签页。系统会按 ID 显示会话列表。
点击要查看更多详细信息的会话。
点击活动标签页，查看与会话相关联的活动。
输入消息，然后按 Enter 键，即可向会话添加新事件。

Python 版 Vertex AI SDK

import datetime

client.agent_engines.sessions.events.append(
    name=session.name,
    author="user",                                              # Required.
    invocation_id="1",                                          # Required.
    timestamp=datetime.datetime.now(tz=datetime.timezone.utc),  # Required.
    config={
        "content": {
            "role": "user",
            "parts": [{"text": "hello"}]
        },
    },
)

REST

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

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:appendEvent

请求 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:appendEvent"

PowerShell

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 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:appendEvent" | Select-Object -Expand Content

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

清理

如需清理此项目中使用的所有资源，您可以删除 Vertex AI Agent Engine 实例及其子资源：

agent_engine.delete(force=True)

使用 Google Cloud 控制台或 API 调用管理会话 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

创建 Vertex AI Agent Engine 实例

列出会话

Google Cloud 控制台

Python 版 Vertex AI SDK

REST

curl

PowerShell

创建会话

Google Cloud 控制台

Python 版 Vertex AI SDK

REST

curl

PowerShell

获取会话

Google Cloud 控制台

Python 版 Vertex AI SDK

REST

curl

PowerShell

删除会话

Google Cloud 控制台

Python 版 Vertex AI SDK

REST

curl

PowerShell

列出会话中的事件

Google Cloud 控制台

Python 版 Vertex AI SDK

REST

curl

PowerShell

向会话附加事件

Google Cloud 控制台

Python 版 Vertex AI SDK

REST

curl

PowerShell

清理

使用 Google Cloud 控制台或 API 调用管理会话