Conecta el procesador de extensiones de Apigee a un Agent Gateway

Esta página se aplica a Apigee y Apigee Hybrid.

Consulta la documentación de Apigee Edge.

En esta página, se describe cómo conectar el procesador de extensiones de Apigee a una Agent Gateway para que las políticas de Apigee se apliquen a las llamadas que un agente de IA realiza a su modelo, sus herramientas y los servidores del Protocolo de contexto del modelo (MCP) que usa, sin cambiar el agente.

Una Agent Gateway es el punto de entrada y salida de la red para el tráfico de un agente. No es un balanceador de cargas, por lo que no usa una extensión de tráfico. En su lugar, la puerta de enlace delega la autorización a una extensión de autorización, y tú configuras el procesador de extensiones como esa extensión. Una vez que se conecta, la puerta de enlace envía cada solicitud y respuesta del agente a Apigee para su procesamiento, y Apigee devuelve un veredicto.

En la siguiente figura, se muestran los recursos que creas en esta página y la ruta que sigue una sola solicitud del agente a través de ellos:

Una solicitud del agente se retiene en el Agent Gateway, se envía a Apigee a través de Private Service Connect para obtener un veredicto y, luego, se reenvía.
Figura 1: Componentes y flujo de solicitudes cuando el procesador de extensiones de Apigee es la extensión de autorización para una puerta de enlace de Agent Gateway.

En la figura 1, una solicitud se controla de la siguiente manera:

  1. El agente realiza una solicitud HTTPS normal a su modelo, una herramienta o un servidor de MCP. El agente se vincula a la puerta de enlace cuando se crea y no necesita cambios.
  2. La puerta de enlace retiene la solicitud y llama a la extensión de autorización para obtener un veredicto.
  3. La llamada sale a través del adjunto de red, por lo que se origina dentro de tu red de VPC.
  4. Tu zona de DNS privada resuelve el nombre de host de la llamada al host en la dirección IP interna del extremo de Private Service Connect.
  5. El extremo reenvía la devolución de llamada al adjunto de servicio de tu instancia de Apigee.
  6. El grupo de entornos enruta la llamada externa por su nombre de host al proxy sin destino, donde se ejecutan tus políticas.
  7. El proxy devuelve un veredicto a la puerta de enlace. Apigee nunca reenvía el tráfico del agente, ya que el proxy no tiene destino.
  8. Si el veredicto permite la solicitud, la puerta de enlace envía la solicitud original a su destino.

Los elementos AuthzPolicy y AuthzExtension de la figura 1 son de configuración, no de tráfico: la política adjunta la extensión a la puerta de enlace, y la extensión nombra el proxy del procesador de extensiones que se ejecuta. Ambos se crean en Configura la extensión de autorización.

Para conectar el procesador de extensiones a un balanceador de cargas, consulta Comienza a usar el procesador de extensiones de Apigee.

En las siguientes secciones, se te guiará a través de los pasos:

Antes de comenzar

Antes de comenzar, completa las siguientes tareas:

  1. Accede a tu cuenta de Google Cloud . Si eres nuevo en Google Cloud, crea una cuenta para evaluar el rendimiento de nuestros productos en situaciones reales. Los clientes nuevos también obtienen $300 en créditos gratuitos para ejecutar, probar y, además, implementar cargas de trabajo.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Enable the Apigee, Compute Engine, Network Services, Network Security, and Cloud DNS APIs, if any are not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the APIs

  5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  6. Verify that billing is enabled for your Google Cloud project.

  7. Enable the Apigee, Compute Engine, Network Services, Network Security, and Cloud DNS APIs, if any are not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the APIs

    8.

  8. Instala la Google Cloud CLI.

    Después de instalar Google Cloud CLI, ejecuta el comando gcloud components update para obtener los componentes de gcloud más recientes.

  9. Aprovisiona una instancia de Apigee si aún no lo hiciste.

    En la consola de Google Cloud , ve a la página Instancias de Apigee.

    Ir a Instancias de Apigee

  10. Implementa un Agent Gateway en la misma región que tu instancia de Apigee, con governedAccessPath configurado como AGENT_TO_ANYWHERE para que la puerta de enlace controle el tráfico saliente del agente. Para obtener más información, consulta Configura Agent Gateway.

    Actualizarás la configuración de red de esta puerta de enlace más adelante, en Actualiza la puerta de enlace del agente, después de que exista la zona DNS.

  11. Confirma que tienes una VPC y una subred que tanto el Agent Gateway como el extremo de Private Service Connect pueden usar.

    Ir a Redes de VPC

Roles obligatorios

Para obtener los permisos que necesitas para conectar el procesador de extensiones de Apigee a una puerta de enlace del agente, pídele a tu administrador que te otorgue los siguientes roles de IAM:

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.

Configura las variables de entorno

Configura las siguientes variables de entorno para identificar los recursos que creaste en Antes de comenzar. Cada sección posterior de esta página define las variables adicionales que necesita, en el punto en el que creas el recurso que nombran.

export PROJECT_ID=PROJECT_ID
export ORG_NAME=$PROJECT_ID
export REGION=REGION
export INSTANCE=INSTANCE
export VPC_NETWORK_NAME=VPC_NETWORK_NAME
export SUBNET=SUBNET
export GATEWAY=GATEWAY

Aquí:

  • PROJECT_ID es el ID del proyecto que contiene tu instancia de Apigee.
  • REGION es la Google Cloud región de tu instancia de Apigee.
  • INSTANCE es el nombre de tu instancia de Apigee.
  • VPC_NETWORK_NAME y SUBNET son la red de VPC y la subred que usan el Agent Gateway y el extremo de Private Service Connect.
  • GATEWAY es el nombre del Agent Gateway que implementaste.

Para confirmar que las variables de entorno estén configuradas correctamente, ejecuta el siguiente comando y revisa el resultado:

echo $PROJECT_ID $ORG_NAME $REGION $INSTANCE $VPC_NETWORK_NAME $SUBNET $GATEWAY

Elige el nombre de host del texto destacado

La puerta de enlace llega a Apigee en un nombre de host privado que elijas. Lo eliges ahora, antes de crear cualquier elemento, porque el primer recurso que creas (el grupo de entornos de Apigee) lo usa como nombre de host, mientras que la zona de DNS que lo resuelve no se crea hasta que crees una zona de DNS privada.

export DNS_DOMAIN=DNS_DOMAIN
export EXTPROC_HOST=apigee-extproc.$DNS_DOMAIN

Aquí, DNS_DOMAIN es un dominio de DNS privado que no tiene que resolverse en Internet pública, escrito sin un punto final, por ejemplo, internal.example.com. Esto proporciona un EXTPROC_HOST de apigee-extproc.internal.example.com. Puedes usar una etiqueta que no sea apigee-extproc, siempre y cuando el nombre de host permanezca dentro de DNS_DOMAIN.

Configura un token de autenticación

export TOKEN=$(gcloud auth print-access-token)
echo $TOKEN

Configura el procesador de extensiones de Apigee

Nombra los recursos de Apigee que crea esta sección:

export EXTPROC_ENV=EXTPROC_ENV
export EXTPROC_ENVGROUP=EXTPROC_ENVGROUP
export PROXY_NAME=PROXY_NAME

Aquí:

  • EXTPROC_ENV y EXTPROC_ENVGROUP son nombres que eliges para un entorno y un grupo de entornos de Apigee dedicados al procesador de extensiones, por ejemplo, extproc-env y extproc-envgroup. Cada nombre debe tener entre 2 y 32 caracteres de letras minúsculas, números o guiones, debe comenzar con una letra y no puede terminar con un guion. El nombre del entorno debe ser diferente de todos los demás nombres de entorno de tu organización.
  • PROXY_NAME es un nombre que eliges para el proxy del procesador de extensiones, por ejemplo, extproc-authz.

El lado de Apigee de la configuración es el mismo que para un balanceador de cargas. Sigue los pasos para configurar el procesador de extensiones de Apigee en la guía de inicio rápido para hacer lo siguiente:

  1. Crea un entorno de Apigee con la propiedad apigee-service-extension-enabled establecida en true, adjúntalo a tu instancia y crea un grupo de entornos cuyo nombre de host sea $EXTPROC_HOST.
  2. Crea e implementa un proxy del procesador de extensiones sin destino en ese entorno.

Luego, enumera las implementaciones en el entorno:

