在 Gemini Enterprise Agent Platform 中,您可以创建智能体的不可变版本,即修订版本。然后,您可以在不同的有效修订版本之间拆分流量。借助流量拆分,您可以测试新修订版本并逐步增加其流量,还可以出于其他目的在修订版本之间拆分流量。
创建修订版本的功能始终处于启用状态。您无需开启此功能。如需了解如何创建修订版本,请参阅修订版本和状态。
如果您尚未创建任何修订版本,则需要先创建修订版本,然后才能查看修订版本并配置它们之间的流量,如本页所述。
目前,您可以通过 v1beta1 API 使用修订版本和流量拆分功能。
本页介绍了如何管理代理版本和流量拆分。
修订版本和状态
修订版本是智能体的快照。创建代理或更新代理的版本化字段时,系统会创建代理的不可变修订版本。当修订版本可用于查询时,即为有效。请注意,根据流量配置,它可能不会接收任何查询。修订版本归档后,将永久停止处理流量,并且无法恢复。归档的修订版本仅保留用于历史参考。
您可以使用修订版本的资源名称来标识修订版本,该名称可通过列出智能体修订版本来查找。
修订版本限制
归档的修订版本不再占用修订版本槽位。更改 Agent Gateway 绑定会归档每个预先存在的修订版本(请参阅Agent Gateway 和修订版本),因此绑定更改会释放配额,而不是消耗配额。归档的修订版本仍可删除。
已纳入版本控制和未纳入版本控制的字段
本部分列出了已部署的代理的 ReasoningEngineSpec 定义中可更新的字段,您可以通过更新这些字段来创建代理的修订版本。
当您更新受版本控制的字段时,系统会创建新的修订版本。
当您更新代理定义中的无版本字段或除有版本字段之外的字段时,该代理的所有修订版本都会更新。
以下是已纳入版本控制的字段:
- PackageSpec
pickleObjectGcsUridependencyFilesGcsUrirequirementsGcsUripythonVersion
- DeploymentSpec
env[]secretEnv[]firstPartyImageOverrideagentServerModepscInterfaceConfigminInstancesmaxInstancesresourceLimitscontainerConcurrency
classMethods[]agentFramework- SourceCodeSpec
sourcelanguageSpec
identityTypeagentCard[]
列出代理修订版本
您可以列出已部署代理的所有修订版本。
如需查找智能体的资源 ID,请参阅获取智能体资源 ID。
控制台
在 Google Agent Platform 中,依次前往 Govern > Deployments。
点击代理的名称。
选择修订版本标签页。
页面顶部会显示有关修订版本的以下信息:
- 拆分模式:可以是“手动”或“最新”。如需了解详情,请参阅“管理向修订版本的流量”。
- 有效修订版本:有效修订版本的数量与修订版本总数的比较。
- 最新修订版本:最新修订版本的名称及其接收的流量百分比。
- 主要修订版本:接收大部分流量的主要修订版本的名称。
该列表会显示代理的所有修订版本,并包含以下信息:
- 名称:修订版本名称或编号。
- 状态:修订版本的状态。
- 流量:路由到相应修订版本的流量百分比。
- 创建时间:修订版本的创建日期和时间。
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 项目 IDLOCATION:支持的区域RESOURCE_ID:已部署代理的资源 ID
REST
调用 reasoningEngineRuntimeRevisions.list 方法。
在使用任何请求数据之前,请先进行以下替换:
PROJECT_ID:您的 Cloud de Confiance by S3NS 项目 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:您的 Cloud de Confiance by S3NS 项目 IDLOCATION:支持的区域RESOURCE_ID:已部署代理的资源 IDREVISION_ID:特定运行时修订版本的唯一 ID
REST
调用 reasoningEngineRuntimeRevisions.get 方法。
在使用任何请求数据之前,请先进行以下替换:
PROJECT_ID:您的 Cloud de Confiance by S3NS 项目 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:您的 Cloud de Confiance by S3NS 项目 IDLOCATION:支持的区域RESOURCE_ID:已部署代理的资源 IDREVISION_ID_1:第一个修订版本的修订版本 IDREVISION_ID_2:第二个修订版本的修订版本 ID
REST
如需将流量配置为始终流向最新修订版本(默认),请使用 traffic_config 字段更新 ReasoningEngine 资源,并指定 trafficSplitAlwaysLatest:
{
"trafficConfig": {
"trafficSplitAlwaysLatest": {}
}
}
如需在代理的运行时修订版本之间分配流量,请使用 traffic_config 字段更新 ReasoningEngine 资源,并提供流量目标列表及其各自的百分比。以下示例展示了如何跨两个修订版本设置手动拆分。
在使用任何请求数据之前,请先进行以下替换:
PROJECT_ID:您的 Cloud de Confiance by S3NS 项目 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:您的 Cloud de Confiance by S3NS 项目 IDLOCATION:支持的区域RESOURCE_ID:已部署代理的资源 IDREVISION_ID:特定运行时修订版本的唯一 ID
REST
调用 reasoningEngineRuntimeRevisions.query 方法。
在使用任何请求数据之前,请先进行以下替换:
PROJECT_ID:您的 Cloud de Confiance by S3NS 项目 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:您的 Cloud de Confiance by S3NS 项目 IDLOCATION:支持的区域RESOURCE_ID:已部署代理的资源 IDREVISION_ID:特定运行时修订版本的唯一 ID
REST
调用 reasoningEngineRuntimeRevisions.delete 方法。
在使用任何请求数据之前,请先进行以下替换:
PROJECT_ID:您的 Cloud de Confiance by S3NS 项目 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
如需发送您的请求,请展开以下选项之一: