Accede a Apigee de forma privada desde Gemini Enterprise Agent Platform

Esta página se aplica a Apigee, pero no a Apigee Hybrid.

Consulta la documentación de Apigee Edge.

En este documento, se describe cómo configurar la conectividad privada desde un agente implementado en el entorno de ejecución del agente de la Plataforma de agentes de Gemini Enterprise a las APIs y las herramientas del Protocolo de contexto del modelo (MCP) publicadas en Apigee, a través de Private Service Connect. Con este patrón, el tráfico del agente a Apigee permanece completamente privado y no atraviesa la Internet pública.

Descripción general

Agent Runtime implementa tu agente en una red segura administrada por Google sin acceso a tu red de nube privada virtual (VPC). Del mismo modo, Apigee se ejecuta en una red segura administrada por Google. Cuando deseas que las llamadas de un agente a un modelo de lenguaje grande (LLM) o a las herramientas de MCP expuestas a través de Apigee viajen de forma privada, necesitas una forma de conectar estas dos redes administradas por Google a través de una red de VPC que controlas.

En este documento, se describe el siguiente patrón para ese puente:

Con esta configuración, cuando tu agente llama a https://APIGEE_HOSTNAME/..., la solicitud se resuelve en la IP del extremo de Private Service Connect en tu VPC, se reenvía a través del adjunto de servicio a tu instancia de Apigee y la procesa el proxy de API que coincide con la ruta de acceso de la solicitud.

Antes de comenzar

En este documento, se usan los siguientes marcadores de posición en los comandos. Reemplázalos por valores de tu entorno.

  • APIGEE_PROJECT_ID: Es el Google Cloud ID del proyecto que contiene tu organización de Apigee.
  • SERVICE_PROJECT_ID: Es el Google Cloud ID del proyecto en el que implementas tu agente en Agent Runtime. Puede ser el mismo que APIGEE_PROJECT_ID o un proyecto diferente, según cómo organices tus recursos de Google Cloud.
  • SERVICE_PROJECT_NUMBER: Es el número de proyecto numérico de SERVICE_PROJECT_ID. Puedes recuperarlo con gcloud projects describe SERVICE_PROJECT_ID --format="value(projectNumber)".
  • HOST_PROJECT_ID: ID del proyecto Google Cloud que contiene la red de VPC, la subred y la zona privada de Cloud DNS del consumidor. Es igual que SERVICE_PROJECT_ID, a menos que uses la VPC compartida, en cuyo caso este es el proyecto host al que se conecta el proyecto de servicio.
  • REGION: Es la región de tu instancia de Apigee (por ejemplo, us-west1).
  • VPC_NAME: Es el nombre de la red de VPC del consumidor en HOST_PROJECT_ID.
  • SUBNET_NAME: Es el nombre de una subred en VPC_NAME que se encuentra en REGION.
  • APIGEE_HOSTNAME: Es el nombre de host que configuraste en el grupo de entornos de Apigee (por ejemplo, api.internal.example.com).
  • BASE_PATH: Es la ruta base del proxy de API implementado en Apigee (por ejemplo, /mcp o /orders).
  • PARENT_DNS_NAME: Es el dominio DNS principal de APIGEE_HOSTNAME que deseas publicar desde la zona privada (por ejemplo, internal.example.com.). El valor debe terminar con un punto.
  • APIGEE_INSTANCE_NAME: Es el nombre de tu instancia de Apigee en REGION.

Debes tener lo siguiente:

  • Uno o más proyectos de Google Cloud (como se describe en la nota anterior) con la facturación habilitada
  • Una organización de Apigee existente en APIGEE_PROJECT_ID con al menos una instancia. En este documento, se crean todos los recursos de redes del consumidor (adjunto de red, extremo de Private Service Connect y la implementación del entorno de ejecución del agente) en la misma región que tu instancia de Apigee, que es la configuración más simple.
  • Un grupo de entornos cuyos entornos se implementan en esa instancia de Apigee y que incluye el nombre de host al que deseas que llame tu agente. En este documento, se hace referencia a ese nombre de host como APIGEE_HOSTNAME.
  • Al menos un proxy de API implementado en un entorno de ese grupo de entornos Todos los proxies a los que quieras que llame el agente deben ser accesibles en https://APIGEE_HOSTNAME/BASE_PATH.
  • Una red de VPC y una subred en HOST_PROJECT_ID, en la misma región que la instancia de Apigee En este documento, se hace referencia a estos como VPC_NAME y SUBNET_NAME. Agent Runtime requiere una subred de /28 como mínimo y aplica restricciones de rango adicionales. Para obtener más información, consulta los requisitos de rango de IP de subred en la documentación de Agent Platform.
  • Las siguientes APIs habilitadas en el proyecto correspondiente:
    • Apigee (apigee.googleapis.com) en APIGEE_PROJECT_ID.
    • Compute Engine (compute.googleapis.com) y Cloud DNS (dns.googleapis.com) en HOST_PROJECT_ID.
    • Agent Platform (aiplatform.googleapis.com) en SERVICE_PROJECT_ID.
  • Permisos de IAM suficientes para crear zonas y registros de Cloud DNS, direcciones de Compute Engine, adjuntos de red y reglas de reenvío de Private Service Connect en HOST_PROJECT_ID, y para actualizar la configuración de la instancia y el grupo de entornos de Apigee en APIGEE_PROJECT_ID Para obtener detalles sobre los roles necesarios, consulta Roles de Apigee, Control de acceso de Cloud DNS y Roles de IAM de Compute Engine.

