Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Salida de Agent Gateway desde Agent Runtime al MCP de Google

1. Introducción

En este codelab, se explora la gobernanza de salida de Agent Gateway para los agentes de IA que acceden a servidores remotos del Protocolo de contexto del modelo (MCP) de Google Cloud.

Las apps basadas en IA, desde chatbots independientes hasta sistemas autónomos con flujos de trabajo multiagente, pueden invocar herramientas externas de forma dinámica. Proporcionar a los agentes acceso controlado para consultar bases de datos, recuperar contenido web y ejecutar acciones es fundamental para que sean seguros y productivos. Sin embargo, en los entornos empresariales, proteger la ejecución de herramientas del agente es un desafío. Si un agente tiene acceso directo a la red, los ataques de inyección de instrucciones o las alucinaciones del modelo pueden hacer que el agente filtre datos sensibles o ejecute comandos destructivos.

Para administrar agentes autónomos a gran escala, Agent Gateway proporciona un punto de aplicación centralizado de confianza cero integrado directamente en la arquitectura de Agent Platform. En lugar de depender de implementaciones personalizadas exclusivas para cada aplicación o código de agente, Agent Gateway proporciona enrutamiento de red, administración de agentes y seguridad en el tiempo de ejecución que se aplican a nivel de la plataforma.

Cuando Agent Gateway opera en modo de salida (agent-to-anywhere), reenvía todas las solicitudes salientes de los agentes configurados para usar la puerta de enlace. Cada solicitud de carga de trabajo del agente se autentica con la identidad del agente única y se autoriza con las políticas de Identity-Aware Proxy (IAP). Las llamadas a la herramienta del MCP se decodifican y se inspeccionan de forma dinámica para aplicar las políticas. Los administradores de seguridad pueden aplicar de forma centralizada permisos detallados para garantizar que los agentes solo puedan invocar extremos y métodos aprobados.

Qué compilarás

Agent Gateway en modo de salida (del agente a cualquier lugar)
Extensión de autorización de Identity-Aware Proxy (IAP)
Agente de Agent Runtime ADK con identidad del agente
Agent Registry con extremos de la API de Google y de MCP
Políticas de autorización con control de acceso de IAM
Conjunto de datos de BigQuery para consultar con MCP

Fig. 1: Arquitectura del codelab

Qué aprenderá

Cómo implementar Agent Gateway en una secuencia de configuración estructurada
Cómo realizar la transición de las políticas de autorización del modo de ejecución de prueba al modo de aplicación forzosa
Cómo registrar extremos de la API de Google y servidores MCP en Agent Registry
Cómo auditar los registros de Agent Gateway para validar la administración de la salida

Requisitos

Un proyecto de Google Cloud con la facturación habilitada.
Permisos de IAM para aprovisionar servicios de redes, conjuntos de datos de BigQuery y recursos de Agent Platform
Un shell compatible con POSIX (bash o zsh) con Google Cloud CLI (componentes gcloud y bq) instalado
Herramientas de línea de comandos: git, curl, jq (procesador JSON), Python 3 y uv (administrador de paquetes de Python)

2. Conceptos

Secuencia de implementación

Cuando implementes Agent Gateway con controles de administración, es importante que sigas una secuencia de configuración estructurada para que los agentes tengan acceso a los recursos necesarios en la inicialización y las solicitudes de red se realicen correctamente.

En este codelab, se usa la siguiente secuencia de implementación:

Iniciar en modo de prueba: Si se configura un tiempo de ejecución del agente para enrutar llamadas salientes a la puerta de enlace antes de que esta se aprovisione por completo, no se podrá inicializar la carga de trabajo. Configurar primero la extensión de autorización de la puerta de enlace en el modo DRY_RUN garantiza que no se descarten solicitudes cuando el tráfico del agente llegue a la puerta de enlace.
Registra todos los servicios: Todos los agentes, servidores de MCP y extremos que usan Agent Gateway deben registrarse en Agent Registry. Las solicitudes se rechazan para cualquier origen o destino no registrado. Los agentes implementados en Agent Runtime y los servidores de MCP de Google se registran automáticamente. Cualquier endpoint de API de Google o servidor MCP personalizado se debe registrar de forma manual.
Aplica políticas de autorización: Las políticas de autorización se usan para permitir que los agentes registrados accedan a los componentes agenticos otorgando el rol roles/iap.egressor a la principal de identidad del agente y vinculándolo al recurso de registro de destino. Evalúa el comportamiento del agente con el modo de ejecución de prueba y, luego, define políticas para permitir el tráfico de salida elegido a través de la puerta de enlace. Una vez que se establezcan las políticas, cambia al modo ENFORCED para permitir que la puerta de enlace aplique de forma activa las políticas de gobernanza.

Fig. 2: Secuencia de implementación

Topología de enrutamiento de salida

Por lo general, las puertas de enlace administran el tráfico entrante (entrada) a los servicios de backend. Agent Gateway, que opera en modo de salida (agente a cualquier destino), actúa como un proxy saliente centralizado y de confianza cero para las cargas de trabajo basadas en agentes.

Cuando una app de IA o una carga de trabajo con agentes intenta invocar una herramienta o API externa, Agent Gateway intercepta la solicitud saliente y la evalúa según las políticas de gobernanza antes de enrutarla a su destino:

Redes privadas (VPC): Tráfico saliente dirigido a APIs internas de la empresa, microservicios, bases de datos alojadas en VPC privadas y redes locales o entre nubes a las que se puede acceder a través de conectividad híbrida.
Redes externas (Internet): Tráfico saliente que se dirige a servicios web de terceros, APIs de SaaS o extremos públicos.
Servicios de IA y Agent Platform: Tráfico saliente que segmenta las APIs de Cloud administradas de Google, los modelos de base, los extremos de MCP de Google (como BigQuery) y los servicios de administración de la plataforma (políticas de Agent Registry y de IAP).

Fig. 3: Topología de enrutamiento de salida de Agent Gateway

El objetivo de este Codelab es el tráfico saliente de un agente personalizado en Agent Runtime que se dirige al extremo del servidor de MCP remoto de Google para BigQuery.

3. Configuración

Roles de IAM obligatorios

Se requieren los siguientes roles para crear los recursos en este codelab:

Categoría	Rol de IAM requerido (ID)	Descripción
Administración de API	`roles/serviceusage.serviceUsageAdmin`	Habilita los servicios de la API de Google Cloud
Redes y puerta de enlace	`roles/networkservices.admin`	Aprovisiona Agent Gateway
Service Extensions	`roles/serviceextensions.admin`	Configura las extensiones de enrutamiento
Seguridad de red	`roles/networksecurity.admin`	Implementa políticas de autorización
Agent Registry	`roles/agentregistry.admin`	Hosts permitidos del catálogo
Vertex AI y agentes	`roles/aiplatform.admin`	Implementa cargas de trabajo de Agent Runtime
Políticas de salida	`roles/iap.admin`	Aplica políticas de `roles/iap.egressor`
BigQuery	`roles/bigquery.admin`	Configura esquemas y conjuntos de datos de prueba
Cloud Storage	`roles/storage.admin`	Administra buckets de etapa de pruebas de implementación
Registros y auditoría	`roles/logging.viewer`	Cómo inspeccionar registros y registros de auditoría

Como alternativa, usa un rol básico amplio, como roles/admin, o un rol heredado, como roles/owner.

Accede a tu proyecto

En este codelab, se usa un solo proyecto de Google Cloud. En los pasos de configuración, se usan la CLI de gcloud y los comandos de shell de Linux.

Para comenzar, accede a la línea de comandos de tu proyecto de Google Cloud:

Cloud Shell en shell.cloud.google.com
Una terminal local con la CLI de gcloud instalada

Establece tu ID del proyecto

gcloud config set project SET_YOUR_PROJECT_ID_HERE

Autentica la sesión

# login to gcloud cli
gcloud auth login

# login for gcloud api
gcloud auth application-default login

Establece variables de entorno de shell

# set custom var for slug (eg, "foo") and region preference
export SLUG="foo"
export REGION="us-central1"
export MREGION="us"
echo ${SLUG}
echo ${REGION}
echo ${MREGION}

# create project vars (automatic)
export PROJ_ID=$(gcloud config list --format="value(core.project)")
export PROJ_NO=$(gcloud projects describe ${PROJ_ID} --format="value(projectNumber)")
export ORG_ID=$(gcloud projects get-ancestors ${PROJ_ID} --format="value(id)" | tail -n 1)
echo ${PROJ_ID}
echo ${PROJ_NO}
echo ${ORG_ID}

# create resource vars (automatic)
export AGW_NAME="agw-${SLUG}-${REGION}-ata"
export AGW_URI="projects/${PROJ_ID}/locations/${REGION}/agentGateways/${AGW_NAME}"
export RE_AGENT_NAME="agent-dj"
export RE_AGENT_ID_SET="principalSet://agents.global.org-${ORG_ID}.system.id.goog/attribute.platformContainer/aiplatform/projects/${PROJ_NO}"
export STAGING_BUCKET="agent-staging-${PROJ_NO}"
echo ${AGW_NAME}
echo ${AGW_URI}
echo ${RE_AGENT_NAME}
echo ${RE_AGENT_ID_SET}
echo ${STAGING_BUCKET}

# create local dir for config files
mkdir -p cfg

Habilita los servicios de la API

# enable google apis (agent platform bundle, part 1)
gcloud services enable \
  agentregistry.googleapis.com \
  aiplatform.googleapis.com \
  apphub.googleapis.com \
  apptopology.googleapis.com \
  cloudapiregistry.googleapis.com \
  cloudtrace.googleapis.com \
  compute.googleapis.com \
  dataform.googleapis.com \
  iam.googleapis.com \
  iamconnectors.googleapis.com \
  iap.googleapis.com \
  logging.googleapis.com \
  modelarmor.googleapis.com \
  monitoring.googleapis.com \
  networksecurity.googleapis.com \
  networkservices.googleapis.com \
  notebooks.googleapis.com \
  observability.googleapis.com

# enable google apis (agent platform bundle, part 2)
gcloud services enable \
  securitycenter.googleapis.com \
  saasservicemgmt.googleapis.com \
  storage.googleapis.com \
  telemetry.googleapis.com \
  texttospeech.googleapis.com \
  discoveryengine.googleapis.com

Aquí concluye la parte de configuración… a continuación, se abordará la sección Puerta de enlace.

4. Puerta de enlace

Antes de aplicar los controles de acceso, implementa Agent Gateway y configura su extensión de autorización en el modo DRY_RUN. Esto permite que las llamadas a herramientas salientes se realicen correctamente y, al mismo tiempo, se registren los resultados de la evaluación para fines de auditoría.

Aquí, Agent Gateway usa un registro regional para admitir recursos de Agent Runtime regionales.

Crear puerta de enlace

# create agent gateway config file (regional registry)
cat > cfg/${AGW_NAME}.yaml << EOF
name: ${AGW_NAME}
protocols:
  - MCP
googleManaged:
  governedAccessPath: AGENT_TO_ANYWHERE
registries:
  - "//agentregistry.googleapis.com/projects/${PROJ_ID}/locations/${REGION}"
EOF

# import agent gateway config file (create gateway)
gcloud network-services agent-gateways import ${AGW_NAME} \
  --source="cfg/${AGW_NAME}.yaml" \
  --location=${REGION}

# show agent gateway details (verify deployment state)
gcloud network-services agent-gateways describe ${AGW_NAME} \
  --location=${REGION}

Aquí concluye la parte de la puerta de enlace… a continuación, veremos la sección de Autorización.

5. Autorización

La extensión de autorización de Agent Gateway para Identity-Aware Proxy (IAP) es un tipo de extensión de servicio que se usa para delegar decisiones de autorización para todas las comunicaciones de Agent Platform.

Flujo de delegación: Cuando un agente intenta invocar un extremo externo o un servidor de MCP, enruta la solicitud a Agent Gateway. En lugar de evaluar el acceso de forma local, la puerta de enlace usa la extensión de autorización para enviar una llamada al servicio de evaluación de IAP. IAP evalúa la identidad del agente (basada en SPIFFE) en función de la política de IAM del recurso de destino en Agent Registry. IAP devuelve una decisión ALLOW o DENY a la puerta de enlace, que reenvía el tráfico o lo bloquea con un código de estado HTTP 403 Forbidden.
Modos de aplicación: En el modo DRY_RUN, IAP evalúa las solicitudes y registra las decisiones en Cloud Logging sin bloquear el tráfico. En el modo ENFORCE, se bloquea de inmediato cualquier solicitud de un agente no autorizado o a un destino no registrado.
Capa de vinculación: La extensión de servicio se conecta a Agent Gateway a través de una política de autorización configurada con el perfil REQUEST_AUTHZ.

Extensión de autorización

Crea una extensión de autorización

# create authz extension config file (dry run mode)
cat > cfg/${AGW_NAME}-svc-ext-authz-iap-dryrun.yaml << EOF
name: ${AGW_NAME}-svc-ext-authz-iap-dryrun
service: iap.googleapis.com
failOpen: true
timeout: 1s
metadata:
  iamEnforcementMode: "DRY_RUN"
  iapPolicyVersion: "V1"
EOF

# import authz extension file (create extension)
gcloud service-extensions authz-extensions import ${AGW_NAME}-svc-ext-authz-iap-dryrun \
  --source=cfg/${AGW_NAME}-svc-ext-authz-iap-dryrun.yaml \
  --location=${REGION}

# show authz extension details (verify extension state)
gcloud service-extensions authz-extensions describe ${AGW_NAME}-svc-ext-authz-iap-dryrun \
  --location=${REGION}

Política de autorización

Una política de autorización vincula el proveedor de seguridad (IAP) al recurso de puerta de enlace de destino y especifica el perfil de intercepción (REQUEST_AUTHZ).

Crea una política de autorización

# create authz policy config file (attach dry-run authz extension)
cat > cfg/${AGW_NAME}-authz-policy-profile-iap.yaml << EOF
name: ${AGW_NAME}-authz-policy-profile-iap
target:
  resources:
    - "projects/${PROJ_ID}/locations/${REGION}/agentGateways/${AGW_NAME}"
policyProfile: REQUEST_AUTHZ
action: CUSTOM
customProvider:
  authzExtension:
    resources:
      - "projects/${PROJ_ID}/locations/${REGION}/authzExtensions/${AGW_NAME}-svc-ext-authz-iap-dryrun"
EOF

# import authz policy config file (enable authz policy)
gcloud beta network-security authz-policies import ${AGW_NAME}-authz-policy-profile-iap \
  --source=cfg/${AGW_NAME}-authz-policy-profile-iap.yaml \
  --location=${REGION}

# show authz policy details (verify dry run mode)
gcloud beta network-security authz-policies describe ${AGW_NAME}-authz-policy-profile-iap \
  --location=${REGION}

Con esto, concluye la parte de autorización… a continuación, veremos la sección Codebase.

6. Base de código

El código del agente, el conjunto de datos de BigQuery y la secuencia de comandos de registro que se usan en este codelab se mantienen en un repositorio remoto de GitHub de Google Cloud. En los siguientes pasos, se clonará el repositorio de forma local, se copiarán los archivos necesarios en la estructura del directorio de trabajo actual y, luego, se borrarán los archivos temporales innecesarios.

Se crea un bucket de almacenamiento provisional para que Agent Runtime suba, compile y, luego, implemente el código de la aplicación del agente empaquetado y sus artefactos de dependencia.

Recupera artefactos remotos

# clone remote repository to temp local dir
git clone https://github.com/GoogleCloudPlatform/cloud-networking-solutions.git ./temp_agw_cuj_arun_egress_gmcp

# copy agent runtime and endpoint definitions to working project dir
cp -r temp_agw_cuj_arun_egress_gmcp/codelabs/agw-cuj-arun-egress-gmcp/agent-dj ./agent-dj
cp -r temp_agw_cuj_arun_egress_gmcp/codelabs/agw-cuj-arun-egress-gmcp/endpoints ./endpoints

# remove temporary directory
rm -rf temp_agw_cuj_arun_egress_gmcp

Crea un conjunto de datos de BigQuery

# create bq dataset schema and load data
bq --project_id=${PROJ_ID} query \
  --use_legacy_sql=false < agent-dj/setup.sql

Crea un bucket de etapa de pruebas

# create storage bucket for agent deployment artifacts
gcloud storage buckets create gs://${STAGING_BUCKET} --location=${REGION}

# verify staging bucket url
gcloud storage buckets list --format="value(storage_url)"

Aquí concluye la parte de la base de código. A continuación, se abordará la sección Registro.

7. Registro

Agent Registry es un inventario centralizado de todos los agentes, servidores MCP y extremos (APIs) en el ecosistema de IA. También es un catálogo que se puede usar para enumerar, buscar y descubrir otras herramientas y servicios registrados para su uso en aplicaciones de IA. El modo de salida de Agent Gateway (agent-to-anywhere) usa el modelo de datos del registro como marco de trabajo de administración para aplicar el control de acceso de salida. Los permisos de rol de IAM para los agentes de llamada de la principal se verifican en función de la política vinculada al recurso del registro.

Para iniciar el entorno y brindar asistencia a los agentes con varias APIs y servicios de Google, se usa una secuencia de comandos para registrar rápidamente un conjunto común de extremos de API con nombres de host y ubicaciones de endpoints/googleapis.txt.

Registra extremos

# run python script to register google api endpoints
python3 endpoints/register_endpoints.py \
  --multi-region=${MREGION} \
  --region=${REGION} \
  --mtls-endpoints=include

Verifica los extremos

# list regional endpoints (verify registration)
gcloud agent-registry endpoints list --location=${REGION} \
  --format="table(displayName, name.basename():label=ENDPOINT_ID, interfaces[0].url:label=URL)"

Con esto, concluye la parte del registro. A continuación, se abordará la sección Runtime.

8. Entorno de ejecución

El agente del ADK de agent-dj implementado en Agent Runtime se configura con los siguientes parámetros en la secuencia de comandos de implementación para integrarse con Agent Platform:

"identity_type": types.IdentityType.AGENT_IDENTITY para aprovisionar una identidad principal única basada en SPIFFE para el agente
"agent_gateway_config": { "agent_to_anywhere_config": {"agent_gateway": } } para dirigir todo el tráfico saliente iniciado por el agente a Agent Gateway para la evaluación y aplicación de políticas

Implementa el agente

# deploy agent runtime workload
uv --directory agent-dj run python3 deploy_agent.py \
  --project=${PROJ_ID} \
  --region=${REGION} \
  --src-dir=./agent \
  --staging-bucket=${STAGING_BUCKET} \
  --display-name="${RE_AGENT_NAME}" \
  --description="agent for dj contact info" \
  --enable-telemetry \
  --enable-agent-identity \
  --agent-gateway-egress=${AGW_URI} \
  --allow-token-sharing

Recupera los signos vitales de la implementación

# fetch agent runtime resource (reasoning engine) id
export RE_ENGINE_ID=$(curl -s -X GET \
  "https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" | \
  jq -r --arg name "${RE_AGENT_NAME}" \
  '.reasoningEngines[] | select(.displayName==$name) | .name | split("/") | last')
echo ${RE_ENGINE_ID}

# fetch agent runtime (reasoning engine) agent identity
export RE_AGENT_IDENTITY=$(gcloud agent-registry agents list \
  --location=${REGION} --filter="displayName=${RE_AGENT_NAME}" \
  --format="value(attributes.'agentregistry.googleapis.com/system/RuntimeIdentity'.principal)")
echo ${RE_AGENT_IDENTITY}

# fetch agent registry uid for agent
export AGENT_UID=$(gcloud agent-registry agents list \
  --location=${REGION} \
  --filter="displayName=${RE_AGENT_NAME}" \
  --format="value(uid)")
echo ${AGENT_UID}

Verifica la entrada del registro

# show agent resource registry details
gcloud agent-registry agents describe ${AGENT_UID} --location=${REGION}

agentId: urn:agent:projects-${PROJ_NO}:projects:${PROJ_NO}:locations:${REGION}:aiplatform:reasoningEngines:${RE_ENGINE_ID}
attributes:
  agentregistry.googleapis.com/system/Framework:
    framework: google-adk
  agentregistry.googleapis.com/system/RuntimeIdentity:
    principal: principal://agents.global.org-${PROJ_NO}.system.id.goog/resources/aiplatform/projects/${PROJ_NO}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}
  agentregistry.googleapis.com/system/RuntimeReference:
    uri: //aiplatform.googleapis.com/projects/${PROJ_NO}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}
createTime: 'YYYY-MM-DDTHH:MM:SS.ssssssZ'
description: agent for dj contact info
displayName: agent-dj
name: projects/${PROJ_ID}/locations/${REGION}/agents/agentregistry-${RE_AGENT_ID}
protocols:
- interfaces:
  - protocolBinding: HTTP_JSON
    url: https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}:query
  - protocolBinding: HTTP_JSON
    url: https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}:streamQuery
  type: CUSTOM
uid: agentregistry-00000000-0000-0000-1234-4567abcd1234
updateTime: 'YYYY-MM-DDTHH:MM:SS.ssssssZ'

Verifica la configuración de la puerta de enlace

# verify agent gateway routing specification
curl -s -X GET "https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  | jq '{displayName: .displayName, name: .name, effectiveIdentity: .spec.effectiveIdentity, agentGatewayConfig: .spec.deploymentSpec.agentGatewayConfig}'

Otorga roles de IAM de agente para los recursos

Las concesiones de roles de IAM para los recursos permiten que la identidad principal del agente acceda a BigQuery, a las herramientas de MCP (para las APIs de Google) y a otros servicios requeridos de la plataforma de IA. Estas políticas se aplican con IAM a nivel del recurso.

# grant bigquery query execution role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/bigquery.user"

# grant bigquery data viewer role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/bigquery.dataViewer"

# grant mcp tool execution role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/mcp.toolUser"

# grant ai platform user role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/aiplatform.user"

# grant agent default access role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/aiplatform.agentDefaultAccess"

# grant agent registry viewer role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/agentregistry.viewer"

# grant cloud logging writer role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/logging.logWriter"

# grant cloud monitoring writer role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/monitoring.metricWriter"

# grant browser role for resource manager lookup
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/browser"

Verifica los roles de IAM del agente para los recursos

# verify active role bindings for agent identity
gcloud projects get-iam-policy ${PROJ_ID} \
  --flatten="bindings[].members" \
  --filter="bindings.members:${RE_AGENT_IDENTITY}" \
  --format="value(bindings.role)"

Aquí concluye la parte del tiempo de ejecución… a continuación, se encuentra la sección Políticas.

9. Políticas

Las políticas de autorización de la administración de agentes permiten el tráfico de un agente de IA a través de Agent Gateway y hacia el destino (p. ej., el extremo del servidor de MCP de Google Cloud para BigQuery). Una vez que el tráfico llega al destino, los permisos de IAM normales autorizan el acceso a los datos (y se habilitaron en la sección anterior).

Los otorgamientos de roles de IAM para la salida de Agent Gateway habilitan políticas de acceso que permiten que la identidad principal del agente acceda a los recursos de destino registrados a través de Agent Gateway. Las políticas se aplican a nivel de Agent Gateway y se validan con las políticas de IAM de Identity-Aware Proxy (IAP).

Otorga roles de IAM de agente para la salida de Agent Gateway

Agent Gateway verifica las solicitudes entrantes para validar que la identidad del agente que llama tenga el permiso iap.webServiceVersions.egressViaIAP (otorgado por el rol roles/iap.egressor) en el recurso de destino.

Otorgar roles/iap.egressor a la identidad del agente o al conjunto de principales de Agent Runtime en el recurso de destino seleccionado permite este tráfico de salida. En este codelab, el rol se aplica a la principal set, que otorga permiso a todas las identidades de los agentes de Agent Runtime en el proyecto.

Las políticas de IAM están vinculadas a los recursos de destino según se definen en el modelo de datos del Registro de agentes. El recurso iap_web/agentRegistry representa un nivel "en todo el registro" en la jerarquía de IAM. Aquí, agentRegistry actúa como el elemento superior de los recursos secundarios individuales de agents, mcpServers y endpoints. En este codelab, la política de IAM está vinculada al nivel del registro, lo que aplica el permiso a todos los recursos secundarios.

Configura la política de IAM del registro regional de IAP

# show iap iam policy for regional registry
gcloud beta iap web get-iam-policy --resource-type=agent-registry --region=${REGION}

# retrieve active etag on policy for regional registry
export IAP_ETAG=$(gcloud beta iap web get-iam-policy --resource-type=agent-registry --region=${REGION} --format="value(etag)")
echo ${IAP_ETAG}

# create policy config file
cat > cfg/iap-policy-re-agent-set-to-registry-${REGION}.json << EOF
{
  "bindings": [
    {
      "role": "roles/iap.egressor",
      "members": [
        "${RE_AGENT_ID_SET}"
      ]
    }
  ],
  "etag": "${IAP_ETAG}"
}
EOF

# import policy file (bind iam policy)
gcloud beta iap web set-iam-policy cfg/iap-policy-re-agent-set-to-registry-${REGION}.json \
  --resource-type=agent-registry \
  --region=${REGION}

# verify iap iam policy for regional registry
gcloud beta iap web get-iam-policy --resource-type=agent-registry --region=${REGION}

Aquí concluye la sección de políticas. A continuación, se abordará la sección de Auditoría.

10. Auditoría

La extensión de autorización de Agent Gateway funciona en modo DRY_RUN. Se observan y registran las solicitudes salientes, pero no se bloquean.

Prueba las preguntas del agente

Abre una ventana del navegador en la IU de la consola de Google Cloud y navega a la siguiente ubicación:

Agent Platform → Agents → Deployments → agent-dj
Selecciona la pestaña Playground.

O bien, haz eco de este comando de terminal y haz clic en el vínculo para ir al Playground del agente:

# playground
echo "https://console.cloud.google.com/agent-platform/runtimes/locations/${REGION}/agent-engines/${RE_ENGINE_ID}/playground?project=${PROJ_ID}"

Envía algunas búsquedas de prueba…

How many DJs do we have on file?
What is the phone number of DJ Cosmopup?

Verifica que las búsquedas devuelvan respuestas válidas (p. ej., "Hay 12 DJs en el archivo").

Analiza los registros de auditoría

Consulta los registros y, luego, inspecciona las evaluaciones de las políticas de prueba de validación.

# query gateway logs for dry run
gcloud logging read \
  "resource.type=\"networkservices.googleapis.com/Gateway\" \
  AND httpRequest.requestUrl:*" \
  --project=${PROJ_ID} \
  --limit=10 \
  --format="table(
    timestamp.date(tz=LOCAL):label=TIMESTAMP,
    httpRequest.requestMethod:label=METHOD,
    httpRequest.status:label=STATUS,
    jsonPayload.authzPolicyInfo.result:label=IAP_AUTHZ,
    jsonPayload.agentGatewayInfo.mcpInfo.method:label=MCP_METHOD,
    httpRequest.requestUrl:label=URL
  )"

TIMESTAMP            METHOD  STATUS  IAP_AUTHZ  MCP_METHOD  URL
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED                https://telemetry.googleapis.com/v1/traces
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED                https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}/sessions/${RE_SESSION_ID}:appendEvent
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED                https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/publishers/google/models/gemini-2.5-flash:generateContent
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED                https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}/sessions/${RE_SESSION_ID}:appendEvent
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED    tools/call  https://bigquery.googleapis.com/mcp
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED                https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}/sessions/${RE_SESSION_ID}:appendEvent
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED                https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/publishers/google/models/gemini-2.5-flash:generateContent
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED    tools/call  https://bigquery.googleapis.com/mcp
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED                https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/publishers/google/models/gemini-2.5-flash:generateContent
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED    tools/call  https://bigquery.googleapis.com/mcp

Aquí concluye la parte de la auditoría. A continuación, se abordará la sección Aplicar.

11. Aplicar

El agente pudo realizar solicitudes exitosas a través de la puerta de enlace en modo DRY_RUN. Actualiza la política de autorización para realizar la transición de la extensión de autorización del IAP de Agent Gateway al modo ENFORCE.

Actualiza la extensión de autorización

# create authz extension config file (enforced mode)
cat > cfg/${AGW_NAME}-svc-ext-authz-iap-enforced.yaml << EOF
name: ${AGW_NAME}-svc-ext-authz-iap-enforced
service: iap.googleapis.com
failOpen: false
timeout: 1s
metadata:
  iapPolicyVersion: "V1"
EOF

# import authz extension file (create extension)
gcloud service-extensions authz-extensions import ${AGW_NAME}-svc-ext-authz-iap-enforced \
  --source=cfg/${AGW_NAME}-svc-ext-authz-iap-enforced.yaml \
  --location=${REGION}

# list authz extensions (imported configs)
gcloud service-extensions authz-extensions list --location=${REGION}

Actualiza la política de autorización

# re-write authz policy config file (pointing to enforced authz extension)
cat > cfg/${AGW_NAME}-authz-policy-profile-iap.yaml << EOF
name: ${AGW_NAME}-authz-policy-profile-iap
target:
  resources:
    - "projects/${PROJ_ID}/locations/${REGION}/agentGateways/${AGW_NAME}"
policyProfile: REQUEST_AUTHZ
action: CUSTOM
customProvider:
  authzExtension:
    resources:
      - "projects/${PROJ_ID}/locations/${REGION}/authzExtensions/${AGW_NAME}-svc-ext-authz-iap-enforced"
EOF

# import authz policy config file (enable new authz policy)
gcloud beta network-security authz-policies import ${AGW_NAME}-authz-policy-profile-iap \
  --source=cfg/${AGW_NAME}-authz-policy-profile-iap.yaml \
  --location=${REGION}

# show authz policy details (verify enforced mode)
gcloud beta network-security authz-policies describe ${AGW_NAME}-authz-policy-profile-iap \
  --location=${REGION}

Verifica la aplicación

Regresa al Playground del agente en la IU de la consola.

Envía una consulta de prueba adicional…

What DJ Fishfry's credit card number?

Observa que las solicitudes del agente al modelo fundamental de Gemini (${REGION}-aiplatform.googleapis.com/...) y al extremo del servidor de MCP (bigquery.googleapis.com/mcp) se pasan con códigos de estado HTTP 200 OK.

# show gateway logs for http requests
gcloud logging read \
  "resource.type=\"networkservices.googleapis.com/Gateway\" \
  AND httpRequest.requestUrl:*" \
  --project=${PROJ_ID} \
  --limit=10 \
  --format="table(
    timestamp.date(tz=LOCAL):label=TIMESTAMP,
    httpRequest.requestMethod:label=METHOD,
    httpRequest.status:label=STATUS,
    jsonPayload.authzPolicyInfo.result:label=IAP_AUTHZ,
    jsonPayload.agentGatewayInfo.mcpInfo.method:label=MCP_METHOD,
    httpRequest.requestUrl:label=URL)"

Comprueba que no se bloquee ninguna solicitud. Busca cualquier intento de salida rechazado con códigos de estado HTTP 403 Forbidden en los registros de auditoría de la puerta de enlace.

# show gateway logs for authz denies
gcloud logging read \
  "resource.type=\"networkservices.googleapis.com/Gateway\" \
  AND (jsonPayload.authzPolicyInfo.result=\"DENIED\" OR httpRequest.status=403)" \
  --project=${PROJ_ID} \
  --limit=10 \
  --format="table(
    timestamp.date(tz=LOCAL):label=TIMESTAMP,
    httpRequest.requestMethod:label=METHOD,
    httpRequest.status:label=STATUS,
    jsonPayload.enforcedGatewaySecurityPolicy.serverNameIndication:label=SNI,
    jsonPayload.authzPolicyInfo.result:label=AUTHZ_RESULT,
    jsonPayload.authzPolicyInfo.policies[0].name.basename():label=DENYING_POLICY
  )"

Aquí concluye la parte de aplicación… a continuación, veremos la sección Limpieza.

12. Limpieza

# delete agent
curl -s -X DELETE "https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}?force=true" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)"

# next

# remove agent resource iam bindings
for ROLE in \
  "roles/bigquery.user" \
  "roles/bigquery.dataViewer" \
  "roles/mcp.toolUser" \
  "roles/aiplatform.user" \
  "roles/aiplatform.agentDefaultAccess" \
  "roles/agentregistry.viewer" \
  "roles/logging.logWriter" \
  "roles/monitoring.metricWriter" \
  "roles/browser"; do
  gcloud -q projects remove-iam-policy-binding ${PROJ_ID} \
    --member="${RE_AGENT_IDENTITY}" \
    --role="${ROLE}"
done

# next

# delete storage bucket
gcloud -q storage rm --recursive gs://${STAGING_BUCKET}

# delete bigquery dataset and contents
bq rm -r -f -d ${PROJ_ID}:dj_ds

# next

# reset/clear iap regional registry iam policy
export IAP_ETAG=$(gcloud beta iap web get-iam-policy --resource-type=agent-registry --region=${REGION} --format="value(etag)")
cat > cfg/iap-policy-empty.json << EOF
{
  "bindings": [],
  "etag": "${IAP_ETAG}"
}
EOF

gcloud beta iap web set-iam-policy cfg/iap-policy-empty.json \
  --resource-type=agent-registry \
  --region=${REGION}

# next

# delete gateway resources
gcloud -q beta network-security authz-policies delete ${AGW_NAME}-authz-policy-profile-iap --location=${REGION}

gcloud -q beta service-extensions authz-extensions delete ${AGW_NAME}-svc-ext-authz-iap-dryrun --location=${REGION}

gcloud -q network-services agent-gateways delete ${AGW_NAME} --location=${REGION}

# next

# clean up local working directories and generated configs
rm -rf cfg agent-dj endpoints

# end

Aquí concluye la sección de limpieza. A continuación, veremos la Conclusión.

13. Conclusión

¡Felicitaciones! Implementaste y controlaste correctamente las comunicaciones salientes de un agente que accede a herramientas con Agent Gateway.

cosmopup

Cosmopup cree que los codelabs son lo mejor.

¿Qué sigue?

Consulta la documentación de Gemini Enterprise Agent Platform para conocer las funciones avanzadas y los instructivos.
Configura barreras de seguridad de Model Armor en Agent Gateway para mayor seguridad potenciada por IA
Explora las políticas de administración semántica para aplicar reglas comerciales y de cumplimiento a las búsquedas en lenguaje natural

Si tienes comentarios, preguntas o correcciones, usa este formulario de comentarios.

¡Gracias!