Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

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

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

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

建立 Agent Runtime 執行個體

如要存取 Agent Platform Sessions，請先使用 Agent Runtime 執行個體。您不需要部署任何程式碼，即可開始使用 Sessions。如果您曾使用 Agent Engine，建立 Agent Runtime 執行個體只需幾秒鐘，不必部署程式碼。如果您是第一次使用 Agent Engine，可能需要較長的處理時間。

如果沒有現有的 Agent Runtime 執行個體，請使用下列程式碼建立一個：

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：您的區域。如需支援的區域，請參閱這篇文章。

列出工作階段

列出與 Agent Runtime 執行個體相關聯的會話。

控制台

如果是已部署的代理程式，您可以使用 Google Cloud 控制台列出與代理程式相關聯的工作階段：

前往 Google Cloud 控制台的 Agent Platform「Deployments」頁面。

前往「Deployments」(部署作業)

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

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 控制台的 Agent Platform「Deployments」頁面。

前往「Deployments」(部署作業)

清單會顯示所選專案的 Agent Engine 執行個體。您可以使用「篩選器」欄位，依指定資料欄篩選清單。
按一下 Agent Engine 執行個體的名稱。
按一下「Playground」分頁標籤。
按一下「新工作階段」建立新工作階段。

Python

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

其中 USER_ID 是您定義的使用者 ID。例如：user-123。

如果是 SESSION_ID，請考量下列限制，避免與系統產生的 ID 發生衝突：

如果第一個字元是英文字母，ID 最多可有 63 個字元。有效字元為小寫英文字母、數字和連字號 ([a-z0-9-])。最後一個字元必須是英文字母或數字
如果第一個字元是數字，ID 最多可有 9 個字元。有效字元為數字 ([0-9])，開頭不得為零。

REST

使用任何要求資料之前，請先修改下列項目的值：

PROJECT_ID：專案 ID。
LOCATION：建立 Agent Engine 執行個體的區域。
AGENT_ENGINE_ID： Agent Engine 執行個體的資源 ID。
USER_ID：您定義的使用者 ID。例如：sessions-agent。
SESSION_ID：您定義的工作階段 ID。例如：my-custom-session。
為避免與系統產生的 ID 發生衝突，指定自訂工作階段 ID 時請遵守下列限制：
- 如果第一個字元是英文字母，ID 最多可有 63 個字元。有效字元為小寫英文字母、數字和連字號 (`[a-z0-9-]`)。最後一個字元必須是英文字母或數字。
- 如果第一個字元是數字，ID 最多可有 9 個字元。有效字元為數字 (`[0-9]`)，開頭不得為零。
HTTP 方法和網址：
```
POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions
```
JSON 要求內文：
```
{
  "userId": USER_ID
}
```
如要傳送要求，請選擇以下其中一個選項：
curl

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login 透過使用者帳戶登入 gcloud CLI，或是使用 Cloud Shell 自動登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

將要求主體儲存在名為 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
您應該會收到長時間執行的作業，可以查詢該作業來檢查工作階段的建立狀態。

設定工作階段存留時間 (TTL)

所有工作階段都必須有到期時間。您可以在建立或更新工作階段時定義到期時間。工作階段及其子項事件會在到期時間過後自動刪除。您可以直接設定到期時間 (expire_time)，也可以設定存留時間 (ttl)，單位為秒。如果兩者皆未指定，系統會套用 365 天的預設存留時間。

存留時間

如果您設定存留時間，伺服器會將新建立的工作階段到期時間計算為 create_time + ttl，或將更新的工作階段到期時間計算為 update_time + ttl。

client.agent_engines.sessions.create(
    name=agent_engine.api_resource.name,  # Required
    user_id=USER_ID, # Required
    config={
        # Session will be deleted 10 days after creation time.
        "ttl": f"{24 * 60 * 60 * 10}s"
    }
)

到期時間

import datetime

client.agent_engines.sessions.create(
    name=agent_engine.api_resource.name,  # Required
    user_id=USER_ID, # Required
    config={
        # Session will be deleted at the provided time (10 days after current time).
        "expire_time": datetime.datetime.now(tz=datetime.timezone.utc) + datetime.timedelta(seconds=24 * 60 * 60 * 10),
    }
)

取得工作階段

取得與 Agent Platform 執行個體相關聯的特定工作階段。

控制台

對於已部署的代理程式，您可以使用 Google Cloud 控制台建立工作階段：

前往 Google Cloud 控制台的 Agent Platform「Deployments」頁面。

前往「Deployments」(部署作業)

清單會顯示所選專案的 Agent Engine 執行個體。您可以使用「篩選器」欄位，依指定資料欄篩選清單。
按一下 Agent Engine 執行個體的名稱。
按一下「Playground」分頁標籤。
按一下「工作階段」分頁標籤。系統會依 ID 顯示工作階段清單。
按一下要查看詳細資料的會話。

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

回覆內容應會顯示工作階段的相關資訊。

刪除工作階段

刪除與 Agent Platform 執行個體相關聯的工作階段。

控制台

如果是已部署的代理程式，您可以使用 Google Cloud 控制台刪除與代理程式相關聯的工作階段：

前往 Google Cloud 控制台的 Agent Platform「Deployments」頁面。

前往「Deployments」(部署作業)

清單會顯示所選專案的 Agent Engine 執行個體。您可以使用「篩選器」欄位，依指定資料欄篩選清單。
按一下 Agent Engine 執行個體的名稱。
按一下「工作階段」分頁標籤。系統會依 ID 顯示工作階段清單。
找到要刪除的會話，然後按一下「更多動作」選單 ()。
點選「刪除」。
按一下「刪除工作階段」。

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) 和空白回應。

列出工作階段中的事件

列出與 Agent Platform 執行個體相關聯的工作階段中的事件。

控制台

對於已部署的代理程式，您可以使用 Google Cloud 控制台建立工作階段：

前往 Google Cloud 控制台的 Agent Platform「Deployments」頁面。

前往「Deployments」(部署作業)

清單會顯示所選專案的 Agent Engine 執行個體。您可以使用「篩選器」欄位，依指定資料欄篩選清單。
按一下 Agent Engine 執行個體的名稱。
按一下「Playground」分頁標籤。
按一下「工作階段」分頁標籤。系統會依 ID 顯示工作階段清單。
按一下要查看詳細資料的會話。
按一下「事件」分頁標籤，即可查看與工作階段相關聯的事件。

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

回覆中應會顯示與工作階段相關聯的事件清單。

將事件附加至工作階段

將事件附加至與 Agent Platform 執行個體相關聯的工作階段。

控制台

對於已部署的代理程式，您可以使用 Google Cloud 控制台建立工作階段：

前往 Google Cloud 控制台的 Agent Platform「Deployments」頁面。

前往「Deployments」(部署作業)

清單會顯示所選專案的 Agent Engine 執行個體。您可以使用「篩選器」欄位，依指定資料欄篩選清單。
按一下 Agent Engine 執行個體的名稱。
按一下「Playground」分頁標籤。
按一下「工作階段」分頁標籤。系統會依 ID 顯示工作階段清單。
按一下要查看詳細資料的會話。
按一下「事件」分頁標籤，即可查看與工作階段相關聯的事件。
輸入訊息，然後按下 Enter 鍵，即可在工作階段中新增事件。

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"}]
        },
    },
)

或者，您可以使用 raw_event 欄位，在工作階段事件中加入任意資料。這項功能有助於與其他代理程式架構互通，或儲存自訂事件資料。

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={
        "raw_event": {
            "content": "hello",
            "custom_field": "custom_value"
        },
    },
)

REST

使用任何要求資料之前，請先修改下列項目的值：

PROJECT_ID：專案 ID。
LOCATION：建立 Agent Engine 執行個體的區域。
AGENT_ENGINE_ID： Agent Engine 執行個體的資源 ID。
USER_ID：您定義的使用者 ID。例如：sessions-agent。
SESSION_ID：您定義的工作階段 ID。例如：my-custom-session。
為避免與系統產生的 ID 發生衝突，指定自訂工作階段 ID 時請遵守下列限制：
- 如果第一個字元是英文字母，ID 最多可有 63 個字元。有效字元為小寫英文字母、數字和連字號 (`[a-z0-9-]`)。最後一個字元必須是英文字母或數字。
- 如果第一個字元是數字，ID 最多可有 9 個字元。有效字元為數字 (`[0-9]`)，開頭不得為零。
HTTP 方法和網址：
```
POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions
```
JSON 要求內文：
```
{
  "userId": USER_ID
}
```
如要傳送要求，請選擇以下其中一個選項：
curl

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login 透過使用者帳戶登入 gcloud CLI，或是使用 Cloud Shell 自動登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

將要求主體儲存在名為 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
您應該會收到長時間執行的作業，可以查詢該作業來檢查工作階段的建立狀態。

清除所用資源

如要清理此專案中使用的所有資源，您可以刪除 Agent Platform 執行個體及其子項資源：

agent_engine.delete(force=True)

使用 Google Cloud 控制台或 API 呼叫管理工作階段 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

建立 Agent Runtime 執行個體

列出工作階段

控制台

Python

REST

curl

PowerShell

建立課程

控制台

Python

REST

curl

PowerShell

設定工作階段存留時間 (TTL)

存留時間

到期時間

取得工作階段

控制台

Python

REST

curl

PowerShell

刪除工作階段

控制台

Python

REST

curl

PowerShell

列出工作階段中的事件

控制台

Python

REST

curl

PowerShell

將事件附加至工作階段

控制台

Python

REST

curl

PowerShell

清除所用資源

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