Configura Model Armor en una puerta de enlace

Model Armor te ayuda a garantizar que tus agentes de IA cumplan con tus estándares de seguridad y gobernanza sin necesidad de implementar lógica de filtrado directamente en los agentes. Cuando configuras Model Armor con Agent Gateway, Model Armor aplica las barreras de seguridad de contenido de tu organización inspeccionando todas las instrucciones y respuestas que pasan por la puerta de enlace. Esta función te permite aplicar medidas de protección de contenido de manera coherente en todos los agentes regidos por la puerta de enlace. Model Armor te ayuda a mitigar riesgos como la inyección de instrucciones, los intentos de jailbreak, la filtración de información sensible y la generación de contenido dañino. Para obtener más información, consulta Filtros de Model Armor.

Plantillas de Model Armor

Para configurar Model Armor en una puerta de enlace, crea plantillas que especifiquen cómo filtrar las instrucciones y las respuestas que reciben y devuelven tus agentes de IA. Las plantillas proporcionan filtros y umbrales personalizados para varias categorías de seguridad. Para obtener más información, consulta Plantillas de Model Armor.

Model Armor incorpora capacidades de filtrado directamente en las rutas de comunicación regidas por Agent Gateway. Cuando pasas el contenido a través de Model Armor, la puerta de enlace aplica tus plantillas de seguridad del contenido. En tu plantilla, puedes configurar Model Armor para que oculte o bloquee el contenido que incumpla tus plantillas.

Tráfico de entrada y salida

A través de Agent Gateway, Model Armor puede ayudar a proteger los siguientes flujos de tráfico.

De cliente a agente (entrada del agente)

Defines plantillas que Model Armor usa para evaluar tanto las solicitudes como las respuestas dentro del tráfico de cliente a agente. Puedes aplicar una sola plantilla a ambas direcciones o configurar plantillas diferentes para cada una.

Model Armor sigue las plantillas cuando filtra lo siguiente:

  • Solicitudes entrantes del cliente (usuarios finales o aplicaciones que llaman) a tu agente de IA
  • Respuestas salientes del agente de IA al cliente

Cuando un cliente envía una instrucción al agente, Agent Gateway intercepta el tráfico y envía la carga útil a Model Armor para su limpieza. Si Model Armor emite un veredicto de ALLOW, Agent Gateway envía la instrucción al agente de IA. Si Model Armor emite un veredicto de BLOCK, el cliente recibe un error y el flujo finaliza antes de llegar al agente de IA.

Después de que el agente de IA procesa la solicitud y genera una respuesta, Agent Gateway intercepta el flujo saliente antes de que llegue al cliente. Model Armor evalúa la respuesta y emite un veredicto. Según el veredicto, Agent Gateway permite o bloquea por completo la respuesta.

Del agente a cualquier lugar (salida del agente)

Defines plantillas que Model Armor usa para evaluar las solicitudes y las respuestas en el tráfico de Agent-to-Anywhere. Puedes aplicar una sola plantilla a ambas direcciones o configurar plantillas diferentes para cada una.

Model Armor sigue las plantillas cuando examina las comunicaciones entre tu agente de IA y los sistemas externos, incluidos los siguientes:

  • Modelos de lenguaje grandes (LLM) externos
  • Agentes de IA externos
  • Servidores del Protocolo de contexto del modelo (MCP)

Cuando un agente de IA se comunica con un sistema externo, Agent Gateway intercepta el tráfico de salida y llama a Model Armor. Model Armor evalúa la carga útil según las plantillas de salida que establezcas.

Si los datos salientes incumplen tus políticas de seguridad, Model Armor emite un veredicto de BLOCK. Luego, Agent Gateway finaliza la conexión para evitar que los datos sensibles o dañinos lleguen al LLM, a la herramienta o al agente externo de IA.

Antes de comenzar

Habilita la API de Model Armor si aún no está habilitada.

Roles necesarios para habilitar las APIs

Para habilitar APIs, necesitas el permiso serviceusage.services.enable. Si creaste el proyecto, es probable que ya tengas este permiso a través del rol de propietario (roles/owner). De lo contrario, puedes obtener este permiso a través del rol de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin). Obtén más información para otorgar roles.

Habilitar la API

Roles obligatorios

Para obtener los permisos que necesitas para crear plantillas de Model Armor, pídele a tu administrador que te otorgue el rol de IAM de Administrador de Model Armor (roles/modelarmor.admin) en el proyecto. 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.

Para conocer los roles necesarios para trabajar con Agent Gateway, consulta Roles necesarios en la documentación de Agent Gateway.

Para obtener información sobre las cargas útiles admitidas y no admitidas que pasan por la puerta de enlace, consulta Cargas útiles admitidas y no admitidas en este documento.

Configura Model Armor en una puerta de enlace

Para configurar Model Armor en una puerta de enlace, sigue estos pasos:

  1. Habilita la API de Model Armor en el proyecto en el que deseas crear las plantillas de Model Armor.

  2. Crea una o más plantillas de Model Armor en la misma región en la que planeas agregar la puerta de enlace. Puedes usar la misma plantilla para el tráfico de entrada y de salida.

    Toma nota de los nombres de las plantillas. Para copiar el nombre de una plantilla en la consola deGoogle Cloud , consulta los detalles de la plantilla y haz clic en Copiar al portapapeles junto al nombre de la plantilla.

  3. Configura Agent Gateway en la misma región en la que se almacenan las plantillas de Model Armor. Para la puerta de enlace de cliente a agente (entrada), especifica las plantillas de Model Armor que creaste para el tráfico de entrada. Para la puerta de enlace de Agent-to-Anywhere (salida), especifica las plantillas de Model Armor que creaste para el tráfico de salida. Puedes usar la misma plantilla para ambos flujos de tráfico.

  4. Otorga los roles de IAM necesarios a los agentes de servicio correspondientes:

    • De cliente a agente (entrada): Otorga al agente de servicio del agente de servicio de AI Platform Reasoning Engine los siguientes roles:

      • El rol de usuario de Model Armor Callout (roles/modelarmor.calloutUser) en el proyecto que contiene el agente de IA.

      • El rol Usuario de Model Armor (roles/modelarmor.user) en el proyecto que contiene la plantilla de Model Armor

      gcloud projects add-iam-policy-binding AGENT_RUNTIME_PROJECT_ID \
    --member=serviceAccount:service-AGENT_RUNTIME_PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com \
    --role=roles/modelarmor.calloutUser
gcloud projects add-iam-policy-binding MODEL_ARMOR_PROJECT_ID \
    --member=serviceAccount:service-AGENT_RUNTIME_PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com \
    --role=roles/modelarmor.user

      Reemplaza lo siguiente:

      • AGENT_RUNTIME_PROJECT_ID: Es el ID del proyecto en el que creaste el agente.
      • AGENT_RUNTIME_PROJECT_NUMBER: Es el número del proyecto en el que creaste el agente.
      • MODEL_ARMOR_PROJECT_ID: Es el ID del proyecto que contiene la plantilla de Model Armor.

    • Agent-to-Anywhere (salida): Otorga al agente de servicio de Service Extensions los siguientes roles:

      • Los roles de usuario de Model Armor Callout (roles/modelarmor.calloutUser) y de consumidor de Service Usage (roles/serviceusage.serviceUsageConsumer) en el proyecto que contiene la puerta de enlace
      • El rol Usuario de Model Armor (roles/modelarmor.user) en el proyecto que contiene la plantilla de Model Armor
      gcloud projects add-iam-policy-binding GATEWAY_PROJECT_ID \
    --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
    --role=roles/modelarmor.calloutUser
gcloud projects add-iam-policy-binding GATEWAY_PROJECT_ID \
    --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
    --role=roles/serviceusage.serviceUsageConsumer
gcloud projects add-iam-policy-binding MODEL_ARMOR_PROJECT_ID \
    --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
    --role=roles/modelarmor.user

      Reemplaza lo siguiente:

      • GATEWAY_PROJECT_ID: Es el ID del proyecto en el que creaste la puerta de enlace.
      • GATEWAY_PROJECT_NUMBER: Es el número del proyecto en el que creaste la puerta de enlace.
      • MODEL_ARMOR_PROJECT_ID: Es el ID del proyecto que contiene la plantilla de Model Armor.

      Para obtener instrucciones, consulta Delega la autorización a Model Armor.

    Para obtener información general sobre cómo otorgar un rol, consulta Otorga un solo rol de IAM.

Opcional: Verificación de validación de la plantilla previa a la implementación

Antes de implementar tus plantillas en una puerta de enlace, puedes ejecutar una verificación previa a la implementación para verificar que la configuración de la plantilla aplique tus políticas de seguridad correctamente.

Puedes validar tu plantilla consultando el método sanitizeUserPrompt directamente con un conjunto de instrucciones de prueba. Para obtener más información sobre cómo ejecutar esta verificación previa a la implementación y ver una lista de instrucciones de prueba verificadas, consulta Valida la configuración de tu plantilla.

Oculta datos sensibles de solicitudes y respuestas

Puedes indicarle a Model Armor que oculte datos sensibles, como números de documentos de identidad nacionales y números de teléfono, de las cargas útiles. Para usar esta función, sigue estos pasos:

Si usas el tipo de aplicación de INSPECT_AND_BLOCK, ocurre una de las siguientes situaciones:

  • Si una carga útil solo incumple el detector de Sensitive Data Protection, Model Armor la oculta según tu configuración avanzada de Sensitive Data Protection y la plantilla de desidentificación.

  • Si una carga útil incumple varios detectores, Model Armor no realiza la ocultación, sino que bloquea toda la carga útil.

Si usas el tipo de aplicación de INSPECT_ONLY en lugar de INSPECT_AND_BLOCK, Model Armor no redactará la carga útil.

Independientemente del tipo de aplicación de la política (INSPECT_ONLY o INSPECT_AND_BLOCK), los registros de Model Armor se ocultan según la configuración avanzada de Sensitive Data Protection y la plantilla de desidentificación.

Para obtener una lista completa de los detectores de Model Armor (también llamados filtros), consulta Filtros de Model Armor.

Cargas útiles compatibles y no compatibles

En esta sección, se enumeran los tipos de cargas útiles que Model Armor higieniza.

Tráfico de entrada de cliente a agente

Para el tráfico de cliente a agente (entrada) que usa el protocolo del ADK, Model Armor solo sanitiza las solicitudes y respuestas de reasoningEngines.streamQuery para los agentes que se crearon con el Kit de desarrollo de agentes (ADK) y se ejecutan en Vertex AI Agent Engine.

Todas las demás cargas útiles de ReasoningEngine y respuestas de error de ReasoningEngine no se envían a Model Armor. Las cargas útiles que no son del ADK (como las cargas útiles de Langchain) tampoco se envían a Model Armor.

Tráfico de salida (del agente a cualquier lugar)

Para el tráfico de Agent-to-Anywhere (salida), se admiten las siguientes cargas útiles.

Cargas útiles de A2A

Model Armor solo sanitiza las siguientes cargas útiles del protocolo A2A v1:

Model Armor permite las siguientes cargas útiles de A2A sin saneamiento:

Cargas útiles de MCP

Model Armor solo sanitiza las siguientes cargas útiles de MCP:

Model Armor permite las siguientes cargas útiles sin sanitización:

  • tools/list
  • resources/*
  • notifications/*
  • HTTP/SSE transmitible para MCP
  • Errores del protocolo de MCP (por ejemplo, todos los errores que no sean de ejecución de herramientas)

Cargas útiles de LLM externas

Model Armor solo sanitiza las siguientes cargas útiles del protocolo de la API de OpenAI (salida), que incluye los modelos GPT en openai.com, así como cualquier otro modelo a través de servidores de LLM compatibles con la API de OpenAI (como vLLM). Las cargas útiles que no se indican aquí se permiten sin saneamiento.

Revisión de documentos

En esta integración, no se admite la limpieza de instrucciones y respuestas que contienen documentos o cargas de archivos (como PDFs). Para analizar documentos, llama directamente a la API de REST de Model Armor. Para obtener más información, consulta Document screening en la documentación de Model Armor.

Cuotas y límites del sistema

La cuota se consume en el proyecto en el que residen las plantillas de Model Armor. Si la puerta de enlace está en un proyecto diferente, la cuota de ExternalProcessor también se consume en el proyecto de la puerta de enlace.

Para obtener más información sobre las cuotas que se aplican cuando usas Model Armor con otros servicios, consulta Administra cuotas.

Para obtener información general sobre las cuotas y los límites del sistema de Model Armor, incluidos los límites de tamaño de entrada y de tokens, consulta Cuotas y límites del sistema en la documentación de Model Armor.

¿Qué sigue?