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

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

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

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

建立 Agent Runtime 執行個體

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

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

import agentplatform

client = agentplatform.Client(
  project="PROJECT_ID",
  location="LOCATION"
)
# If you don't have an Agent Runtime instance already, create an instance.
remote_agent = client.runtimes.create()

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

更改下列內容：

PROJECT_ID：專案 ID。
LOCATION：所在區域。請參閱支援工作階段的區域。

列出工作階段

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

控制台

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

前往 Google Cloud 控制台的「Agent Platform Deployments」(Agent Platform 部署作業) 頁面。

前往「Deployments」(部署作業) 頁面

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

Python

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

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

USER_ID：選擇自己的使用者 ID，字元限制為 128 個。例如：user-123。

根據預設，client.sessions.list 會傳回依建立時間遞減排序的工作階段 (create_time desc)。當多個工作階段同時更新時，這個預設順序可確保分頁穩定。Python SDK 不會公開 order_by 選項。如要依其他欄位排序，請使用 REST API。

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。

如要排序傳回的工作階段，請新增查詢參數 ?orderBy=ORDER_BY，其中 ORDER_BY 為 create_time、update_time 或 display_name。您可以附加 %20desc 來遞減排序，例如 ?orderBy=create_time%20desc。如果省略 orderBy，API 會傳回依 create_time desc 排序的工作階段。在並行更新期間，請使用 create_time desc 分頁瀏覽工作階段，以免更新作業導致工作階段跨越頁面邊界。

建立工作階段

建立與使用者 ID 相關聯的工作階段。

控制台

如果是已部署的代理，您可以使用 Google Cloud 控制台建立工作階段：

前往 Google Cloud 控制台的「Agent Platform Deployments」(Agent Platform 部署作業) 頁面。

前往「Deployments」(部署作業) 頁面

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

Python

session = client.sessions.create(
    name=remote_agent.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.sessions.create(
    name=remote_agent.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.sessions.create(
    name=remote_agent.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」(Agent Platform 部署作業) 頁面。

前往「Deployments」(部署作業) 頁面

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

Python

session = client.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」(Agent Platform 部署作業) 頁面。

前往「Deployments」(部署作業) 頁面

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

Python

client.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」(Agent Platform 部署作業) 頁面。

前往「Deployments」(部署作業) 頁面

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

Python

for session_event in client.sessions.events.list(
    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」(Agent Platform 部署作業) 頁面。

前往「Deployments」(部署作業) 頁面

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

Python

import datetime

client.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.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 執行個體及其子項資源：

remote_agent.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 呼叫管理工作階段