Arquitectura

En los siguientes pasos, se describe el flujo de tráfico entre un agente implementado en Agent Runtime y un proxy de API alojado en Apigee, con un extremo de Private Service Connect en una VPC del consumidor como puente.

  1. El agente, que se ejecuta en Agent Runtime, realiza una solicitud HTTPS a APIGEE_HOSTNAME.
  2. El intercambio de tráfico de DNS configurado en la interfaz de PSC de Agent Runtime reenvía la búsqueda a la zona privada de Cloud DNS en tu VPC de consumidor, que devuelve la dirección IP del extremo de Private Service Connect.
  3. La solicitud del agente sale a través de la interfaz de PSC a tu VPC del consumidor y llega al extremo de Private Service Connect en esa dirección IP.
  4. El extremo de Private Service Connect reenvía la solicitud a través de la conexión de servicio al adjunto de servicio de la instancia de Apigee.
  5. La instancia de Apigee finaliza el protocolo TLS, hace coincidir el nombre de host de la solicitud con el grupo de entornos y enruta al proxy de API correcto.

Paso 1: Configura las redes en la VPC del consumidor

En esta sección, se configuran recursos en dos proyectos. Cada comando incluye una marca --project explícita para que puedas ejecutar los comandos desde cualquier configuración activa de gcloud:

  • Los recursos de Cloud DNS (zona y registro privados) se crean en HOST_PROJECT_ID, ya que la zona privada se adjunta a la red de VPC del consumidor.
  • Los recursos del extremo de Private Service Connect (dirección IP interna estática y regla de reenvío) y el adjunto de red se crean en SERVICE_PROJECT_ID. Cada uno de estos comandos usa una referencia entre proyectos a la subred compartida o a la red de VPC en HOST_PROJECT_ID. En una implementación de un solo proyecto, SERVICE_PROJECT_ID y HOST_PROJECT_ID son iguales, por lo que no hay cambios de propiedad entre los pasos. Para obtener más información sobre el modelo de VPC compartida para los extremos de Private Service Connect, consulta Crea un extremo en un proyecto de servicio de VPC compartida.

Crea una zona privada de Cloud DNS

Crea una zona privada de Cloud DNS que solo sea visible para tu VPC de consumidor. El agente usa esta zona (a través del intercambio de tráfico de DNS) para resolver APIGEE_HOSTNAME en una dirección IP privada. 

gcloud dns managed-zones create apigee-private \
  --project=HOST_PROJECT_ID \
  --dns-name="PARENT_DNS_NAME" \
  --description="Private zone for Apigee PSC access" \
  --visibility=private \
  --networks=VPC_NAME

Para obtener más información sobre las zonas privadas de Cloud DNS, consulta Zonas privadas.

Crea un adjunto de red

Crea un adjunto de red en la misma región y subred en la que deseas que aparezca la interfaz de PSC de Agent Runtime. Agent Runtime vincula su interfaz de PSC a este adjunto cuando se implementa el agente.

En una implementación de un solo proyecto, crea el adjunto de red en SERVICE_PROJECT_ID (que también es HOST_PROJECT_ID). En una implementación de VPC compartida, puedes crear el adjunto de red en el proyecto de servicio o en el proyecto host. Agent Platform recomienda el proyecto de servicio para simplificar los permisos. Para obtener orientación sobre la elección y los roles de IAM correspondientes, consulta Usa la interfaz de Private Service Connect con la VPC compartida.

El siguiente comando crea el adjunto de red en SERVICE_PROJECT_ID. En una implementación de VPC compartida, la referencia de subred debe incluir el ID del proyecto host. 

gcloud compute network-attachments create agent-network-attachment \
  --project=SERVICE_PROJECT_ID \
  --region=REGION \
  --subnets=projects/HOST_PROJECT_ID/regions/REGION/subnetworks/SUBNET_NAME \
  --connection-preference=ACCEPT_AUTOMATIC

Reservar una nueva dirección IP interna estática

Reserva una dirección IP interna para usarla como la IP del extremo de Private Service Connect al que se conecta el agente. Crea el recurso de dirección en SERVICE_PROJECT_ID y haz referencia a la subred compartida en HOST_PROJECT_ID para que el valor de la dirección se asigne desde el rango de esa subred. Esto coincide con la guía de la VPC compartida en Usa una dirección IP interna estática con una VPC compartida. 

gcloud compute addresses create apigee-psc-endpoint-ip \
  --project=SERVICE_PROJECT_ID \
  --region=REGION \
  --subnet=projects/HOST_PROJECT_ID/regions/REGION/subnetworks/SUBNET_NAME

Recupera la dirección reservada, que usarás en pasos posteriores: 

gcloud compute addresses describe apigee-psc-endpoint-ip \
  --project=SERVICE_PROJECT_ID \
  --region=REGION \
  --format="value(address)"

En este documento, se hace referencia a esta dirección como PSC_ENDPOINT_IP.

Obtén el adjunto de servicio para la instancia de Apigee

Recupera el URI del adjunto de servicio para tu instancia de Apigee con el método organizations.instances.get de la API de Apigee. Usas este URI como destino para el extremo de Private Service Connect. 

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://apigee.googleapis.com/v1/organizations/APIGEE_PROJECT_ID/instances/APIGEE_INSTANCE_NAME"

La respuesta incluye un campo serviceAttachment. En este documento, se hace referencia a ese valor como APIGEE_SERVICE_ATTACHMENT. Para obtener más información sobre cómo Apigee expone una vinculación de servicio en cada instancia, consulta Administración de instancias.

Crea el extremo de Private Service Connect

Crea una regla de reenvío que actúe como el extremo de Private Service Connect. Se orienta al adjunto del servicio de Apigee y usa la IP estática que reservaste. Crea la regla de reenvío en SERVICE_PROJECT_ID y haz referencia a la red de VPC compartida en HOST_PROJECT_ID y a la dirección en SERVICE_PROJECT_ID. 

gcloud compute forwarding-rules create apigee-psc-endpoint \
  --project=SERVICE_PROJECT_ID \
  --region=REGION \
  --network=projects/HOST_PROJECT_ID/global/networks/VPC_NAME \
  --address=projects/SERVICE_PROJECT_ID/regions/REGION/addresses/apigee-psc-endpoint-ip \
  --target-service-attachment=APIGEE_SERVICE_ATTACHMENT

Verifica que el servicio de Apigee haya aceptado la conexión: 

gcloud compute forwarding-rules describe apigee-psc-endpoint \
  --project=SERVICE_PROJECT_ID \
  --region=REGION \
  --format="value(pscConnectionStatus)"

El estado debe ser ACCEPTED antes de que el extremo pueda reenviar tráfico. Para obtener más información sobre los extremos de Private Service Connect, consulta Información sobre el acceso a servicios publicados a través de extremos.

Agrega un registro DNS para el nombre de host

En la zona privada, crea un registro A que resuelva APIGEE_HOSTNAME en PSC_ENDPOINT_IP. Este registro solo es visible dentro de VPC_NAME, por lo que los clientes externos siguen resolviendo el nombre de host a través del DNS público. 

gcloud dns record-sets create APIGEE_HOSTNAME. \
  --project=HOST_PROJECT_ID \
  --zone=apigee-private \
  --type=A \
  --ttl=60 \
  --rrdatas=PSC_ENDPOINT_IP

Paso 2: Configura Apigee

Agrega el proyecto de servicio a la lista de aceptación de consumidores de la instancia

La instancia de Apigee solo acepta conexiones de Private Service Connect de proyectos de consumidores que se encuentran en su consumerAcceptList. El lado del consumidor de la conexión está asociado con SERVICE_PROJECT_ID, ya que ese es el proyecto en el que se implementa el agente.

De forma predeterminada, el proyecto asociado a la organización de Apigee (APIGEE_PROJECT_ID) ya está en la lista. Si SERVICE_PROJECT_ID es igual a APIGEE_PROJECT_ID, no es necesario realizar ningún cambio y puedes omitir esta sección. De lo contrario, agrega SERVICE_PROJECT_ID a la lista.

Primero, verifica el valor actual de consumerAcceptList con el método organizations.instances.get: 

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://apigee.googleapis.com/v1/organizations/APIGEE_PROJECT_ID/instances/APIGEE_INSTANCE_NAME"

Busca el campo consumerAcceptList en la respuesta.

Luego, actualiza la lista llamando al método organizations.instances.patch con una máscara de actualización en consumerAcceptList. Dado que el campo reemplaza la lista existente, incluye todos ID del proyecto que deben conservar el acceso, incluidos APIGEE_PROJECT_ID y cualquier proyecto de servicio adicional que implemente agentes: 

curl -X PATCH \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{"consumerAcceptList": ["APIGEE_PROJECT_ID", "SERVICE_PROJECT_ID"]}' \
  "https://apigee.googleapis.com/v1/organizations/APIGEE_PROJECT_ID/instances/APIGEE_INSTANCE_NAME?updateMask=consumerAcceptList"

Para confirmar la actualización, vuelve a ejecutar el comando get y verifica que SERVICE_PROJECT_ID ahora se incluya en consumerAcceptList.

Verifica el nombre de host del grupo de entornos

Confirma que APIGEE_HOSTNAME aparezca en el grupo de entornos que aloja tus proxies de API. Si no es así, agrégala.

Para obtener instrucciones, consulta Trabaja con grupos de entornos.

Paso 3: Implementa tu agente con una interfaz de PSC y un intercambio de DNS

Cuando implementes tu agente en Agent Runtime, configúralo con una interfaz de PSC que haga referencia al adjunto de red que creaste y configura el intercambio de tráfico de DNS en tu zona privada. Para conocer el procedimiento de implementación completo y los frameworks compatibles, consulta Usa la interfaz de Private Service Connect con Agent Runtime y Implementa agentes en la documentación de Agent Platform.

Configura los siguientes dos campos en la configuración de la interfaz de PSC del agente (consulta la referencia de PscInterfaceConfig):

  • networkAttachment: Configura este parámetro como el nombre completo del recurso del adjunto de red que creaste en el paso 1, con el formato projects/SERVICE_PROJECT_ID/regions/REGION/networkAttachments/agent-network-attachment. Si creaste el adjunto de red en el proyecto host, usa HOST_PROJECT_ID en esta ruta.
  • dnsPeeringConfigs: Agrega una entrada con los siguientes campos para que Agent Runtime resuelva APIGEE_HOSTNAME a través de tu zona privada:
    • domain: PARENT_DNS_NAME. El valor debe terminar con un punto.
    • targetProject: HOST_PROJECT_ID. Este es el proyecto que contiene la VPC del consumidor y la zona privada.
    • targetNetwork: VPC_NAME.

El agente de servicio de Agent Platform para SERVICE_PROJECT_ID (service-SERVICE_PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com) debe tener permiso para configurar el intercambio de tráfico de DNS y actualizar la vinculación de red. Otorga los roles necesarios como se describe en Rol obligatorio del agente de servicio de Agent Platform. En una implementación de VPC compartida, se aplican roles adicionales en el proyecto host. Consulta Usa una interfaz de Private Service Connect con la VPC compartida.

Desde el código del agente, llama al proxy de API en https://APIGEE_HOSTNAME/BASE_PATH. Dentro del entorno de Agent Runtime, este nombre de host se resuelve a través del intercambio de tráfico de DNS en PSC_ENDPOINT_IP, y la solicitud atraviesa el extremo de Private Service Connect hacia tu VPC y hacia Apigee.

Verifica la ruta privada

Después de implementar el agente, verifica que las solicitudes lleguen a Apigee a través de la ruta privada:

  • Confirma que el estado de la regla de reenvío sea ACCEPTED con el comando de Crea el extremo de Private Service Connect.
  • Desde una VM de Compute Engine conectada a VPC_NAME en REGION (en una implementación de VPC compartida, esta VM puede estar en el proyecto host o en un proyecto de servicio conectado a la VPC compartida), ejecuta dig +short APIGEE_HOSTNAME. El resultado debe ser PSC_ENDPOINT_IP. Esto confirma que la zona privada resuelve el nombre de host correctamente dentro de la VPC.
  • Desde la misma VM, envía una solicitud a un proxy de API implementado en https://APIGEE_HOSTNAME/BASE_PATH y confirma que recibes la respuesta esperada.
  • Invoca el agente implementado y confirma que se entregó la solicitud. Luego, usa Apigee Analytics o Debug para confirmar que la solicitud llegó al proxy de API esperado en el nombre de host del grupo de entornos.

¿Qué sigue?