Administra Agent Gateway

En este documento, se describen las tareas de mantenimiento posteriores a la implementación para los recursos de Agent Gateway. Si aún no creaste una puerta de enlace, consulta Configura Agent Gateway.

Antes de comenzar

Antes de administrar los recursos de Agent Gateway, verifica los siguientes requisitos previos:

Visualiza y, luego, inspecciona las puertas de enlace

Puedes enumerar los recursos de Agent Gateway en un proyecto de Google Cloud y, además, inspeccionar la configuración de una puerta de enlace, las extensiones adjuntas y los metadatos de solo salida.

Console

  1. En la consola de Google Cloud , ve a la página Puertas de enlace.

    Ir a Puertas de enlace

  2. Consulta la lista de puertas de enlace en el proyecto seleccionado.

  3. Haz clic en el nombre de una puerta de enlace para abrir su página de detalles:

    • En la pestaña Detalles, revisa las secciones Descripción general, Autorización de acceso, Seguridad de IA, Extensiones de servicio y Configuración de VPC.
    • En la pestaña Observabilidad, revisa las métricas de tráfico y de políticas de la puerta de enlace. Para obtener más información, consulta Supervisa el tráfico de Agent Gateway.

gcloud

  • Enumera todas las puertas de enlace de una región específica:

    gcloud network-services agent-gateways list \
  --location=LOCATION \
  --project=PROJECT_ID

    Reemplaza lo siguiente:

    • LOCATION: Es la región en la que se implementan las puertas de enlace, como us-central1.
    • PROJECT_ID: Es el ID del proyecto de Google Cloud que aloja las puertas de enlace.

  • Inspecciona la configuración de una puerta de enlace específica:

    gcloud network-services agent-gateways describe AGENT_GATEWAY_NAME \
  --location=LOCATION \
  --project=PROJECT_ID

    Reemplaza AGENT_GATEWAY_NAME por el nombre del recurso de Agent Gateway.

Configuración inmutable

La mayoría de los parámetros de configuración de Agent Gateway, como sus instancias asociadas de Agent Registry y las políticas de seguridad y administración, se pueden modificar in situ, como se describe en Actualiza una Agent Gateway. Sin embargo, algunos parámetros de configuración principales son inmutables y requieren que implementes una puerta de enlace de reemplazo. Consulta la siguiente tabla antes de modificar las puertas de enlace:

Configuración Mutabilidad Requisito o restricción
Nombre y región de la puerta de enlace Inmutable Para cambiar el nombre o la región, implementa una puerta de enlace de reemplazo.

Ruta de acceso administrada

(AGENT_TO_ANYWHERE o CLIENT_TO_AGENT)

 Inmutable Se configura en el momento de la creación en googleManaged.governedAccessPath. No se puede modificar in situ.

Adjunto de red de Private Service Connect

(networkAttachment)

 Inmutable después de establecerse Una vez que asocias un adjunto de red con una puerta de enlace, no se puede cambiar ni quitar.

Plantilla de conectividad del agente y parámetros de configuración asociados de intercambio de tráfico de Cloud DNS, configuración de confianza de TLS y salida de VPC

 Mutable de forma condicional Puedes actualizar la configuración de la puerta de enlace para que haga referencia a una plantilla de conectividad diferente con parámetros de configuración nuevos, siempre que la plantilla nueva siga haciendo referencia al mismo networkAttachment.

Reemplaza una puerta de enlace para cambiar la configuración inmutable

Si necesitas cambiar un parámetro de configuración inmutable, como el adjunto de red de PSC asociado con la puerta de enlace, debes implementar una puerta de enlace de reemplazo y migrar tus cargas de trabajo a la puerta de enlace nueva:

  1. Crea el Agent Gateway de reemplazo y configura sus políticas de Identity and Access Management (IAM) y de autorización. Para obtener instrucciones, consulta Configura Agent Gateway.

  2. Actualiza tus cargas de trabajo para usar la puerta de enlace de reemplazo:

    • Apps de Gemini Enterprise: Actualiza el nombre del recurso de la puerta de enlace en la configuración de Seguridad > Configuración de la app. Consulta Enruta el tráfico de Gemini Enterprise a través de Agent Gateway.
    • Agentes de Agent Runtime: Dentro de un solo proyecto y región, todos los agentes de Agent Runtime deben vincularse a la misma puerta de enlace. No se admiten las actualizaciones directas in situ de una puerta de enlace a otra. Para migrar tus agentes, sigue estos pasos:
      1. Asegúrate de que cada agente vinculado enrute el 100% del tráfico a su revisión más reciente (trafficConfig.trafficSplitAlwaysLatest).
      2. Desasocia todos los agentes del proyecto y la región de la puerta de enlace anterior configurando spec.deploymentSpec.agentGatewayConfig como {} con reasoningEngines.patch y espera a que finalice cada operación de actualización.
      3. Llama a reasoningEngines.patch en cada agente para establecer spec.deploymentSpec.agentGatewayConfig en el nombre del recurso de la puerta de enlace de reemplazo. Para ver ejemplos de solicitudes, consulta Enruta el tráfico de Agent Runtime a través de Agent Gateway.

  3. Después de que todas las cargas de trabajo dejen de hacer referencia a la puerta de enlace anterior, sigue los pasos que se indican en Borra un Agent Gateway para desmantelar la puerta de enlace anterior.

Actualiza una Agent Gateway

Puedes actualizar ciertos parámetros de configuración de Agent Gateway directamente en la consola de Google Cloud o con gcloud CLI para exportar la configuración de la puerta de enlace a un archivo YAML, realizar los cambios y volver a importar el archivo.

Actualiza el registro de agentes

Puedes actualizar el registro de agentes asociado en la consola deGoogle Cloud o la gcloud CLI. Tu puerta de enlace debe hacer referencia al registro regional único que corresponde a la región de la puerta de enlace. Si la puerta de enlace está vinculada a una app de Gemini Enterprise, debe mantener un solo registro que coincida con la ubicación de esa app.

Console

  1. En la consola de Google Cloud , ve a la página Puertas de enlace.

    Ir a Puertas de enlace

  2. Haz clic en el nombre de la puerta de enlace que quieres actualizar.

  3. En la pestaña Detalles, en la sección Descripción general, haz clic en Editar registros.

  4. Selecciona el Agent Registry regional que coincida con la región en la que se implementó tu puerta de enlace y, luego, haz clic en Guardar.

gcloud

Exporta la configuración de la puerta de enlace a agent-gateway.yaml con gcloud network-services agent-gateways export, edita registries, description o labels (quita los campos de solo salida, como createTime, updateTime, agentGatewayCard y selfLink) y vuelve a importar el archivo con gcloud network-services agent-gateways import, como se muestra en Actualiza la plantilla de conectividad de la puerta de enlace.

Actualiza la plantilla de conectividad

Puedes actualizar la plantilla de conectividad de un recurso de Agent Gateway con gcloud CLI.

gcloud

  1. Crea un AgentConnectivityTemplate nuevo con la configuración de conectividad actualizada y asegúrate de que use el mismo networkAttachment que la puerta de enlace existente. Para obtener instrucciones detalladas sobre la sintaxis y la configuración de la plantilla, consulta Configura Agent Gateway con conectividad de VPC.

  2. Exporta la configuración de la puerta de enlace existente a un archivo YAML:

    gcloud network-services agent-gateways export AGENT_GATEWAY_NAME \
 --destination="agent-gateway.yaml" \
 --location=LOCATION \
 --project=PROJECT_ID

    Reemplaza lo siguiente:

    • AGENT_GATEWAY_NAME: Es el nombre de la puerta de enlace que se actualizará.
    • LOCATION: Es la región en la que se implementa la puerta de enlace.
    • PROJECT_ID: Es el ID del proyecto en el que se implementa la puerta de enlace.

  3. En el archivo agent-gateway.yaml exportado, mantén intactos los campos protocols, registries, description y labels existentes, quita los campos de solo salida (createTime, updateTime, agentGatewayCard, selfLink) y actualiza agentConnectivityTemplate para hacer referencia a la plantilla nueva:

    name: projects/PROJECT_NUMBER/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME
protocols:
  - MCP
googleManaged:
  governedAccessPath: AGENT_TO_ANYWHERE
registries:
  - //agentregistry.googleapis.com/projects/PROJECT_NUMBER/locations/LOCATION
agentConnectivityTemplate: projects/PROJECT_NUMBER/locations/LOCATION/agentConnectivityTemplates/NEW_TEMPLATE_NAME

    Reemplaza lo siguiente:

    • PROJECT_NUMBER: Es el número de proyecto numérico en el que se implementa la puerta de enlace (agentConnectivityTemplate requiere el número de proyecto en lugar del ID del proyecto).
    • LOCATION: Es la región de la puerta de enlace.
    • AGENT_GATEWAY_NAME: Es el nombre de la puerta de enlace.
    • NEW_TEMPLATE_NAME: Es el nombre de la plantilla de conectividad de reemplazo.

  4. Vuelve a importar el archivo YAML actualizado para aplicar los cambios:

    gcloud network-services agent-gateways import AGENT_GATEWAY_NAME \
 --source="agent-gateway.yaml" \
 --location=LOCATION \
 --project=PROJECT_ID

  5. Opcional: Borra la plantilla de conectividad anterior después de que finalice la actualización de la puerta de enlace:

    gcloud network-services agent-connectivity-templates delete OLD_TEMPLATE_NAME \
 --location=LOCATION \
 --project=PROJECT_ID

Modificar la configuración de IAP o las plantillas de Model Armor

Puedes modificar la configuración de aplicación de la IAP y las plantillas de Model Armor actualizando las extensiones de autorización adjuntas a tu puerta de enlace.

Console

  1. En la consola de Google Cloud , ve a la página Puertas de enlace.

    Ir a Puertas de enlace

  2. Haz clic en el nombre de la puerta de enlace que quieres actualizar.

  3. En la pestaña Detalles, actualiza las extensiones de seguridad adjuntas:

    • Cambia el modo de aplicación forzosa de IAP: En la sección Autorización de acceso, junto a Autorización de acceso, haz clic en Editar autorización de acceso. Selecciona Solo auditoría (modo de ejecución de prueba) o Aplicar políticas y, luego, haz clic en Guardar.

    • Cambiar las plantillas de Model Armor: En la sección Seguridad de la IA, haz clic en Editar plantilla de solicitud junto a Plantilla para solicitudes o Editar plantilla de respuesta junto a Plantilla para respuestas. Selecciona la plantilla de reemplazo y, luego, haz clic en Guardar.

gcloud

  1. Enumera las extensiones de autorización en la región de la puerta de enlace para identificar el nombre de la extensión:

    gcloud service-extensions authz-extensions list \
 --location=LOCATION \
 --project=PROJECT_ID

    Reemplaza LOCATION por la región de la puerta de enlace y PROJECT_ID por el ID de tu proyecto.

  2. Inspecciona la configuración actual de la extensión:

    gcloud service-extensions authz-extensions describe AUTHZ_EXTENSION_NAME \
 --location=LOCATION \
 --project=PROJECT_ID \
 --format=yaml

    Reemplaza AUTHZ_EXTENSION_NAME por el nombre de tu recurso AuthzExtension de IAP o Model Armor.

  3. Guarda la especificación de la extensión actualizada en authz-extension.yaml, omitiendo los campos de solo salida, como createTime y updateTime:

    • Para una extensión de IAP: Incluye iamEnforcementMode: "DRY_RUN" para el modo de solo auditoría o quita iamEnforcementMode para aplicar políticas:

      name: AUTHZ_EXTENSION_NAME
service: iap.googleapis.com
failOpen: false
timeout: 1s
metadata:
  iapPolicyVersion: "V2"
  iamEnforcementMode: "DRY_RUN" # Omit this line to enforce policies

    • Para una extensión de Model Armor: Actualiza request_template_id y response_template_id en metadata.model_armor_settings:

      name: AUTHZ_EXTENSION_NAME
service: modelarmor.LOCATION.rep.googleapis.com
failOpen: false
timeout: 1s
metadata:
  model_armor_settings: '[
    {
      "request_template_id": "projects/MODEL_ARMOR_PROJECT_ID/locations/LOCATION/templates/REQUEST_TEMPLATE_ID",
      "response_template_id": "projects/MODEL_ARMOR_PROJECT_ID/locations/LOCATION/templates/RESPONSE_TEMPLATE_ID"
    }
  ]'

      Reemplaza lo siguiente:

      • AUTHZ_EXTENSION_NAME: Es el nombre de tu recurso AuthzExtension de Model Armor.
      • LOCATION: Es la región de la puerta de enlace.
      • MODEL_ARMOR_PROJECT_ID: Es el ID del proyecto que aloja tus plantillas de Model Armor.
      • REQUEST_TEMPLATE_ID y RESPONSE_TEMPLATE_ID: Son los IDs de tus plantillas de solicitud y respuesta.

      Asegúrate de que la cuenta de servicio de la puerta de enlace (agentGatewayCard.serviceExtensionsServiceAccount) tenga roles/modelarmor.user en cualquier proyecto de plantilla al que se haga referencia recientemente, así como roles/modelarmor.calloutUser y roles/serviceusage.serviceUsageConsumer en el proyecto de puerta de enlace (consulta Delega la autorización).

  4. Importa el archivo YAML de la extensión actualizado:

    gcloud service-extensions authz-extensions import AUTHZ_EXTENSION_NAME \
 --source="authz-extension.yaml" \
 --location=LOCATION \
 --project=PROJECT_ID

Para adjuntar políticas de autorización nuevas o modificar las reglas de coincidencia de tráfico en un AuthzPolicy existente, consulta Delega la autorización.

Desasocia cargas de trabajo de un Agent Gateway

Antes de borrar una Agent Gateway, debes desasociar todas las apps de Gemini Enterprise y los agentes de Agent Runtime que hagan referencia a la puerta de enlace.

Cómo desasociar una app de Gemini Enterprise

Puedes desvincular un Agent Gateway de una app de Gemini Enterprise en la consola de Google Cloud :

  1. En la consola de Google Cloud , ve a la página Gemini Enterprise.

    Ir a Gemini Enterprise

  2. Haz clic en el nombre de la app asociada con la puerta de enlace.

  3. Haz clic en Seguridad.

  4. En la pestaña Configuración, en Configuración de Agent Gateway, borra el campo Nombre del recurso de Agent Gateway.

  5. Haz clic en Guardar.

Si desasocias un Agent Gateway, se detiene el enrutamiento del tráfico saliente de la app a través de la puerta de enlace. Los agentes importados y los servidores del Protocolo de contexto del modelo (MCP) permanecen registrados en Agent Registry, pero la app no puede acceder a ellos hasta que vuelvas a vincular una puerta de enlace. Ten en cuenta que la puerta de enlace nueva debe hacer referencia al mismo registro de agentes.

Desasocia un agente de Agent Runtime

La consola de Google Cloud y gcloud CLI no admiten la modificación de las vinculaciones de la puerta de enlace de Agent Runtime. Para desasociar un Agent Gateway de un agente de Agent Runtime implementado mientras se mantiene el agente en ejecución, puedes llamar al método de la API de REST reasoningEngines.patch para borrar spec.deploymentSpec.agentGatewayConfig:

  1. Asegúrate de que el agente enrute todo el tráfico a la revisión más reciente (trafficConfig.trafficSplitAlwaysLatest establecido en true o sin división manual de trafficConfig configurada). Borrar o cambiar una vinculación de puerta de enlace falla si hay una división de tráfico de revisión manual activa y archiva de forma irreversible todas las revisiones anteriores. Para obtener más información, consulta Agent Gateway y revisiones.

  2. Envía una solicitud PATCH al motor de razonamiento con updateMask=spec.deploymentSpec.agentGatewayConfig y un objeto agentGatewayConfig vacío ({}):

    curl -X PATCH \
 -H "Authorization: Bearer $(gcloud auth print-access-token)" \
 -H "Content-Type: application/json; charset=utf-8" \
 -d '{
   "spec": {
     "deploymentSpec": {
       "agentGatewayConfig": {}
     }
   }
 }' \
 "https://REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/reasoningEngines/RESOURCE_ID?updateMask=spec.deploymentSpec.agentGatewayConfig"

    Reemplaza lo siguiente:

    • REGION: Es la región en la que se implementa el agente.
    • PROJECT_ID: Es el ID del proyecto en el que se implementa el agente.
    • RESOURCE_ID: Es el ID del recurso del agente.

Borra un Agent Gateway

Agent Gateway aplica un seguimiento estricto de las referencias para evitar políticas de seguridad huérfanas y rutas de tráfico de agentes dañadas. Si se produce un error cuando se borra una puerta de enlace, el botón Borrar de la consola de Google Cloud permanece no disponible si se cumple alguna de las siguientes condiciones:

  • Uno o más agentes de Agent Runtime o apps de Gemini Enterprise aún hacen referencia a la puerta de enlace.
  • Cualquier AuthzPolicy (para IAP, Model Armor o un proveedor personalizado) o TelemetryPolicy aún se orienta a la puerta de enlace.
  • Aún se está ejecutando una operación de actualización de la configuración de VPC en la puerta de enlace.

Completa los siguientes pasos en orden para borrar una Agent Gateway y limpiar sus recursos asociados:

Console

  1. Asegúrate de que ninguna app de Gemini Enterprise ni agente de Agent Runtime haga referencia a la puerta de enlace. Sigue las instrucciones que se indican en Desasocia cargas de trabajo de un Agent Gateway.

  2. En la consola de Google Cloud , ve a la página Puertas de enlace.

    Ir a Puertas de enlace

  3. Haz clic en el nombre de la puerta de enlace que quieres borrar.

  4. En la pestaña Detalles, quita todas las asociaciones de políticas orientadas a la puerta de enlace:

    • Si aparece la sección Autorización de acceso, haz clic en Quitar y, luego, confirma la eliminación. Esta acción borra el AuthzPolicy de IAP y su AuthzExtension.
    • Si aparece la sección Seguridad de IA, haz clic en Quitar y, luego, confirma la eliminación. Esta acción borra tanto el objeto AuthzPolicy de Model Armor como su AuthzExtension.
    • Consulta la tabla Extensiones de servicio. Si queda algún recurso AuthzPolicy personalizado adjunto, usa la pestaña gcloud en este procedimiento para borrarlos antes de continuar.

  5. Una vez que se quiten todas las asociaciones de políticas y no haya ninguna actualización de VPC en curso, haz clic en Borrar y, luego, confirma la eliminación.

  6. Confirma que la puerta de enlace ya no aparezca en la lista Puertas de enlace de tu proyecto.

  7. Opcional: Limpia los recursos de conectividad sin usar si ninguna otra puerta de enlace los usa. Usa la pestaña gcloud para borrar el AgentConnectivityTemplate y borrar el adjunto de red.

gcloud

  1. Asegúrate de que ninguna app de Gemini Enterprise ni agente de Agent Runtime haga referencia a la puerta de enlace. Sigue las instrucciones que se indican en Desasocia cargas de trabajo de un Agent Gateway.

  2. Quita las políticas de autorización y las extensiones de autorización:

    1. Enumera las políticas de autorización en la región de la puerta de enlace para encontrar políticas cuyo campo target.resources haga referencia a tu puerta de enlace y toma nota de cualquier authzExtensions al que se haga referencia:

      gcloud network-security authz-policies list \
  --location=LOCATION \
  --project=PROJECT_ID \
  --format="yaml(name,target.resources,customProvider.authzExtension.resources)"

      Reemplaza LOCATION por la región de la puerta de enlace y PROJECT_ID por el ID de tu proyecto.

    2. Borra cada AuthzPolicy que se oriente a la puerta de enlace:

      gcloud network-security authz-policies delete AUTHZ_POLICY_NAME \
  --location=LOCATION \
  --project=PROJECT_ID

      Reemplaza AUTHZ_POLICY_NAME por el ID de cada política de autorización orientada a la puerta de enlace (por ejemplo, AGENT_GATEWAY_NAME-iap-authzpolicy o AGENT_GATEWAY_NAME-aisecurity-authzpolicy para las políticas creadas en la consola).

    3. Opcional: Después de borrar los recursos AuthzPolicy de referencia, borra los recursos AuthzExtension que no usen otras políticas:

      gcloud service-extensions authz-extensions delete AUTHZ_EXTENSION_NAME \
  --location=LOCATION \
  --project=PROJECT_ID

      Reemplaza AUTHZ_EXTENSION_NAME por el ID de la extensión de autorización sin usar.

  3. Borra el Agent Gateway:

    gcloud network-services agent-gateways delete AGENT_GATEWAY_NAME \
 --location=LOCATION \
 --project=PROJECT_ID

    Reemplaza AGENT_GATEWAY_NAME por el nombre de la puerta de enlace que deseas borrar.

  4. Confirma que la puerta de enlace ya no aparezca en la lista de puertas de enlace regionales:

    gcloud network-services agent-gateways list \
 --location=LOCATION \
 --project=PROJECT_ID

  5. Opcional: No puedes borrar un AgentConnectivityTemplate mientras una Agent Gateway hace referencia a él. Después de borrar la puerta de enlace, borra las plantillas de conectividad que no uses:

    gcloud network-services agent-connectivity-templates delete CONNECTIVITY_TEMPLATE_NAME \
 --location=LOCATION \
 --project=PROJECT_ID

    Reemplaza CONNECTIVITY_TEMPLATE_NAME por el nombre de la plantilla de conectividad sin usar. Si ya no necesitas el adjunto de red de Private Service Connect subyacente, las zonas privadas de Cloud DNS o los recursos de TrustConfig del Administrador de certificados, consulta Borra adjuntos de red.

¿Qué sigue?

Guía

Obtén información para delegar la autorización de Agent Gateway a IAP, Model Armor o tu propio servicio de autorización personalizado.

Guía

Aprende a supervisar Agent Gateway.

Guía

Aprende a configurar una Agent Gateway.

Solución de problemas

Aprender a solucionar problemas de conectividad de Agent Gateway