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 está Activa cuando 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. Cuando se archiva una revisión, se retira de forma permanente de la entrega de tráfico y no se puede restablecer. Las revisiones archivadas se conservan solo como referencia histórica.

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

Límites de revisión

Las revisiones archivadas dejan de ocupar un espacio de revisión. Cambiar una vinculación de Agent Gateway archiva cada revisión preexistente (consulta Agent Gateway y revisiones), por lo que un cambio de vinculación libera cuota en lugar de consumirla. Las revisiones archivadas se pueden seguir borrando.

Campos versionados y sin versionar

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 del agente

Puedes enumerar todas las revisiones de un agente implementado.

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, incluida la siguiente información:

    1. Nombre: Es el nombre o número de la revisión.
    2. Estado: Es el estado de la revisión.
    3. Tráfico: Es el porcentaje de tráfico que se dirige a la revisión.
    4. Creado: Fecha y hora en que se creó la revisión.

SDK de Agent Platform

El siguiente código muestra 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 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)

Reemplaza las siguientes variables en el código:

  • PROJECT_ID: ID del proyecto de Cloud de Confiance by S3NS
  • 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 Cloud de Confiance by S3NS
  • 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.

Console

  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. En esta pantalla, se muestra información sobre la revisión, como la hora de creación y el estado.

SDK de Agent Platform

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

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)

Reemplaza las siguientes variables en el código:

  • PROJECT_ID: ID del proyecto de Cloud de Confiance by S3NS
  • 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 Cloud de Confiance by S3NS
  • 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 nueva revisión del agente, el tráfico se dirige automáticamente a esa revisión.

Una división manual solo puede segmentarse para las revisiones activas. Si se le asigna un nombre a una revisión archivada, se devuelve FAILED_PRECONDITION:

Traffic target revision {revision} is not an active revision of this Agent Engine. Update traffic_config to reference only active revisions.

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 destinará 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 cómo configurar la distribución del tráfico basada en porcentajes.

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

Reemplaza las siguientes variables en el código:

  • PROJECT_ID: ID del proyecto de Cloud de Confiance by S3NS
  • 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 revisión 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 versiones.

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

  • PROJECT_ID: ID del proyecto de Cloud de Confiance by S3NS
  • 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 revisión de la segunda revisión
  • TRAFFIC_PERCENTAGE_1: El porcentaje de flujo de tráfico que deseas para la primera revisión
  • TRAFFIC_PERCENTAGE_2: 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á la 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 directas 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 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)

Reemplaza las siguientes variables en el código:

  • PROJECT_ID: ID del proyecto de Cloud de Confiance by S3NS
  • 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 Cloud de Confiance by S3NS
  • 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:

 

Agent Gateway y revisiones

Si adjuntas, cambias o separas una vinculación de Agent Gateway en un agente, se crea una revisión nueva y se archivan todas las revisiones que existían antes del cambio. Solo la revisión nueva permanece activa. Esta acción es irreversible, ya que no se pueden restablecer las revisiones archivadas.

Dado que un cambio de vinculación archiva cada revisión existente, solo se permite cuando todo el tráfico ya está en la revisión más reciente. La API rechaza el cambio si se establece alguna división manual, incluso una que coloque el 100% del tráfico en la revisión más reciente. El rechazo devuelve 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.

Para cambiar la puerta de enlace en un agente que usa una división de tráfico manual, haz lo siguiente:

  1. Cambia al enrutamiento siempre más reciente configurando traffic_config.traffic_split_always_latest (o borrando traffic_config). Consulta Configura la distribución del tráfico entre las revisiones.
  2. Cambia spec.deployment_spec.agent_gateway_config. Esto crea la nueva revisión y archiva todas las anteriores.
  3. Si necesitas otra división manual, créala a partir de las revisiones creadas después del cambio de vinculación.

Se puede seguir accediendo a las revisiones archivadas a través de la API, y se conserva su ReasoningEngineSpec completa. Para crear una revisión nueva equivalente a una archivada, obtén los detalles de la revisión archivada y, luego, implementa una revisión nueva con los mismos campos versionados. Si se reutiliza el mismo URI de imagen de contenedor, se reproduce el mismo tiempo de ejecución; si se reutilizan la misma ubicación del código fuente y los mismos métodos de clase, se reproduce el mismo comportamiento.

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 configurar el registro.

Crea una revisión nueva del agente

Para crear una revisión nueva, actualiza los campos versionados de un agente implementado. Consulta Actualiza un agente implementado para obtener instrucciones.

Si actualizas los campos con versiones, se creará automáticamente una revisión nueva. Si actualizas campos sin versiones, el agente se actualizará en todas sus revisiones existentes sin crear una nueva.

Administra la limpieza de revisiones

Gemini Enterprise Agent Platform quita automáticamente las revisiones antiguas para ayudarte a mantenerte dentro de los límites de revisión. También puedes borrar revisiones de forma manual.

Recolección automática de elementos no utilizados

De forma predeterminada, Gemini Enterprise Agent Platform habilita la recolección automática de elementos no utilizados para todos los agentes. No puedes inhabilitarlo. La recolección de elementos no utilizados solo se ejecuta como parte de una operación de actualización del agente; no se ejecuta como un trabajo en segundo plano.

  • Cuándo se ejecuta: Si una operación de actualización intenta superar el límite de revisión configurado, Gemini Enterprise Agent Platform borra las revisiones aptas más antiguas en la misma operación antes de crear la revisión nueva. Si reduces el límite, Gemini Enterprise Agent Platform borrará de inmediato la cantidad suficiente de las revisiones aptas más antiguas para cumplir con el nuevo límite.
  • Revisiones aptas: Una revisión es apta para su eliminación solo si cumple con todas las siguientes condiciones:
    • Está en el estado ACTIVE.
    • No se incluye en la configuración de tráfico (recibe el 0% del tráfico).
  • Fallas: Si no hay suficientes revisiones aptas para liberar espacio, Gemini Enterprise Agent Platform rechaza la operación de actualización con un error FAILED_PRECONDITION. No borra ninguna revisión ni crea una nueva. Debes quitar revisiones de la configuración de tráfico o aumentar el límite antes de volver a intentarlo.

Configura el límite

El límite se define con el campo revision_garbage_collection_strategy.keep_n_latest.max_revisions en el agente. Puedes establecer este campo cuando crees el agente o cambiarlo más adelante con una solicitud de actualización.

  • Valor predeterminado para agentes nuevos: 100 revisiones.
  • Valor predeterminado para los agentes existentes: 950 revisiones.
  • Rango permitido: de 1 a 950. Se rechaza un valor de 0 o menos. Se rechaza un valor superior a 950 porque 950 es una cuota fija que no se puede aumentar.

Eliminación manual

Puedes quitar manualmente 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 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 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"
)

Reemplaza las siguientes variables en el código:

  • PROJECT_ID: ID del proyecto de Cloud de Confiance by S3NS
  • 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 Cloud de Confiance by S3NS
  • 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: