Configura Model Armor en una puerta de enlace

Model Armor te ayuda a garantizar que tus agentes de IA sigan tus estándares de seguridad y administración sin que tengas que implementar la 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 protecciones de seguridad de contenido de forma coherente en todos los agentes que rige 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 que rige Agent Gateway. Cuando se pasa el contenido por Model Armor, la puerta de enlace aplica tus plantillas de seguridad de contenido. En tu plantilla, puedes configurar Model Armor para ocultar o bloquear el contenido que incumple 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 las solicitudes y 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 las 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 filtra las comunicaciones entre tu agente de IA y los sistemas externos, incluidos los siguientes:

  • Modelos de lenguaje grandes (LLM) externos
  • Agentes de IA de terceros
  • 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 dañinos o sensibles lleguen al LLM, a la herramienta o al agente de IA externo.

Antes de comenzar

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

Roles necesarios para habilitar las APIs

Para habilitar las 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 obtenerlo 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 compatibles y no compatibles que pasan por la puerta de enlace, consulta Cargas útiles compatibles y no compatibles 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 quieres 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.

    Si creas las plantillas de Model Armor en un proyecto diferente del que contiene el agente de IA o Agent Gateway y usas los Controles del servicio de VPC, ambos proyectos deben estar en el mismo perímetro de servicio de los Controles del servicio de VPC.

  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 agente a cualquier destino (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 motor de razonamiento de plataforma de IA 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 de 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.
    • De agente a cualquier lugar (salida): Otorga al agente de servicio de Service Extensions los siguientes roles:

      • Los roles de usuario de Model Armor Callout (roles/modelarmor.calloutUser) y consumidor de Service Usage (roles/serviceusage.serviceUsageConsumer) en el proyecto que contiene la puerta de enlace.
      • El rol de 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 la 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 asegurarte de que la configuración de la plantilla aplique correctamente tus políticas de seguridad.

Para validar tu plantilla, consulta 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 una lista de instrucciones de prueba verificadas, consulta Prueba una plantilla de Model Armor.

Oculta datos sensibles de las solicitudes y respuestas

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

Si usas el tipo de aplicación de política INSPECT_AND_BLOCK, ocurrirá una de las siguientes situaciones:

  • Si una carga útil incumple solo el detector de Sensitive Data Protection, Model Armor oculta la carga útil 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 medidas por incumplimiento INSPECT_ONLY en lugar de INSPECT_AND_BLOCK, Model Armor no oculta la carga útil.

Independientemente del tipo de aplicación de medidas por incumplimiento (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 limpia.

Tráfico de cliente a agente (entrada)

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

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

Tráfico del agente a cualquier lugar (salida)

Para el tráfico de agente a cualquier destino (salida), se admiten las siguientes cargas útiles.

Cargas útiles de A2A

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

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

Cargas útiles de MCP

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

Model Armor permite las siguientes cargas útiles sin limpieza:

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

Cargas útiles de LLM externas

Model Armor solo limpia las siguientes cargas útiles del protocolo de la API de OpenAI (salida), que incluye modelos de 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 limpieza.

Filtrado de documentos

En esta integración, no se admite la limpieza de instrucciones y respuestas que contengan documentos o cargas de archivos (como PDF). Para verificar documentos, llama directamente a la API de REST de Model Armor. Para obtener más información, consulta Análisis de documentos 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.

Las solicitudes de limpieza unarias y las solicitudes de transmisión almacenadas en búfer están sujetas a los límites del sistema de tokens por filtro (65,536 tokens para la inyección de instrucciones y la detección de jailbreak, la IA responsable y los filtros de material de abuso sexual infantil (CSAM), y 130,000 tokens para Sensitive Data Protection) y un límite de tamaño de entrada de 4 MB. Si una instrucción o respuesta, como una carga útil grande de generación aumentada por recuperación (RAG) o un historial de conversación de agente de varios pasos, supera el límite de tokens de un filtro sin una infracción detectada, ese filtro omite la evaluación y devuelve EXECUTION_SKIPPED con Detection skipped as token limit exceeded. en la entrada de registro SanitizeOperation. La solicitud continúa sin activar un bloqueo para ese filtro. Para filtrar cargas útiles grandes sin alcanzar los límites de tokens, usa la limpieza de transmisión en tiempo real.

Por ejemplo, usa streamQuery para los agentes creados con el Kit de desarrollo de agentes, que admite tokens ilimitados. Como alternativa, divide las cargas útiles de RAG grandes y los historiales de agentes para que cada solicitud unaria se mantenga dentro de los límites de tokens.

Para obtener más información sobre las cuotas que se aplican cuando integras 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?