curl -s -H "Authorization: Bearer $TOKEN" \
  "https://apigee.googleapis.com/v1/organizations/$ORG_NAME/environments/$EXTPROC_ENV/deployments"

El entorno puede tener más de un proxy implementado, por lo que, en la respuesta, busca la entrada cuyo apiProxy sea $PROXY_NAME y anota su revision.

Puedes revisar el proxy en la consola de Google Cloud :

Ir a Proxies de API

Establece la siguiente variable en esa revisión, que necesitarás en Verificar la conexión:

export REVISION=REVISION

Conecta Agent Gateway a Apigee

La puerta de enlace llega a Apigee a través de un extremo de Private Service Connect en tu VPC, que encuentra resolviendo $EXTPROC_HOST en una zona del DNS privada.

Busca el adjunto del servicio

Busca el adjunto de servicio de tu instancia de Apigee:

curl -s -H "Authorization: Bearer $TOKEN" \
  "https://apigee.googleapis.com/v1/organizations/$ORG_NAME/instances"

Establece la siguiente variable en el valor serviceAttachment de la instancia en tu región:

export SERVICE_ATTACHMENT=SERVICE_ATTACHMENT

Crea un adjunto de red

El Agent Gateway sale de tu VPC a través de un adjunto de red. Elige un nombre para él, por ejemplo, agent-gateway-attachment, y créalo:

export NETWORK_ATTACHMENT=NETWORK_ATTACHMENT
gcloud compute network-attachments create $NETWORK_ATTACHMENT \
    --region=$REGION --subnets=$SUBNET --connection-preference=ACCEPT_AUTOMATIC

Crea el extremo de Private Service Connect

Reserva una dirección IP interna y crea el extremo de Private Service Connect:

gcloud compute addresses create apigee-extproc-psc-ip \
    --region=$REGION --subnet=$SUBNET --purpose=GCE_ENDPOINT
gcloud compute forwarding-rules create apigee-extproc-psc-endpoint \
    --region=$REGION --network=$VPC_NETWORK_NAME \
    --address=apigee-extproc-psc-ip \
    --target-service-attachment=$SERVICE_ATTACHMENT

En la consola de Google Cloud , ve a la página Private Service Connect .

Ir a Private Service Connect

Confirma que el extremo informe pscConnectionStatus: ACCEPTED y configura la siguiente variable en su dirección IP:

gcloud compute forwarding-rules describe apigee-extproc-psc-endpoint \
    --region=$REGION --format="value(pscConnectionStatus,IPAddress)"
export PSC_IP=PSC_IP

Si el estado es PENDING, tu proyecto no está en el consumerAcceptList de la instancia de Apigee y no se puede aceptar la conexión.

Crea una zona de DNS privado

Crea una zona de DNS privada para $DNS_DOMAIN y un registro A que resuelva $EXTPROC_HOST en la dirección IP del extremo:

gcloud dns managed-zones create extproc-zone \
    --dns-name=$DNS_DOMAIN. --visibility=private --networks=$VPC_NETWORK_NAME \
    --description="Apigee extension processor callout host"
gcloud dns record-sets create $EXTPROC_HOST. --type=A --ttl=300 \
    --rrdatas=$PSC_IP --zone=extproc-zone

Actualiza Agent Gateway

Actualiza Agent Gateway desde Antes de comenzar para que salga a través de tu adjunto de red y pueda resolver la zona que creaste.

  1. Exporta la configuración actual:

    gcloud network-services agent-gateways export $GATEWAY \
    --location=$REGION --destination=agent-gateway.yaml

  2. En agent-gateway.yaml, agrega el siguiente bloque networkConfig y reemplaza cada marcador de posición por el valor de la variable de entorno correspondiente. El archivo se edita directamente, por lo que las variables de shell no se sustituyen aquí:

    networkConfig:
  egress:
    networkAttachment: projects/PROJECT_ID/regions/REGION/networkAttachments/NETWORK_ATTACHMENT
  dnsPeeringConfig:
    domains: [ DNS_DOMAIN. ]
    targetProject: PROJECT_ID
    targetNetwork: projects/PROJECT_ID/global/networks/VPC_NETWORK_NAME

    Deja el resto del archivo, incluidos googleManaged.governedAccessPath, protocols y registries, como se exportaron.

  3. Importa la configuración editada:

    gcloud network-services agent-gateways import $GATEWAY \
    --location=$REGION --source=agent-gateway.yaml

