本頁面由 Cloud Translation API 翻譯而成。

使用 Google Cloud 控制台或 API 呼叫管理工作階段

本節說明如何使用 Vertex AI Agent Engine Sessions，透過 Google Cloud 控制台或直接 API 呼叫管理工作階段。如不想使用 ADK 代理程式管理工作階段，可以改用 Google Cloud 控制台或直接呼叫 API。

如要使用 ADK 代理管理工作階段，請參閱「使用 Agent Development Kit 管理工作階段」。

建立 Vertex AI Agent Engine 執行個體

如要存取 Vertex AI Agent Engine 工作階段，您必須先使用 Vertex AI Agent Engine 執行個體。您不需要部署任何程式碼，即可開始使用 Sessions。如果您曾使用 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：您的區域。如要查看支援 Sessions 的區域，請參閱這篇文章。

列出工作階段

列出與 Vertex AI Agent Engine 執行個體相關聯的工作階段。

Google Cloud 控制台

如果是已部署的代理程式，您可以使用 Google Cloud 主控台列出與代理程式相關聯的會話：

前往 Google Cloud 控制台的「Vertex AI Agent Engine」頁面。

前往 Agent Engine

清單中會顯示所選專案的 Agent Engine 執行個體。您可以使用「篩選」欄位，依指定欄篩選清單。
按一下 Agent Engine 執行個體的名稱。
按一下「Sessions」(工作階段) 分頁標籤。系統會依 ID 顯示工作階段清單。

Vertex AI SDK for Python

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」分頁標籤。
按一下「新階段」建立新階段。

Vertex AI SDK for Python

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」分頁標籤。
按一下「Sessions」(工作階段) 分頁標籤。系統會依 ID 顯示工作階段清單。
按一下要查看詳細資料的會話。

Vertex AI SDK for Python

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 執行個體的名稱。
按一下「Sessions」(工作階段) 分頁標籤。系統會依 ID 顯示工作階段清單。
找到要刪除的會話，然後按一下「更多動作」選單 ()。
按一下「Delete」(刪除)。
按一下「刪除工作階段」。

Vertex AI SDK for Python

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」分頁標籤。
按一下「Sessions」(工作階段) 分頁標籤。系統會依 ID 顯示工作階段清單。
按一下要查看詳細資料的會話。
按一下「事件」分頁標籤，即可查看與工作階段相關聯的事件。

Vertex AI SDK for Python

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」分頁標籤。
按一下「Sessions」(工作階段) 分頁標籤。系統會依 ID 顯示工作階段清單。
按一下要查看詳細資料的會話。
按一下「事件」分頁標籤，即可查看與工作階段相關聯的事件。
輸入訊息，然後按下 Enter 鍵，即可在工作階段中新增事件。

Vertex AI SDK for Python

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：叫用的 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 控制台

Vertex AI SDK for Python

REST

curl

PowerShell

建立工作階段

Google Cloud 控制台

Vertex AI SDK for Python

REST

curl

PowerShell

取得工作階段

Google Cloud 控制台

Vertex AI SDK for Python

REST

curl

PowerShell

刪除工作階段

Google Cloud 控制台

Vertex AI SDK for Python

REST

curl

PowerShell

列出工作階段中的事件

Google Cloud 控制台

Vertex AI SDK for Python

REST

curl

PowerShell

將事件附加至工作階段

Google Cloud 控制台

Vertex AI SDK for Python

REST

curl

PowerShell

清除所用資源

使用 Google Cloud 控制台或 API 呼叫管理工作階段