管理已部署的代理程式

您可以使用 Agent Runtime 管理已部署至平台的代理。您可以使用控制台、SDK 或 REST API,列出、取得、更新及刪除已部署的代理。

本文說明如何在 Agent Platform 管理已部署的代理。如要部署新的代理程式,請參閱「部署代理程式」。

列出已部署的代理

列出指定專案和位置的所有已部署代理:

控制台

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

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

清單會顯示所選專案中已部署的代理 (未部署執行階段的獨立記憶庫執行個體,會顯示在「Memory Bank」頁面)。您可以使用「Filter」(篩選器) 欄位,依指定資料欄篩選清單。

Agent Platform SDK

import agentplatform

client = agentplatform.Client(  # For service interactions via client.runtimes
    project="PROJECT_ID",
    location="LOCATION",
)

for agent in client.runtimes.list():
    print(agent)

如要依display_name篩選清單,請按照下列步驟操作:

for agent in client.runtimes.list(
    config={
        "filter": 'display_name="DISPLAY_NAME"',
    },
):
    print(agent)

REST

呼叫 reasoningEngines.list 方法。

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

  • PROJECT_ID:您的 GCP 專案 ID
  • LOCATION:支援的地區

HTTP 方法和網址:

GET https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines

請展開以下其中一個選項,以傳送要求:

您應該會收到執行成功的狀態碼 (2xx) 和空白回應。

取得已部署的代理

每個部署的代理程式都有專屬的 RESOURCE_ID ID。詳情請參閱「部署代理程式」。

控制台

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

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

    清單中會顯示所選專案中已部署的代理。您可以使用「Filter」(篩選器) 欄位,依指定資料欄篩選清單。

  2. 按一下指定代理的名稱。代理的「Metrics」(指標) 頁面隨即開啟。

  3. 選用:如要查看代理程式的部署作業詳細資料,請按一下「Deployment details」(部署作業詳細資料)。「Deployment details」(部署作業詳細資料) 窗格隨即開啟。如要關閉窗格,請點選「Done」(完成)。

  4. 選用:如要查看代理的 query 和 streamQuery 網址,請按一下「API URLs」(API 網址),系統會開啟「API URLs」(API 網址) 窗格。如要關閉窗格,請點選「Done」(完成)。

Agent Platform SDK

下列程式碼可讓您取得特定已部署的代理:

import agentplatform

client = agentplatform.Client(  # For service interactions via client.runtimes
    project="PROJECT_ID",
    location="LOCATION",
)

remote_agent = client.runtimes.get(
    name="projects/PROJECT_ID_OR_NUMBER/locations/LOCATION/reasoningEngines/RESOURCE_ID"
)

REST

呼叫 reasoningEngines.get 方法。

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

  • PROJECT_ID:您的 GCP 專案 ID
  • LOCATION:支援的地區
  • RESOURCE_ID:已部署代理的資源 ID

HTTP 方法和網址:

GET https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID

請展開以下其中一個選項,以傳送要求:

您應該會收到執行成功的狀態碼 (2xx) 和空白回應。

更新已部署的代理

您可以同時更新已部署代理的一或多個欄位,但至少須指定一個要更新的欄位。

您可以更新已部署代理的非版本化或版本化欄位。如果更新版本欄位,系統會建立新的修訂版本。如要進一步瞭解版本欄位和管理修訂版本,請參閱「管理修訂版本和流量」。

更新已部署的代理所需的時間,取決於執行的更新作業,但通常需要幾秒到幾分鐘。

控制台

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

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

  2. 在指定代理,按一下「更多動作」選單 ()。

  3. 點選「編輯」,代理的「Edit」(編輯) 窗格隨即開啟。

  4. 編輯代理的「顯示名稱」或「說明」。

  5. 按一下「儲存」。

Agent Platform SDK

如要將已部署的代理 (對應至 RESOURCE_NAME) 更新為新版代理 (對應至 UPDATED_AGENT),請按照下列步驟操作:

import agentplatform

client = agentplatform.Client(  # For service interactions via client.runtimes
    project="PROJECT_ID",
    location="LOCATION",
)

client.runtimes.update(
    name=RESOURCE_NAME,                    # Required.
    agent=UPDATED_AGENT,                   # Optional.
    config={                                                # Optional.
        "requirements": REQUIREMENTS,      # Optional.
        "display_name": "DISPLAY_NAME",    # Optional.
        "description": "DESCRIPTION",      # Optional.
        "extra_packages": EXTRA_PACKAGES,  # Optional.
    },
)

引數與部署代理時相同。

REST

呼叫 reasoningEngines.patch 方法,並提供 update_mask 指定要更新的欄位。

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

  • PROJECT_ID:您的 GCP 專案 ID
  • LOCATION:支援的地區
  • RESOURCE_ID:已部署代理的資源 ID
  • update_mask:以半形逗號分隔的清單,列出要更新的欄位

HTTP 方法和網址:

PATCH https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID?update_mask="display_name,description"

JSON 要求主體:

{
"displayName": "DISPLAY_NAME",
"description": "DESCRIPTION"
}

請展開以下其中一個選項,以傳送要求:

您應該會收到執行成功的狀態碼 (2xx) 和空白回應。

為已部署的代理設定遙測

如果在代理開發期間啟用追蹤記錄,可以使用 Google Cloud 控制台,為已部署的代理設定遙測。

為已部署且啟用遙測功能的代理設定遙測:

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

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

    清單中會顯示所選專案中的 Agent Platform 執行個體。您可以使用「Filter」(篩選器) 欄位,依指定資料欄篩選清單。

  2. 找出 Agent Platform 執行個體所在的資料列。在「Telemetry configuration」(遙測設定) 欄下方,按一下「Configure」(設定)。「Service configuration」(服務設定) 面板隨即開啟。

  3. 您可以進行下列設定:

    • 觀測能力:您可以設定下列項目:

      • 啟用 OpenTelemetry 追蹤記錄和記錄的檢測功能:如要填入代理觀測功能資訊主頁和追蹤記錄頁面,請將切換鈕設為開啟位置。

      • 啟用提示詞輸入內容和回覆輸出內容的記錄功能:如要收集並儲存使用者提示詞和回覆的完整內容,請將切換鈕設為開啟。

      如果代理程式已停用遙測收集功能,您必須重新部署代理程式,並將 Vertex AI SDK 版本更新至 >= 1.126.1,才能查看「觀測能力」的設定選項。

    • 容器:為已部署的代理程式設定容器:

      • 「Scaling」(資源調度):輸入「Minimum number of instances」(執行個體數量下限) 和「Maximum number of instances」(執行個體數量上限)。

      • 資源:選取各容器的記憶體和 CPU 限制。

      • 「Container concurrency」(容器並行處理):輸入「Minimum number of instances」(執行個體數量下限),設定各容器和代理伺服器的並行處理。建議值為 (2 * CPU + 1),預設值為 9。

    • 存取權和權限:按一下「Manage Permissions in IAM」(在 IAM 中管理權限),管理相關聯服務帳戶的代理權限。

    • 部署作業詳細資料:查看代理的部署作業詳細資料,包括「Resource name」(資源名稱) 和「Display name」(顯示名稱)。

    • 記憶庫:查看及編輯代理的記憶庫生成、擷取和保留設定。編輯時需要 aiplatform.reasoningEngines.update 權限;如果沒有這項權限,這些設定會是唯讀狀態。

  4. 按一下「更新」或「關閉」。

查看已部署代理的指標

如果是已部署的代理,您可以使用控制台查看代理的指標:

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

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

    清單中會顯示所選專案中已部署的代理。您可以使用「Filter」(篩選器) 欄位,依指定資料欄篩選清單。

  2. 按一下代理程式名稱。系統會顯示所選代理的「資訊主頁」。

  3. 選取下列其中一個「資訊主頁」分頁標籤:

    • 總覽:查看代理指標的摘要資訊主頁,包括代理延遲時間、代理要求數量和代理錯誤率。

    • 模型:查看代理模型指標的資訊主頁,包括模型呼叫次數、模型錯誤率和模型權杖用量。

    • 工具:查看代理工具的指標資訊主頁,包括工具呼叫次數、工具錯誤率和工具延遲時間。

    • 用量:查看代理用量指標的資訊主頁,包括輸入和輸出的權杖用量、容器 CPU 分配和容器記憶體配置。

    • 記錄:如果您已為代理啟用 Cloud Logging,則可查看代理的記錄。

Gemini Enterprise Agent Platform 資訊主頁

緊急停止和撤銷存取權

如果部署的代理行為異常、使用工具的方式不尋常,或涉及安全事件,您可以終止或重新轉送執行階段執行個體,或透過 Agent Gateway 和 Identity and Access Management (IAM) 的政策控管機制撤銷其下游存取權,藉此停止其活動。

由於執行階段作業和政策更新有不同的強制執行模式和傳播時間範圍,請選擇符合事件應變時間要求的控制項。

緊急停止機制和傳播時間

下表比較了停止代理或撤銷其存取權的可用機制、對有效流量的影響,以及預期的傳播時間:

機制 對有效流量和工作階段的影響 一般傳播時間
刪除已部署的代理 (runtimes.delete 或 reasoningEngines.delete) 終止所有執行階段容器執行個體、停止運作中的叫用和串流工作階段 (streamQuery),並永久撤銷代理的 SPIFFE 身分 (principal://...)。 刪除作業完成後立即生效 (通常需要幾秒到幾分鐘)。
重新規劃修訂版本流量或封存修訂版本 (trafficSplitManual 或 agent_gateway_config) 將傳送至根 Agent Endpoint 的流量 100% 轉移至已知良好的有效修訂版本,或在更新 spec.deployment_spec.agent_gateway_config 時封存現有修訂版本。直接傳送至特定有效修訂版本資源路徑的要求,會持續傳送至該修訂版本封存或刪除為止。 更新作業會在幾秒到幾分鐘內完成。
在 Agent Gateway 的統一存取政策 (UAP) 中套用拒絕規則 (iamEnforcementMode: "ENFORCE") 封鎖透過 Agent Gateway 轉送的傳出工具呼叫、Model Context Protocol (MCP) 要求和代理對代理呼叫,同時保持執行階段容器運作,以便檢查。在新的授權檢查中評估;除非重新授權,否則不會強制終止開啟的串流連線。 最終一致:通常會在 2 分鐘內生效,但可能需要 7 分鐘以上才能在全球生效。群組或principalSet成員資格更新作業可能需要幾分鐘到幾小時才能同步處理。
套用 IAM 拒絕政策、撤銷 IAM 角色,或繫結主體存取邊界政策 封鎖代理身分或附加的服務帳戶呼叫 Google Cloud API 和資源。系統會評估每項 API 要求,但不會終止執行階段容器本身。 最終一致:通常會在 2 分鐘內生效,最多可能需要 7 分鐘以上 (請參閱「存取權變更傳播」)。

執行緊急停止

如要立即停止遭入侵或行為不當的代理,並防止進一步的下游動作,請完成下列步驟:

  1. 停止執行中的執行階段或隔離流量:
    • 完全終止 (終止參數):如要立即停止所有執行中的容器,並撤銷代理的 SPIFFE 身分,請使用 Google Cloud 控制台、Agent Platform SDK 中的client.runtimes.delete(name="RESOURCE_NAME", force=True),或reasoningEngines.delete REST 方法,刪除已部署的代理。
    • 不刪除代理,直接復原流量:如要保留代理資源和其身分,同時停止傳送流量至有問題的版本,請使用 trafficSplitManual 更新代理,將 100% 的根流量轉送至已知良好的版本,或更新 spec.deployment_spec.agent_gateway_config 來封存現有版本。如果呼叫端直接叫用修訂版本資源路徑,請刪除或封存該特定修訂版本。如需操作說明,請參閱「管理修訂版本和流量」。
  2. 撤銷下游工具和資源的存取權:
    • 如要透過 Agent Gateway 封鎖傳出的工具和 MCP 伺服器呼叫,請在繫結至閘道的 UAP 中,為代理的 principal:// 或 principalSet:// 識別碼新增 DENY 規則,並確認 iamEnforcementMode 設為 "ENFORCE"。如需操作說明,請參閱「設定 IAM 政策來控管代理程式存取權」。
    • 如要封鎖直接 Google Cloud API 呼叫,請撤銷授予代理身分或其自訂服務帳戶的 IAM 角色,或附加 IAM 拒絕政策或主體存取邊界政策。
  3. 考量傳播時間並確認圍堵成效:
    • 如果代理正在執行非預期的工具呼叫,請勿只依賴 IAM 或 UAP 政策更新。政策變更需要 2 到 7 分鐘 (principalSet 更新則需要更長時間) 才會在全球生效。請務必搭配執行階段刪除或修訂版本流量重新轉送作業,撤銷政策,才能立即停止。
    • 在 Cloud Logging 中查詢 is_agentic=true 和 networkservices.googleapis.com/gateway_requests 拒絕,確認代理程式活動已停止。如要進一步瞭解記錄擷取和安全性發現項目延遲時間,請參閱「稽核代理動作」和「透過 Agent Gateway 監控流量」。

刪除已部署的代理

從 Agent Runtime 代管執行階段刪除已部署的代理。刪除 Agent Runtime 後,Agent Identity 就會失效。任何向該主體授予權限的 IAM 統一存取政策 (UAP),都會在規則中保留已停用的主體。此外,政策繫結仍會保持有效。如要移除失效的主體,請更新 UAP,從規則中移除該主體。如果政策不再包含任何有效主體,請刪除政策繫結。

控制台

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

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

  2. 在指定代理,按一下「更多動作」選單 ()。

  3. 點選「刪除」。

  4. 按一下「Delete agent」(刪除代理)。

Agent Platform SDK

如果您已部署代理程式執行個體 (remote_agent),可以執行下列指令:

remote_agent.delete(
    force=True, # Optional, if the agent has resources (e.g. sessions, memory)
)

或者,您也可以呼叫 runtimes.delete(),按照下列方式刪除與 RESOURCE_NAME 對應的已部署代理:

import agentplatform

client = agentplatform.Client(  # For service interactions via client.runtimes
    project="PROJECT_ID",
    location="LOCATION",
)

client.runtimes.delete(
    name=RESOURCE_NAME,
    force=True, # Optional, if the agent has resources (e.g. sessions, memory)
)

REST

呼叫 reasoningEngines.delete 方法。

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

  • PROJECT_ID:您的 GCP 專案 ID
  • LOCATION:支援的地區
  • RESOURCE_ID:已部署代理的資源 ID

HTTP 方法和網址:

DELETE https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID

請展開以下其中一個選項,以傳送要求:

您應該會收到執行成功的狀態碼 (2xx) 和空白回應。

後續步驟

指南

使用代理與 Agent Platform 執行階段。