Integra Model Armor con Agent Gateway

Gemini Enterprise Agent Platform es una plataforma para crear y administrar agentes de IA de nivel empresarial. Agent Gateway funciona como un plano de control que administra, protege y rige cómo se conectan e interactúan los agentes de IA dentro del entorno de Google Cloud y con agentes, aplicaciones de IA y LLM externos. La integración de Model Armor y Agent Gateway incorpora las capacidades de filtrado de Model Armor directamente en las rutas de comunicación que administra Gemini Enterprise Agent Platform. Cuando el contenido pasa por Agent Gateway, invoca a Model Armor para aplicar tus plantillas de seguridad predefinidas. Puedes configurar la plantilla para que bloquee y oculte el contenido que incumple las políticas, o para que solo inspeccione el contenido y registre los incumplimientos que se detecten. Esto mitiga riesgos como la inyección de instrucciones, el jailbreaking, la exposición a contenido dañino y la filtración de datos sensibles.

Cuando Model Armor detecta incumplimientos de política en el contenido que pasa por Agent Gateway, se puede configurar para que registre estos eventos. Puedes ver estos hallazgos en la página Model Armor de la consola de Google Cloud (Ir a Model Armor). Estos hallazgos también aparecen en Security Command Center. Para obtener más información, consulta Revisa los hallazgos en la consola deGoogle Cloud .

Cuando se usa el modo de transmisión en tiempo real, Model Armor admite tokens ilimitados en la transmisión, lo que lo hace adecuado para interacciones de larga duración y respuestas de modelos.

Limitaciones

Ten en cuenta las siguientes limitaciones cuando integres Model Armor con Agent Gateway:

  • Compatibilidad con la transmisión para agentes: Model Armor solo admite la limpieza de transmisiones con el método streamQuery para agentes creados con el Kit de desarrollo de agentes.
  • Uso de plantillas entre proyectos: Cuando se usa una plantilla de Model Armor en un proyecto para limpiar las solicitudes de un servicio, como Agent Gateway, en un proyecto diferente, la cuota de la API para Model Armor debe ser suficiente tanto en el proyecto que aloja la plantilla como en el que aloja el servicio que realiza la llamada. Para obtener más información, consulta Administra la cuota.
  • Alineación regional: Model Armor y los servicios con los que se integra deben implementarse en la misma región de Google Cloud . No se admiten las llamadas entre regiones a Model Armor.
  • Compatibilidad con la integración de salida: La protección intercalada de Model Armor en el tráfico de salida se limita a las integraciones con servidores de MCP, servicios que siguen el formato de OpenAI y A2A a través de Agent Gateway.
  • Compatibilidad con la integración de Ingress: La protección de entrada intercalada con Model Armor solo se admite para los agentes creados con ADK.
  • No se admiten documentos: En esta integración, no se admite la limpieza de instrucciones y respuestas que contengan documentos o cargas de archivos (como archivos PDF). Para filtrar documentos, llama directamente a la API de REST de Model Armor.
  • Cargas útiles compatibles: Para obtener una lista de las cargas útiles compatibles, 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. \
          --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. \
          --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. \
          --role=roles/modelarmor.calloutUser
      gcloud projects add-iam-policy-binding GATEWAY_PROJECT_ID \
          --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep. \
          --role=roles/serviceusage.serviceUsageConsumer
      gcloud projects add-iam-policy-binding MODEL_ARMOR_PROJECT_ID \
          --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep. \
          --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.

Tráfico de entrada y salida

En el contexto de la integración de Agent Gateway y Model Armor, los términos entrada y salida se usan desde la perspectiva de las interacciones del agente de IA:

  • Tráfico de entrada (de cliente a agente): Se refiere al flujo de comunicación entre un cliente y el agente. Model Armor puede proteger tanto las solicitudes entrantes del cliente al agente como las respuestas salientes del agente al cliente.
  • Tráfico de salida (del agente a cualquier lugar): Se refiere al flujo de comunicación entre el agente y un sistema externo. Model Armor puede proteger tanto las solicitudes salientes del agente al sistema externo como las respuestas entrantes del sistema externo al agente.

Protección de cliente a agente (entrada)

Debes definir las plantillas que Model Armor usa para evaluar lo siguiente:

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

Puedes aplicar una sola plantilla a ambas direcciones o configurar plantillas diferentes para cada una.

Flujo de tráfico de cliente a agente

  1. Un cliente envía una instrucción al agente. Agent Gateway intercepta la solicitud y envía la carga útil a Model Armor.
  2. Model Armor filtra la solicitud. Si se bloquea, el cliente recibe un error.
  3. Si se permite, la solicitud llega al agente de IA.
  4. El agente de IA genera una respuesta. Agent Gateway intercepta esta respuesta antes de que llegue al cliente.
  5. Model Armor analiza la respuesta y Agent Gateway la permite o la bloquea según el veredicto.

Protección del agente a cualquier lugar (salida)

Debes definir las plantillas que Model Armor usa para evaluar lo siguiente:

  • Solicitudes salientes de tu agente de IA a sistemas externos.
  • Respuestas entrantes de sistemas externos a tu agente de IA.

Esta protección se aplica a las comunicaciones con sistemas que incluyen lo siguiente:

  • LLM externos y agentes de IA de terceros
  • Servidores del Protocolo de contexto del modelo (MCP)
  • Otros agentes de IA

Flujo de tráfico del agente a cualquier lugar

  1. El agente de IA inicia una solicitud a un sistema externo. Agent Gateway intercepta el tráfico saliente.
  2. Model Armor filtra la carga útil saliente. Si se bloquea, se finaliza la conexión.
  3. Si se permite, la solicitud se envía al sistema externo.
  4. El sistema externo devuelve una respuesta. Agent Gateway intercepta esta respuesta entrante.
  5. Model Armor analiza la carga útil de la respuesta y Agent Gateway permite que llegue al agente o la bloquea.

Para obtener más información, consulta Configura Model Armor en una puerta de enlace.

Realiza un seguimiento de las solicitudes de transmisión y depúralas

Para facilitar el seguimiento y la depuración de las solicitudes de transmisión, Model Armor usa un ID de correlación y un ID de seguimiento.

Usa un ID de seguimiento

Un ID de seguimiento conecta todos los eventos de una sola solicitud a medida que viaja por varios servicios en un sistema distribuido. Esto incluye las aplicaciones de medidas de seguridad que Model Armor aplica dentro de la ruta de solicitud del recurso de Agent Gateway.

Cada seguimiento contiene uno o más intervalos, en los que cada ID de intervalo representa una operación o unidad de trabajo específica dentro del seguimiento. Los registros generados durante la ejecución de una solicitud se asocian con el ID de intervalo específico de la operación que realiza el trabajo.

Un ID de seguimiento se controla de dos maneras:

  • Automático: Cuando Google Cloud Observability está habilitado, Agent Gateway genera automáticamente un ID de seguimiento y lo propaga por el sistema.
  • Proporcionado por el usuario: Puedes anular el ID de seguimiento generado por el sistema proporcionando el tuyo con el encabezado HTTP traceparent en tus solicitudes.

    En la siguiente muestra de código, se indica cómo pasar un ID de seguimiento personalizado en una solicitud al método streamQuery:

    curl -X POST \
      -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      -H "Content-Type: application/json" \
      -H "traceparent: 00-98adffecc8dd095968a06c44216190f6-5b565a8342378cd7-01" \
      "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/REASONING_ENGINE_ID:streamQuery?alt=sse"
    

    Reemplaza lo siguiente:

    • LOCATION: Es la región en la que se encuentra el motor de razonamiento.
    • PROJECT_ID: Es el ID de tu proyecto de Google Cloud .
    • REASONING_ENGINE_ID: Es el ID de tu motor de razonamiento.

Usar un ID de seguimiento es el método recomendado para correlacionar registros y seguimientos de extremo a extremo desde el emisor a través de Agent Gateway hasta Model Armor y cualquier agente descendente. Esto es esencial para depurar, comprender las acciones de seguridad y supervisar el rendimiento. Para obtener más información, consulta Visualiza los intervalos de seguimiento de Model Armor.

Para ver los registros de operaciones de limpieza de un ID de seguimiento específico, usa la siguiente consulta en el Explorador de registros:

jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry"
trace:TRACE_ID

Reemplaza TRACE_ID por el ID de seguimiento de tu solicitud.

Usa un ID de correlación

Un ID de correlación vincula todas las entradas de registro en Cloud Logging que pertenecen a una sola sesión de limpieza de transmisión, desde la solicitud inicial hasta la respuesta final. Es un identificador interno que se usa principalmente en los registros de Model Armor, en especial para las sesiones de transmisión de entrada. Para obtener más información, consulta Correlaciona registros y eventos relacionados.

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) con 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 se ejecutan en Agent Runtime.

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.