Administra revisiones y tráfico

En Gemini Enterprise Agent Platform, puedes crear versiones inmutables, o revisiones, de un agente. Luego, puedes dividir el tráfico entre las diferentes revisiones activas. La división del tráfico te permite probar y aumentar gradualmente el tráfico hacia las revisiones nuevas, y dividir el tráfico entre las revisiones para otros fines.

La capacidad de crear revisiones siempre está habilitada. No es necesario que actives la función. Para obtener información sobre cómo crear revisiones, consulta Estados y revisiones.

Si aún no creaste ninguna revisión, deberás hacerlo antes de poder verlas y configurar el tráfico entre ellas, como se describe en esta página.

Por el momento, las revisiones y la división del tráfico están disponibles a través de la API de v1beta1.

En esta página, se describe cómo administrar las revisiones de agentes y la división del tráfico.

Revisiones y estados

Una revisión es una instantánea de un agente. Cuando creas un agente o actualizas sus campos versionados, se crea una revisión inmutable del agente. Una revisión puede tener los siguientes estados:

  • Activa: La revisión está disponible para las búsquedas. Ten en cuenta que es posible que no reciba ninguna búsqueda, según la configuración del tráfico.
  • Obsoleto: No se puede consultar la revisión.

Puedes identificar una revisión con su nombre de recurso, que se puede encontrar enumerando las revisiones del agente.

Campos con versiones y sin versiones

En esta sección, se enumeran los campos de la definición de ReasoningEngineSpec de un agente implementado que puedes actualizar para crear una revisión del agente.

Cuando actualizas los campos con versiones, se crea una revisión nueva.

Cuando actualizas campos sin versiones o campos en la definición de un agente que no sean los campos con versiones, el agente se actualiza en todas sus revisiones.

Estos son los campos versionados:

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

Enumera las revisiones de agentes

Puedes enumerar todas las revisiones de un agente implementado, tanto las activas como las obsoletas.

Para encontrar el ID de recurso de tu agente, consulta Cómo obtener el ID de recurso del agente.

Console

  1. En Google Agent Platform, ve a Govern > Deployments.

    Ir a Implementaciones

  2. Haz clic en el nombre del agente.

  3. Selecciona la pestaña Revisiones.

  4. En la parte superior de la página, se muestra la siguiente información sobre las revisiones:

    1. Modo de división: Puede ser "Manual" o "Más reciente". Consulta "Administra el tráfico a las revisiones" para obtener más información.
    2. Revisiones activas: Es la cantidad de revisiones activas en comparación con la cantidad total de revisiones.
    3. Revisión más reciente: Es el nombre de la revisión más reciente y el porcentaje de tráfico que recibe.
    4. Revisión principal: Es el nombre de la revisión principal, que recibe la mayor parte del tráfico.

  5. En la lista, se muestran todas las revisiones del agente y se incluye la siguiente información:

    1. Nombre: Es el nombre o número de la revisión.
    2. Estado: Indica si la revisión se implementó o está obsoleta.
    3. Tráfico: Es el porcentaje de tráfico que se dirige a la revisión.
    4. Creado: La fecha y la hora en que se creó la revisión.

SDK de Agent Platform

El siguiente código enumera el historial de revisiones de un agente implementado específico. Para enumerar las revisiones, debes identificar el ID de recurso único de tu agente.

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)

Reemplaza las siguientes variables en el código:

  • PROJECT_ID: ID del proyecto de Google Cloud
  • LOCATION: una región admitida
  • RESOURCE_ID: Es el ID del recurso del agente implementado.

REST

Llama al método reasoningEngineRuntimeRevisions.list.

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • PROJECT_ID: ID del proyecto de Google Cloud
  • LOCATION: una región admitida
  • RESOURCE_ID: Es el ID del recurso del agente implementado.

Método HTTP y URL: 

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

Para enviar tu solicitud, expande una de estas opciones:

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

{
  "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"
      }...
    ]
}

Obtén los detalles de una revisión

Puedes recuperar los detalles de una revisión específica.

SDK de Agent Platform

El siguiente código recupera los detalles del recurso para una revisión del agente implementado especificada:

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)

Reemplaza las siguientes variables en el código:

  • PROJECT_ID: ID del proyecto de Google Cloud
  • LOCATION: una región admitida
  • RESOURCE_ID: Es el ID del recurso del agente implementado.
  • REVISION_ID: Es el ID único de una revisión específica del entorno de ejecución.

REST

Llama al método reasoningEngineRuntimeRevisions.get .

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • PROJECT_ID: ID del proyecto de Google Cloud
  • LOCATION: una región admitida
  • RESOURCE_ID: Es el ID del recurso del agente implementado.
  • REVISION_ID: Es el ID único de una revisión específica del entorno de ejecución.

Método HTTP y URL: 

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

Para enviar tu solicitud, expande una de estas opciones:

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

{
  "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"
}

Configura la distribución del tráfico entre las revisiones

Puedes administrar cómo se distribuye el tráfico entre las revisiones activas. Ten en cuenta que solo las consultas dirigidas al recurso raíz reasoningEngine se someten a la división del tráfico. Si se dirige una consulta a una ruta de acceso a un recurso de revisión específico, se omiten explícitamente las reglas de tráfico.

El tráfico se distribuye con uno de los siguientes métodos:

  • Por porcentaje: Cuando se configura por porcentaje, un porcentaje específico del tráfico se dirige a cada revisión del agente. Cada porcentaje especificado debe ser un número entero. La suma de los porcentajes debe ser igual al 100%. Incluso si solo hay 1 revisión activa, puedes configurar la división del tráfico (en la que el 100% se redirecciona allí).

  • A la revisión más reciente: Todo el tráfico se dirige a la revisión más reciente. Cuando se crea una revisión nueva del agente, el tráfico se dirige automáticamente a esa revisión.

Console

Para configurar la administración del tráfico, haz lo siguiente:

  1. Ve a Govern > Deployments.

    Ir a Implementaciones

  2. Haz clic en el nombre del agente.

  3. Ve a la pestaña Revisiones.

  4. En la página de detalles de las revisiones, haz clic en Administrar tráfico.

  5. En Modo de división, selecciona una de estas opciones:

    1. Manual: Especifica el porcentaje de tráfico que se dirigirá a cada revisión.
    2. Siempre la más reciente: En este caso, el 100% del tráfico se dirige a la revisión más reciente (la que se creó más recientemente).

  6. Selecciona Guardar para guardar los cambios.

SDK de Agent Platform

En el siguiente código, se muestra un ejemplo de configuración de la distribución del tráfico basada en porcentajes.

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,
                    },
                ]
            }
        }
    },
)

Reemplaza las siguientes variables en el código:

  • PROJECT_ID: ID del proyecto de Google Cloud
  • LOCATION: una región admitida
  • RESOURCE_ID: Es el ID del recurso del agente implementado.
  • REVISION_ID_1: ID de la primera revisión
  • REVISION_ID_2: ID de la segunda revisión

REST

Para configurar el tráfico de modo que siempre se dirija a la revisión más reciente (opción predeterminada), actualiza el recurso ReasoningEngine con el campo traffic_config y especifica trafficSplitAlwaysLatest:

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

Para dividir el tráfico entre las revisiones del entorno de ejecución de un agente, actualiza el recurso ReasoningEngine con el campo traffic_config y proporciona una lista de destinos de tráfico con sus respectivos porcentajes. A continuación, se muestra cómo establecer la división manual en dos revisiones.

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • PROJECT_ID: ID del proyecto de Google Cloud
  • LOCATION: una región admitida
  • RESOURCE_ID: Es el ID del recurso del agente implementado.
  • REVISION_ID_1: ID de la primera revisión
  • REVISION_ID_2: ID de la segunda revisión
  • TRAFFIC_PERCENTAGE_1: Es el porcentaje de flujo de tráfico que deseas para la primera revisión.
  • TRAFFIC_PERCENTAGE_2: Es el porcentaje de flujo de tráfico que deseas para la segunda revisión.

