在 Gemini Enterprise Agent Platform,您可以建立代理的不可變版本,也就是修訂版本。接著,您可以在不同的有效修訂版本之間分配流量。您可以透過流量拆分功能,測試並逐步增加新修訂版本的流量,以及基於其他目的拆分修訂版本之間的流量。
建立修訂版本的功能一律啟用。您不必開啟這項功能。如要瞭解如何建立修訂版本,請參閱「修訂版本和狀態」。
如果您尚未建立任何修訂版本,則必須先建立修訂版本,才能查看修訂版本並設定修訂版本之間的流量,如本頁所述。
目前,您可以透過 v1beta1 API 使用修訂版本和流量拆分功能。
本頁面說明如何管理代理修訂版本和流量拆分。
修訂版本和狀態
修訂版本是代理的快照。建立代理或更新其版本欄位時,系統會建立代理的不可變動修訂版本。如果修訂版本可供查詢,則為「Active」。請注意,視流量設定而定,該版本可能不會收到任何查詢。修訂版本一經封存,就會永久停止處理流量,且無法還原。封存的修訂版本僅供參考。
您可以透過資源名稱識別修訂版本,只要列出代理修訂版本,即可找到資源名稱。
修訂版本限制
封存的修訂版本不會再占用修訂版本運算單元。變更 Agent Gateway 繫結會封存所有現有修訂版本 (請參閱「Agent Gateway 和修訂版本」),因此變更繫結會釋出配額,而非消耗配額。封存的修訂版本仍可刪除。
有版本和無版本的欄位
本節列出已部署代理的 ReasoningEngineSpec 定義欄位,您可以更新這些欄位,建立代理修訂版本。
更新版本欄位時,系統會建立新的修訂版本。
更新無版本欄位或代理定義中有版本欄位以外的欄位時,代理的所有修訂版本都會更新。
版本欄位如下:
- PackageSpec
pickleObjectGcsUridependencyFilesGcsUrirequirementsGcsUripythonVersion
- DeploymentSpec
env[]secretEnv[]firstPartyImageOverrideagentServerModepscInterfaceConfigminInstancesmaxInstancesresourceLimitscontainerConcurrency
classMethods[]agentFramework- SourceCodeSpec
sourcelanguageSpec
identityTypeagentCard[]
列出代理修訂版本
您可以列出已部署代理的所有修訂版本。
如要查看代理程式的資源 ID,請參閱「取得代理程式資源 ID」。
控制台
在 Agent Platform,依序前往「Govern」>「Deployments」。
按一下代理程式名稱。
選取「修訂版本」分頁標籤。
頁面頂端會顯示修訂版本的相關資訊:
- 分割模式:可設為「手動」或「最新」。詳情請參閱「管理修訂版本的流量」。
- 有效修訂版本:有效修訂版本數量與修訂版本總數的比較。
- 最新修訂版本:最新修訂版本的名稱,以及該版本接收的流量百分比。
- 主要修訂版本:主要修訂版本的名稱,會接收大部分流量。
清單會顯示代理的所有修訂版本,並包含下列資訊:
- 名稱:修訂版本名稱或編號。
- State:修訂版本的狀態。
- 流量:轉送至修訂版本的流量百分比。
- 建立時間:建立修訂版本的日期和時間。
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:您的 Google Cloud 專案 IDLOCATION:支援的地區RESOURCE_ID:已部署代理的資源 ID
REST
呼叫 reasoningEngineRuntimeRevisions.list 方法。
使用任何要求資料之前,請先修改下列項目的值:
PROJECT_ID:您的 Google Cloud 專案 IDLOCATION:支援的地區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"
}...
]
}取得修訂版本的詳細資料
您可以擷取特定修訂版本的詳細資料。
控制台
依序前往「Govern」>「Deployments」。
按一下代理程式名稱。
前往「修訂版本」分頁。
在修訂版本詳細資料頁面,按一下「Revision name」(修訂版本名稱)。
這個畫面會顯示修訂版本的相關資訊,包括建立時間和狀態。
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:您的 Google Cloud 專案 IDLOCATION:支援的地區RESOURCE_ID:已部署代理的資源 IDREVISION_ID:特定執行階段修訂版本的專屬 ID
REST
呼叫 reasoningEngineRuntimeRevisions.get 方法。
使用任何要求資料之前,請先修改下列項目的值:
PROJECT_ID:您的 Google Cloud 專案 IDLOCATION:支援的地區RESOURCE_ID:已部署代理的資源 IDREVISION_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.
控制台
如要設定流量管理,請按照下列步驟操作:
依序前往「Govern」>「Deployments」。
按一下代理程式名稱。
前往「修訂版本」分頁。
在修訂版本詳細資料頁面,按一下「管理流量」。
在「分割模式」下方,選取下列其中一個選項:
- 手動:指定要分配給各修訂版本的流量百分比。
- 一律為最新版本:在這種情況下,100% 的流量會導向最新 (最近建立) 的修訂版本。
選取「儲存」即可儲存變更。
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:您的 Google Cloud 專案 IDLOCATION:支援的地區RESOURCE_ID:已部署代理的資源 IDREVISION_ID_1:第一個修訂版本的 IDREVISION_ID_2:第二個修訂版本的修訂版本 ID
REST
如要將流量一律導向最新修訂版本 (預設),請使用 traffic_config 欄位更新 ReasoningEngine 資源,並指定 trafficSplitAlwaysLatest:
{
"trafficConfig": {
"trafficSplitAlwaysLatest": {}
}
}
如要在代理程式的執行階段修訂版本之間分配流量,請使用 traffic_config 欄位更新 ReasoningEngine 資源,並提供流量目標清單及其各自的百分比。以下說明如何設定在兩個修訂版本之間手動分割流量。
使用任何要求資料之前,請先修改下列項目的值:
PROJECT_ID:您的 Google Cloud 專案 IDLOCATION:支援的地區RESOURCE_ID:已部署代理的資源 IDREVISION_ID_1:第一個修訂版本的 IDREVISION_ID_2:第二個修訂版本的修訂版本 IDTRAFFIC_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:您的 Google Cloud 專案 IDLOCATION:支援的地區RESOURCE_ID:已部署代理的資源 IDREVISION_ID:特定執行階段修訂版本的專屬 ID
REST
呼叫 reasoningEngineRuntimeRevisions.query 方法。
使用任何要求資料之前,請先修改下列項目的值:
PROJECT_ID:您的 Google Cloud 專案 IDLOCATION:支援的地區RESOURCE_ID:已部署代理的資源 IDREVISION_ID:特定執行階段修訂版本的專屬 ID
HTTP 方法和網址:
POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID:query
請展開以下其中一個選項,以傳送要求:
Agent Gateway 和修訂版本
在代理上附加、變更或卸載 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.
如要變更使用手動流量拆分的代理閘道,請按照下列步驟操作:
- 設定
traffic_config.traffic_split_always_latest(或清除traffic_config),切換至一律使用最新版本的轉送方式。請參閱「設定修訂版本之間的流量分配」。 - 變更
spec.deployment_spec.agent_gateway_config。系統會建立新修訂版本,並封存所有先前的修訂版本。 - 如需再次手動分割,請根據變更繫結後建立的版本進行。
您仍可透過 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 是硬性配額,無法提高。
手動刪除
您可以手動刪除代理修訂版本。您只能刪除未用於流量管理的修訂版本,因為這些版本未設定為接收流量。如要瞭解如何設定修訂版本是否接收流量,請參閱「設定修訂版本之間的流量分配」。
控制台
如要刪除代理的修訂版本,請按照下列步驟操作:
依序前往「Govern」>「Deployments」。
按一下代理程式名稱。
前往「修訂版本」分頁。
在修訂版本詳細資料頁面,按一下「Revision name」(修訂版本名稱)。
找出要移除的修訂版本所在資料列。
按一下「刪除」 (垃圾桶) 圖示。
在系統提示時,確認刪除修訂版本。
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:您的 Google Cloud 專案 IDLOCATION:支援的地區RESOURCE_ID:已部署代理的資源 IDREVISION_ID:特定執行階段修訂版本的專屬 ID
REST
呼叫 reasoningEngineRuntimeRevisions.delete 方法。
使用任何要求資料之前,請先修改下列項目的值:
PROJECT_ID:您的 Google Cloud 專案 IDLOCATION:支援的地區RESOURCE_ID:已部署代理的資源 IDREVISION_ID:特定執行階段修訂版本的專屬 ID
HTTP 方法和網址:
DELETE https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID
請展開以下其中一個選項,以傳送要求: