在 Gemini Enterprise Agent Platform 中,您可以创建智能体的不可变版本,即修订版本。然后,您可以在不同的有效修订版本之间分配流量。借助流量分配功能,您可以测试新修订版本并逐步增加其流量,以及出于其他目的在修订版本之间分配流量。
创建修订版本的功能始终处于启用状态。您无需开启该功能。如需了解如何创建修订版本,请参阅修订版本和状态。
如果您尚未创建任何修订版本,则需要先创建修订版本,然后才能查看修订版本并配置它们之间的流量,如本页所述。
目前,您可以通过 v1beta1 API 使用修订版本和流量分配功能。
本页面介绍了如何管理智能体修订版本和流量分配。
修订版本和状态
修订版本是智能体的快照。当您创建智能体或更新其版本化字段时,系统会创建该智能体的一个不可变修订版本。当修订版本可用于查询时,其状态为活跃。请注意,根据流量配置,它可能不会收到任何查询。修订版本归档后,将永久停止处理流量,且无法恢复。已归档的修订版本仅保留用于查阅历史记录。
您可以使用修订版本的资源名称来标识修订版本,该名称可通过列出代理修订版本找到。
修订版本限制
归档的修订版本会停止占用修订版本槽。更改 Agent Gateway 绑定会归档每个预先存在的修订版本(请参阅 Agent Gateway 和修订版本),因此绑定更改会释放配额,而不是消耗配额。已归档的修订版本仍可删除。
版本化和非版本化字段
本部分列出了已部署智能体的 ReasoningEngineSpec 定义中可更新的字段,以便创建智能体的修订版本。
当您更新版本字段时,系统会创建一个新的修订版本。
当您更新无版本字段或代理定义中除有版本字段以外的字段时,代理的所有修订版本都会更新。
以下是版本化字段:
- PackageSpec
pickleObjectGcsUridependencyFilesGcsUrirequirementsGcsUripythonVersion
- DeploymentSpec
env[]secretEnv[]firstPartyImageOverrideagentServerModepscInterfaceConfigminInstancesmaxInstancesresourceLimitscontainerConcurrency
classMethods[]agentFramework- SourceCodeSpec
sourcelanguageSpec
identityTypeagentCard[]
列出智能体修订版本
您可以列出已部署代理的所有修订版本。
如需查找智能体的资源 ID,请参阅获取智能体资源 ID。
控制台
在 Agent Platform 中,依次前往治理 > 部署。
点击代理的名称。
选择修订版本标签页。
页面顶部会显示以下修订版本信息:
- 拆分模式:可以是“手动”或“最新”。如需了解详情,请参阅“管理流向修订版本的流量”。
- 有效修订版本:有效修订版本数量与修订版本总数的对比。
- 最新修订版本:最新修订版本的名称及其接收的流量百分比。
- 主要修订版本:主要修订版本的名称,该修订版本接收大部分流量。
该列表会显示代理的所有修订版本,并包含以下信息:
- 名称:修订版本名称或编号。
- 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"
}...
]
}获取修订版本的详细信息
您可以检索特定修订版本的详细信息。
控制台
前往治理 > 部署。
点击代理的名称。
前往修订版本标签页。
在修订版本详情页面上,点击修订版本名称。
此屏幕会显示有关修订版本的信息,包括创建时间和状态。
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.
控制台
如需配置流量管理,请执行以下操作:
前往治理 > 部署。
点击代理的名称。
前往修订版本标签页。
在修订版本详情页面上,点击管理流量。
在拆分模式下,选择以下选项之一:
- 手动:指定要分配给每个修订版本的流量百分比。
- 始终最新:在这种情况下,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 是无法提高的硬性配额。
手动删除
您可以通过删除代理修订版本来手动移除该修订版本。您只能删除未处于流量管理活跃状态的修订版本,因为这些修订版本未配置为接收流量。如需了解如何配置修订版本是否接收流量,请参阅配置修订版本之间的流量分配。
控制台
如需删除代理的修订版本,请执行以下操作:
前往治理 > 部署。
点击代理的名称。
前往修订版本标签页。
在修订版本详情页面上,点击修订版本名称。
找到要移除的修订版本所在的行。
点击删除(垃圾箱)图标。
出现提示时,确认删除修订版本。
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
如需发送您的请求,请展开以下选项之一: