管理修訂版本和流量

在 Gemini Enterprise Agent Platform 中，您可以建立代理的不可變更版本，也就是修訂版本。然後將流量分配給不同的有效修訂版本。流量拆分功能可讓您測試新修訂版本，並逐步增加流量，還能基於其他目的拆分修訂版本之間的流量。

建立修訂版本的功能一律會啟用。不必開啟這項功能。如要瞭解如何建立修訂版本，請參閱「修訂版本和狀態」。

如果您尚未建立任何修訂版本，就必須先建立修訂版本，才能查看修訂版本並設定修訂版本之間的流量，如本頁所述。

目前只能透過 v1beta1 API 使用修訂版本和流量分配功能。

本頁說明如何管理代理程式修訂版本和流量分配。

修訂版本和狀態

修訂版本是代理的快照。建立代理程式或更新代理程式的版本化欄位時，系統會建立代理程式的不可變更修訂版本。修訂版本可供查詢時，狀態為「有效」。請注意，視流量設定而定，該伺服器可能不會收到任何查詢。修訂版本封存後，就會永久停止處理流量，且無法還原。封存的修訂版本只會保留做為歷史參考資料。

您可以透過修訂版本的資源名稱識別修訂版本，方法是列出代理程式修訂版本。

修訂版本限制

封存的修訂版本不會再占用修訂版本位置。變更 Agent Gateway 繫結會封存所有先前版本 (請參閱「Agent Gateway 和修訂版本」)，因此變更繫結會釋出配額，而非消耗配額。封存的修訂版本仍可刪除。

有版本和無版本的欄位

本節列出已部署代理的 ReasoningEngineSpec 定義中的欄位，您可以更新這些欄位來建立代理的修訂版本。

更新版本化欄位時，系統會建立新的修訂版本。

更新未版本化的欄位，或代理程式定義中版本化欄位以外的欄位時，代理程式的所有修訂版本都會更新。

以下是已納入版本控管的欄位：

  • PackageSpec
    • pickleObjectGcsUri
    • dependencyFilesGcsUri
    • requirementsGcsUri
    • pythonVersion
  • DeploymentSpec
    • env[]
    • secretEnv[]
    • firstPartyImageOverride
    • agentServerMode
    • pscInterfaceConfig
    • minInstances
    • maxInstances
    • resourceLimits
    • containerConcurrency
  • classMethods[]
  • agentFramework
  • SourceCodeSpec
    • source
    • languageSpec
  • identityType
  • agentCard[]

列出代理程式修訂版本

您可以列出已部署代理的所有修訂版本。

如要找出代理程式的資源 ID，請參閱「取得代理程式資源 ID」。

控制台

  1. 在 Google Agent Platform 中，依序前往「Govern」>「Deployments」。

    前往「Deployments」(部署作業)

  2. 按一下代理程式的名稱。

  3. 選取「修訂版本」分頁標籤。

  4. 頁面頂端會顯示修訂版本的相關資訊：

    1. 分割模式：可選擇「手動」或「最新」。詳情請參閱「管理修訂版本的流量」。
    2. 有效修訂版本：有效修訂版本數與修訂版本總數的比較結果。
    3. 最新修訂版本：最新修訂版本的名稱，以及接收的流量百分比。
    4. 主要修訂版本：主要修訂版本的名稱，會接收大部分流量。

  5. 清單會顯示代理的所有修訂版本，包括下列資訊：

    1. 名稱：修訂版本名稱或編號。
    2. 狀態：修訂版本的狀態。
    3. 流量：轉送至修訂版本的流量百分比。
    4. 建立時間：修訂版本的建立日期和時間。

Agent Platform SDK

下列程式碼會列出指定已部署代理程式的修訂版本記錄。如要列出修訂版本，您必須找出代理商的專屬資源 ID。

import agentplatform

client = agentplatform.Client(
    project="PROJECT_ID",
    location="LOCATION",
    http_options={"api_version": "v1beta1"},
)

revisions = client.runtimes.revisions.list(
    name="projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID"
)

for revision in revisions:
    print(revision)

請替換程式碼中的下列變數：

  • PROJECT_ID：您的 Cloud de Confiance by S3NS 專案 ID
  • LOCATION：支援的地區
  • RESOURCE_ID：已部署代理程式的資源 ID

REST

呼叫 reasoningEngineRuntimeRevisions.list 方法。

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

  • PROJECT_ID：您的 Cloud de Confiance by S3NS 專案 ID
  • LOCATION：支援的地區
  • RESOURCE_ID：已部署代理程式的資源 ID。

HTTP 方法和網址：

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