Para ver el conjunto completo de campos de Agent Gateway, consulta Configura Agent Gateway.

Configura la extensión de autorización

Dos recursos conectan la puerta de enlace a tu proxy del procesador de extensiones: una extensión de autorización que apunta a Apigee y una política de autorización que adjunta la extensión a la puerta de enlace.

Crea la extensión de autorización

Elige un nombre para la extensión de autorización, por ejemplo, apigee-authz-extension. Los campos metadata seleccionan qué proxy de Apigee se ejecuta y si se envían los cuerpos de los mensajes:

export AUTHZ_EXT=AUTHZ_EXT
cat > authz-extension.yaml <<EOF
name: projects/$PROJECT_ID/locations/$REGION/authzExtensions/$AUTHZ_EXT
authority: $EXTPROC_HOST
service: $EXTPROC_HOST
timeout: 5s
metadata:
  apigee-extension-processor: $PROXY_NAME
  apigee-request-body: 'true'
  apigee-response-body: 'true'
EOF
gcloud service-extensions authz-extensions import $AUTHZ_EXT \
    --source=authz-extension.yaml --location=$REGION

Aquí:

  • apigee-extension-processor selecciona el proxy del procesador de extensiones que procesa el tráfico.
  • apigee-request-body y apigee-response-body hacen que los cuerpos de solicitud y respuesta estén disponibles en el proxy como request.content y response.content. Sin ellos, las políticas que inspeccionan la carga útil no encuentran nada.

Crea la política de autorización

Elige un nombre para la política de autorización, por ejemplo, apigee-content-authz-policy. La política adjunta la extensión a la puerta de enlace y determina qué tráfico se envía a Apigee:

export AUTHZ_POLICY=AUTHZ_POLICY
cat > authz-policy.yaml <<EOF
name: projects/$PROJECT_ID/locations/$REGION/authzPolicies/$AUTHZ_POLICY
action: CUSTOM
policyProfile: CONTENT_AUTHZ
customProvider:
  authzExtension:
    resources:
    - projects/$PROJECT_ID/locations/$REGION/authzExtensions/$AUTHZ_EXT
httpRules:
- to:
    operations:
    - paths:
      - prefix: "/"
target:
  resources:
  - projects/$PROJECT_ID/locations/$REGION/agentGateways/$GATEWAY
EOF
gcloud beta network-security authz-policies import $AUTHZ_POLICY \
    --source=authz-policy.yaml --location=$REGION

Usa policyProfile: CONTENT_AUTHZ para que se inspeccionen los cuerpos de los mensajes. Una política de REQUEST_AUTHZ solo evalúa los encabezados de solicitud.

Verifica la conexión

Para generar tráfico, necesitas un agente cuya salida esté regida por esta puerta de enlace. Un agente se vincula a un Agent Gateway cuando se crea, estableciendo su configuración de Agent Gateway del agente en $GATEWAY. No puedes ejercer la conexión con una solicitud HTTP directa al Agent Gateway. Para obtener más información, consulta Configura Agent Gateway.

Inicia una sesión de depuración de Apigee en el proxy del procesador de extensiones y, luego, envía una solicitud a través del agente:

curl -s -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  "https://apigee.googleapis.com/v1/organizations/$ORG_NAME/environments/$EXTPROC_ENV/apis/$PROXY_NAME/revisions/$REVISION/debugsessions?timeout=600" \
  -d '{"count":15,"tracesize":5120,"filter":"(request.uri Like \"*generateContent*\")"}'

En las transacciones capturadas, confirma lo siguiente:

  • La URL de la solicitud es la dirección a la que llamó el agente, como el extremo del modelo o un host de herramientas, en lugar de una ruta base de Apigee.
  • Se completan request.content y response.content, lo que confirma que los metadatos del cuerpo en la extensión de autorización funcionan.

Si no aparecen transacciones, verifica que el nombre de host del grupo de entornos, el registro DNS y los campos authority y service de la extensión sean todos $EXTPROC_HOST, que el extremo de Private Service Connect informe ACCEPTED y que el governedAccessPath de la puerta de enlace sea AGENT_TO_ANYWHERE.

¿Qué sigue?