管理修订版本和流量

在 Gemini Enterprise Agent Platform 中，您可以创建智能体的不可变版本，即修订版本。然后，您可以在不同的有效修订版本之间拆分流量。借助流量拆分，您可以测试新修订版本并逐步增加其流量，还可以出于其他目的在修订版本之间拆分流量。

创建修订版本的功能始终处于启用状态。您无需开启此功能。如需了解如何创建修订版本，请参阅修订版本和状态。

如果您尚未创建任何修订版本，则需要先创建修订版本，然后才能查看修订版本并配置它们之间的流量，如本页所述。

目前，修订版本和流量拆分可通过 v1beta1 API 使用。

本页介绍了如何管理代理版本和流量拆分。

修订版本和状态

修订版本是智能体的快照。创建代理或更新代理的版本化字段时，系统会创建代理的不可变修订版本。修订版本可具有以下状态：

  • 有效：相应修订版本可用于查询。请注意，根据流量配置，它可能不会接收任何查询。
  • 已弃用：无法查询相应修订版本。

您可以使用修订版本的资源名称来标识修订版本，该名称可通过列出智能体修订版本来查找。

已纳入版本控制和未纳入版本控制的字段

本部分列出了已部署的代理的 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 中，前往治理 > 部署。

    前往“部署”页面

  2. 点击代理的名称。

  3. 选择修订版本标签页。

  4. 页面顶部会显示有关修订版本的以下信息：

    1. 拆分模式：可以是“手动”或“最新”。如需了解详情，请参阅“管理对修订版本的流量”。
    2. 有效修订版本：有效修订版本的数量与修订版本总数的比较。
    3. 最新修订版本：最新修订版本的名称及其接收的流量百分比。
    4. 主要修订版本：接收大部分流量的主要修订版本的名称。

  5. 该列表会显示代理的所有修订版本，并包含以下信息：

    1. 名称：修订版本名称或编号。
    2. 状态：修订版本是已部署还是已弃用。
    3. 流量：路由到相应修订版本的流量百分比。
    4. 创建时间：修订版本的创建日期和时间。

Agent Platform SDK

以下代码列出了指定已部署代理的修订历史记录。如需列出修订版本，您必须确定代理的唯一资源 ID。

import vertexai
from google.genai import types as genai_types

http_options = genai_types.HttpOptions(
    api_version="v1beta1",
)

client = vertexai.Client(
    project="PROJECT_ID",
    location="LOCATION",
    http_options=http_options,
)

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

for revision in revisions:
    print(revision)

替换代码中的以下变量：

  • PROJECT_ID：您的 Google Cloud 项目 ID
  • LOCATION：支持的区域
  • RESOURCE_ID：已部署代理的资源 ID

REST

调用 reasoningEngineRuntimeRevisions.list 方法。

在使用任何请求数据之前，请先进行以下替换：

  • PROJECT_ID：您的 Google Cloud 项目 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"
      }...
    ]
}

获取修订版本的详细信息

您可以检索特定修订版本的详细信息。

Agent Platform SDK

以下代码会检索指定已部署代理修订版本的资源详细信息：

import vertexai
from google.genai import types as genai_types

http_options = genai_types.HttpOptions(
    api_version="v1beta1",
)

client = vertexai.Client(
    project="PROJECT_ID",
    location="LOCATION",
    http_options=http_options,
)

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

print(revision)

替换代码中的以下变量：

  • PROJECT_ID：您的 Google Cloud 项目 ID
  • LOCATION：支持的区域
  • RESOURCE_ID：已部署代理的资源 ID
  • REVISION_ID：特定运行时修订版本的唯一 ID

REST

调用 reasoningEngineRuntimeRevisions.get 方法。

在使用任何请求数据之前，请先进行以下替换：

  • PROJECT_ID：您的 Google Cloud 项目 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% 的流量会重定向到该修订版本）。

  • 到最新修订版本：所有流量都定向到最新修订版本。创建新的代理修订版本后，流量会自动定向到该新修订版本。