請展開以下其中一個選項，以傳送要求：

您應該會收到如下的 JSON 回覆：

{
  "reasoningEngineRuntimeRevisions": [
      {
        "name": "projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID",
        "spec": {
          // Revision-specific config attributes (e.g., package specs, requirements)
        },
        "createTime": "2026-05-01T13:26:01Z",
        "state": "ACTIVE"
      }...
    ]
}

取得修訂版本的詳細資料

您可以擷取特定修訂版本的詳細資料。

控制台

  1. 依序前往「控管」>「部署作業」。

    前往「Deployments」(部署作業)

  2. 按一下代理程式的名稱。

  3. 前往「修訂版本」分頁。

  4. 在修訂版本詳細資料頁面中，按一下「修訂版本名稱」。

  5. 這個畫面會顯示修訂版本資訊，包括建立時間和狀態。

Agent Platform SDK

以下程式碼會擷取指定已部署代理程式修訂版本的資源詳細資料：

import agentplatform

client = agentplatform.Client(
    project="PROJECT_ID",
    location="LOCATION",
    http_options={"api_version": "v1beta1"},
)

revision = client.runtimes.revisions.get(
    name="projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID"
)

print(revision)

請替換程式碼中的下列變數：

  • PROJECT_ID：您的 Cloud de Confiance by S3NS 專案 ID
  • LOCATION：支援的地區
  • RESOURCE_ID：已部署代理程式的資源 ID
  • REVISION_ID：特定執行階段修訂版本的專屬 ID

REST

呼叫 reasoningEngineRuntimeRevisions.get 方法。

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

  • PROJECT_ID：您的 Cloud de Confiance by S3NS 專案 ID
  • LOCATION：支援的地區
  • RESOURCE_ID：已部署代理程式的資源 ID
  • REVISION_ID：特定執行階段修訂版本的專屬 ID

HTTP 方法和網址：

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID

請展開以下其中一個選項，以傳送要求：

您應該會收到如下的 JSON 回覆：

{
  "name": "projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID",
  "spec": {
    // Revision-specific config attributes (e.g., package specs, requirements)
  },
  "createTime": "2026-05-06T13:05:24Z",
  "state": "ACTIVE"
}

設定修訂版本之間的流量分配

您可以管理流量在有效修訂版本之間的分配方式。請注意，只有導向根 reasoningEngine 資源的查詢會進行流量分割。明確將查詢導向特定修訂版本資源路徑，會略過流量規則。

流量分配方式有兩種：

  • 依百分比：依百分比設定時，指定百分比的流量會導向各個代理程式修訂版本。指定的百分比必須是整數。百分比總和必須等於 100%。即使只有 1 個有效修訂版本，您仍可設定流量分配 (將 100% 的流量重新導向該版本)。
  • 最新修訂版本：所有流量都會導向最新修訂版本。建立新的代理程式修訂版本後，流量會自動導向該版本。

手動拆分只能以「有效」修訂版本為目標。為封存的修訂版本命名會傳回 FAILED_PRECONDITION：

Traffic target revision {revision} is not an active revision of this Agent Engine. Update traffic_config to reference only active revisions.

控制台

如要設定流量管理，請按照下列步驟操作：

  1. 依序前往「控管」>「部署作業」。

    前往「Deployments」(部署作業)

  2. 按一下代理程式的名稱。

  3. 前往「修訂版本」分頁。

  4. 在修訂版本詳細資料頁面中，按一下「管理流量」。

  5. 在「分割模式」下方，選取下列任一選項：

    1. 手動：指定各修訂版本要接收的流量百分比。
    2. 一律為最新版本：在這種情況下，100% 的流量都會導向最新 (最近建立) 的修訂版本。

  6. 選取「儲存」即可儲存變更。

Agent Platform SDK

下列程式碼顯示如何設定以百分比為準的流量分配。

import agentplatform

client = agentplatform.Client(
    project="PROJECT_ID",
    location="LOCATION",
    http_options={"api_version": "v1beta1"},
)

client.runtimes.update(
    name="projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID",
    config={
        "traffic_config": {
            "trafficSplitManual": {
                "targets": [
                    {
                        "runtimeRevisionName": "projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID_1",
                        "percent": 50,
                    },
                    {
                        "runtimeRevisionName": "projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID_2",
                        "percent": 50,
                    },
                ]
            }
        }
    },
)

請替換程式碼中的下列變數：

  • PROJECT_ID：您的 Cloud de Confiance by S3NS 專案 ID
  • LOCATION：支援的地區
  • RESOURCE_ID：已部署代理程式的資源 ID
  • REVISION_ID_1：第一個修訂版本的修訂版本 ID
  • REVISION_ID_2：第二個修訂版本的 ID

REST

如要設定流量一律導向最新修訂版本 (預設)，請使用 traffic_config 欄位更新 ReasoningEngine 資源，並指定 trafficSplitAlwaysLatest：

{
  "trafficConfig": {
    "trafficSplitAlwaysLatest": {}
  }
}

如要在代理程式的執行階段修訂版本之間分配流量，請使用 traffic_config 欄位更新 ReasoningEngine 資源，並提供流量目標清單和各自的百分比。以下說明如何跨兩個修訂版本手動設定分割。

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

  • PROJECT_ID：您的 Cloud de Confiance by S3NS 專案 ID
  • LOCATION：支援的地區
  • RESOURCE_ID：已部署代理程式的資源 ID
  • REVISION_ID_1：第一個修訂版本的修訂版本 ID
  • REVISION_ID_2：第二個修訂版本的 ID
  • TRAFFIC_PERCENTAGE_1：第一個修訂版本所需的流量百分比
  • TRAFFIC_PERCENTAGE_2：您希望第二個修訂版本獲得的流量百分比

HTTP 方法和網址：

PATCH https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID?update_mask=traffic_config

JSON 要求主體：

{
  "trafficConfig": {
    "trafficSplitManual": {
      "targets": [
          {
            "runtimeRevisionName": "projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID_1",
            "percent": TRAFFIC_PERCENTAGE_1
          },
          {
            "runtimeRevisionName": "projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID_2",
            "percent": TRAFFIC_PERCENTAGE_2
          }
        ]
      }
    }
}

請展開以下其中一個選項，以傳送要求：

這項要求會啟動長時間執行的作業 (LRO)。一開始，您會收到標準作業回應。設定變更完成後，回覆會顯示 done 並重複您的設定。 
{
  "name": "projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID",
  "done": false
}

查詢特定修訂版本

您可以透過 SDK 或 API 查詢特定修訂版本。修訂版本必須處於有效狀態，才能查詢。將查詢導向特定修訂版本會略過流量分配規則。

Agent Platform SDK

下列程式碼會查詢特定有效修訂版本：

import agentplatform

client = agentplatform.Client(
    project="PROJECT_ID",
    location="LOCATION",
    http_options={"api_version": "v1beta1"},
)

revision = client.runtimes.revisions.get(
    name="projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID"
)

response = revision.query(
    input={"your_input_key": "your_input_value"},
    config={"class_method": "your_class_method"},
)

print(response)

請替換程式碼中的下列變數：

  • PROJECT_ID：您的 Cloud de Confiance by S3NS 專案 ID
  • LOCATION：支援的地區
  • RESOURCE_ID：已部署代理程式的資源 ID
  • REVISION_ID：特定執行階段修訂版本的專屬 ID

REST

呼叫 reasoningEngineRuntimeRevisions.query 方法。

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

  • PROJECT_ID：您的 Cloud de Confiance by S3NS 專案 ID
  • LOCATION：支援的區域
  • RESOURCE_ID：已部署代理程式的資源 ID
  • REVISION_ID：特定執行階段修訂版本的專屬 ID

HTTP 方法和網址：

POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID:query

請展開以下其中一個選項，以傳送要求：

 

Agent Gateway 和修訂版本

在代理程式上附加、變更或卸離代理程式閘道繫結時，系統會建立新的修訂版本，並封存變更前的所有修訂版本。只有新修訂版本會維持「有效」狀態。這項操作無法復原，封存的修訂版本也無法還原。

由於繫結變更會封存所有現有修訂版本，因此只有在所有流量都已傳送至最新修訂版本時，才能進行這項變更。如果設定了任何手動拆分，即使是將 100% 的流量導向最新修訂版本，API 也會拒絕變更。拒絕會傳回 FAILED_PRECONDITION：

Changing spec.deployment_spec.agent_gateway_config archives every existing runtime revision, so it is only allowed while all traffic is on the latest revision. Set traffic_config.traffic_split_always_latest, or clear traffic_config, before changing the Agent Gateway configuration.

如要變更使用手動流量分配的代理程式閘道，請按照下列步驟操作：

  1. 設定 traffic_config.traffic_split_always_latest (或清除 traffic_config)，即可切換至一律採用最新版本的路由。請參閱「設定修訂版本之間的流量分配」。
  2. 變更 spec.deployment_spec.agent_gateway_config。系統會建立新的修訂版本，並封存所有先前的版本。
  3. 如要再次手動分割，請從繫結變更後建立的修訂版本建構。