Método HTTP y URL: 

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

Cuerpo JSON de la solicitud:

{
  "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
          }
        ]
      }
    }
}

Para enviar tu solicitud, expande una de estas opciones:

Esta solicitud inicia una operación de larga duración (LRO). Inicialmente, recibirás una respuesta de operación estándar. Una vez que se completen los cambios de configuración, la respuesta mostrará done y repetirá los parámetros de configuración. 
{
  "name": "projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID",
  "done": false
}

Consulta una revisión específica

Puedes consultar una revisión específica a través del SDK o las APIs. La revisión debe estar activa para que se pueda consultar. Las consultas dirigidas a una revisión específica omiten las reglas de distribución del tráfico.

SDK de Agent Platform

El siguiente código consulta una revisión activa específica:

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)

Reemplaza las siguientes variables en el código:

  • PROJECT_ID: ID del proyecto de Google Cloud
  • LOCATION: una región admitida
  • RESOURCE_ID: Es el ID del recurso del agente implementado.
  • REVISION_ID: Es el ID único de una revisión específica del entorno de ejecución.

REST

Llama al método reasoningEngineRuntimeRevisions.query.

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • PROJECT_ID: ID del proyecto de Google Cloud
  • LOCATION: una región admitida
  • RESOURCE_ID: Es el ID del recurso del agente implementado.
  • REVISION_ID: Es el ID único de una revisión específica del entorno de ejecución.

Método HTTP y URL: 

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

Para enviar tu solicitud, expande una de estas opciones:

 

Supervisa las revisiones

Supervisa las revisiones para detectar actividad y problemas haciendo un seguimiento del número de revisión como metadatos en los registros. Consulta Configura el registro para obtener información sobre cómo hacerlo.

Actualiza una revisión

Actualiza los agentes implementados siguiendo las instrucciones que se indican en Actualiza un agente implementado. Puedes actualizar loscampos con versiones o sin versiones. Si actualizas los campos con versiones, crearás una revisión nueva.

Borra una revisión del agente

Puedes quitar una revisión del agente si la borras. Solo puedes borrar las revisiones que no estén activas para la administración del tráfico porque están obsoletas o no están configuradas para recibir tráfico. Consulta Configura la distribución del tráfico entre las revisiones para obtener instrucciones sobre cómo configurar si una revisión recibe tráfico.

Console

Para borrar una revisión de un agente, haz lo siguiente:

  1. Ve a Govern > Deployments.

    Ir a Implementaciones

  2. Haz clic en el nombre del agente.

  3. Ve a la pestaña Revisiones.

  4. En la página de detalles de la revisión, haz clic en el Nombre de la revisión.

  5. Busca la fila de la revisión que deseas quitar.

  6. Haz clic en el ícono de borrar (papelera).

  7. Cuando se te solicite, confirma la eliminación de la revisión.

SDK de Agent Platform

El siguiente código borra una revisión del agente especificada:

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"
)

Reemplaza las siguientes variables en el código:

  • PROJECT_ID: ID del proyecto de Google Cloud
  • LOCATION: una región admitida
  • RESOURCE_ID: Es el ID del recurso del agente implementado.
  • REVISION_ID: Es el ID único de una revisión específica del entorno de ejecución.

REST

Llama al método reasoningEngineRuntimeRevisions.delete.

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • PROJECT_ID: ID del proyecto de Google Cloud
  • LOCATION: una región admitida
  • RESOURCE_ID: Es el ID del recurso del agente implementado.
  • REVISION_ID: Es el ID único de una revisión específica del entorno de ejecución.

Método HTTP y URL: 

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

Para enviar tu solicitud, expande una de estas opciones:

 

Limitaciones

  • Agent Gateway no es compatible con los agentes de Agent Runtime que usan revisiones. No podrás usar funciones relacionadas con el control de versiones, como la configuración de división del tráfico y las consultas por revisión, si un Agent Gateway está adjunto a la configuración de un agente.