控制台

如需配置流量管理，请执行以下操作：

  1. 前往治理 > 部署。

    前往“部署”页面

  2. 点击代理的名称。

  3. 前往修订版本标签页。

  4. 在修订版本详情页面上，点击管理流量。

  5. 在拆分模式下，选择以下选项之一：

    1. 手动：指定分配给每个修订版本的流量百分比。
    2. 始终为最新版本：在这种情况下，100% 的流量会流向最新（最近创建）的修订版本。

  6. 选择保存以保存更改。

Agent Platform SDK

以下代码展示了如何配置基于百分比的流量分配。

import vertexai
from google.genai import types as genai_types

http_options = genai_types.HttpOptions(
    api_version="v1beta1",
)

client = vertexai.Client(
    project="PROJECT_ID",
    location="LOCATION",
    http_options=http_options,
)

client.agent_engines.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 项目 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：您的 Google Cloud 项目 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 vertexai
from google.genai import types as genai_types

http_options = genai_types.HttpOptions(
    api_version="v1beta1",
)

client = vertexai.Client(
    project="PROJECT_ID",
    location="LOCATION",
    http_options=http_options,
)

revision = client.agent_engines.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 项目 ID
  • LOCATION：支持的区域
  • RESOURCE_ID：已部署代理的资源 ID
  • REVISION_ID：特定运行时修订版本的唯一 ID

REST

调用 reasoningEngineRuntimeRevisions.query 方法。

在使用任何请求数据之前，请先进行以下替换：

  • PROJECT_ID：您的 Google Cloud 项目 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

如需发送您的请求，请展开以下选项之一：

 

监控修订版本

通过在日志中将修订版本号作为元数据进行跟踪，监控修订版本中的活动和问题。如需了解如何设置日志记录，请参阅设置日志记录。

更新修订版本

按照更新已部署的代理中的说明更新已部署的代理。您可以更新已纳入版本控制或未纳入版本控制的字段。如果您更新受版本控制的字段，则会创建新的修订版本。

删除代理修订版本

您可以通过删除代理修订版本来移除该版本。您只能删除未处于流量管理活动状态的修订版本，因为这些版本已被弃用或未配置为接收流量。如需了解如何配置修订版本是否接收流量，请参阅配置修订版本之间的流量分配。

控制台

如需删除代理的修订版本，请执行以下操作：

  1. 前往治理 > 部署。

    前往“部署”页面

  2. 点击代理的名称。

  3. 前往修订版本标签页。

  4. 在修订版本详情页面上，点击修订版本名称。

  5. 找到要移除的修订版本所在的行。

  6. 点击删除（回收站）图标。

  7. 出现提示时，确认删除相应修订版本。

Agent Platform SDK

以下代码会删除指定的代理修订版本：

import vertexai
from google.genai import types as genai_types

http_options = genai_types.HttpOptions(
    api_version="v1beta1",
)

client = vertexai.Client(
    project="PROJECT_ID",
    location="LOCATION",
    http_options=http_options,
)

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

替换代码中的以下变量：

  • PROJECT_ID：您的 Google Cloud 项目 ID
  • LOCATION：支持的区域
  • RESOURCE_ID：已部署代理的资源 ID
  • REVISION_ID：特定运行时修订版本的唯一 ID

REST

调用 reasoningEngineRuntimeRevisions.delete 方法。

在使用任何请求数据之前，请先进行以下替换：

  • PROJECT_ID：您的 Google Cloud 项目 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

如需发送您的请求，请展开以下选项之一：

 

限制

  • 对于使用修订版本的 Agent Runtime 代理，不支持 Agent Gateway。 如果 Agent Gateway 附加到智能体的配置，您将无法使用与版本控制相关的功能，例如流量拆分配置和按修订版本查询。