您仍可透過 API 存取已封存的修訂版本，且系統會保留完整的 ReasoningEngineSpec。如要建立與封存修訂版本相同的新修訂版本，請取得封存修訂版本的詳細資料，並部署具有相同版本化欄位的新修訂版本。重複使用相同的容器映像檔 URI 會產生相同的執行階段；重複使用相同的原始碼位置和類別方法會產生相同的行為。

監控修訂版本

在記錄中追蹤修訂版本號碼 (做為中繼資料)，監控活動和問題的修訂版本。如要瞭解如何設定記錄功能，請參閱「設定記錄功能」。

建立新的代理程式修訂版本

如要建立新的修訂版本，請更新已部署代理程式的版本化欄位。如需操作說明，請參閱「更新已部署的代理程式」。

如果更新版本化欄位，系統會自動建立新修訂版本。如果更新未設版本的欄位，系統會更新代理程式的所有現有修訂版本，不會建立新版本。

管理修訂版本清理作業

Gemini Enterprise Agent Platform 會自動移除舊版修訂內容，協助您維持在修訂內容限制內。你也可以手動刪除修訂版本。

自動垃圾回收

根據預設，Gemini Enterprise Agent Platform 會為所有代理啟用自動垃圾回收功能。你無法停用這項功能。垃圾回收只會在代理程式更新作業中執行，不會以背景工作形式執行。

  • 執行時間：如果更新作業嘗試超出設定的修訂版本限制，Gemini Enterprise Agent Platform 會在建立新修訂版本前，在同一項作業中刪除最舊的適用修訂版本。如果降低上限，Gemini Enterprise Agent Platform 會立即刪除足夠多的最舊合格修訂版本，以符合新上限。
  • 符合資格的修訂版本：修訂版本必須符合下列所有條件，才能刪除：
    • 處於 ACTIVE 狀態。
    • 因此不會納入流量設定 (流量為 0%)。
  • 失敗：如果沒有足夠的合格修訂版本可釋出空間，Gemini Enterprise Agent Platform 會拒絕更新作業，並顯示 FAILED_PRECONDITION 錯誤。不會刪除任何修訂版本或建立新的修訂版本。請先從流量設定中移除修訂版本，或提高限制，再重試。

設定限制

這項限制是由代理程式的 revision_garbage_collection_strategy.keep_n_latest.max_revisions 欄位定義。您可以在建立代理時設定這個欄位，也可以稍後透過更新要求變更。

  • 新代理程式的預設值：100 個修訂版本。
  • 現有代理商的預設值：950 次修訂。
  • 允許的範圍：1 至 950。系統會拒絕 0 或更低的值。由於 950 是無法提高的硬性配額，因此大於 950 的值會遭到拒絕。

手動刪除

您可以刪除代理程式修訂版本，手動移除該版本。您只能刪除未啟用流量管理的修訂版本，因為這些版本未設定為接收流量。如要瞭解如何設定修訂版本是否會接收流量，請參閱「設定修訂版本之間的流量分配」。

控制台

如要刪除代理程式的修訂版本，請按照下列步驟操作：

  1. 依序前往「控管」>「部署作業」。

    前往「Deployments」(部署作業)

  2. 按一下代理程式的名稱。

  3. 前往「修訂版本」分頁。

  4. 在修訂版本詳細資料頁面中，按一下「修訂版本名稱」。

  5. 找到要移除的修訂版本所在的列。

  6. 按一下「刪除」 (垃圾桶) 圖示。

  7. 系統提示時，請確認要刪除修訂版本。

Agent Platform SDK

下列程式碼會刪除指定的代理程式修訂版本：

import agentplatform

client = agentplatform.Client(
    project="PROJECT_ID",
    location="LOCATION",
    http_options={"api_version": "v1beta1"},
)

client.runtimes.revisions.delete(
    name="projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID"
)

請替換程式碼中的下列變數：

  • PROJECT_ID：您的 Cloud de Confiance by S3NS 專案 ID
  • LOCATION：支援的地區
  • RESOURCE_ID：已部署代理程式的資源 ID
  • REVISION_ID：特定執行階段修訂版本的專屬 ID

REST

呼叫 reasoningEngineRuntimeRevisions.delete 方法。

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

  • PROJECT_ID：您的 Cloud de Confiance by S3NS 專案 ID
  • LOCATION：支援的地區
  • RESOURCE_ID：已部署代理程式的資源 ID
  • REVISION_ID：特定執行階段修訂版本的專屬 ID

HTTP 方法和網址：

DELETE https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID

請展開以下其中一個選項，以傳送要求：