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 y cómo interactúan los agentes de IA dentro del Google Cloud entorno y con agentes externos, aplicaciones de IA y LLMs. 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 tu plantilla para bloquear y redactar contenido que incumpla las políticas, o bien para inspeccionar solo el contenido y registrar cualquier incumplimiento que se detecte. 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 registrar estos eventos. Puedes ver estos resultados en la página Model Armor de la Google Cloud consola (Ir a Model Armor). Estos resultados también aparecen en Security Command Center. Para obtener más información, consulta Revisa los resultados en la Google Cloud consola.

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 del modelo.

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 transmisión con el método streamQuery para los 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 solicitudes de un servicio, como Agent Gateway, en un proyecto diferente, la cuota de API para Model Armor debe ser suficiente tanto en el proyecto que aloja la plantilla como en el proyecto que aloja el servicio de 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 Google Cloud región. No se admiten las llamadas interregionales 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 MCP, servicios que siguen el formato OpenAIy A2A a través de Agent Gateway.
  • Compatibilidad con la integración de entrada: La protección de entrada intercalada con Model Armor solo se admite para los agentes creados con ADK.
  • Sin compatibilidad con documentos: La limpieza de instrucciones y respuestas que contienen documentos o cargas de archivos (como archivos PDF) no se admite en esta integración. Para filtrar documentos, llama directamente a la API de REST de Model Armor.
  • Cargas útiles admitidas: Para obtener una lista de las cargas útiles admitidas, 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 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 Google Cloud consola, consulta los detalles de la plantilla y haz clic en Copiar al portapapeles junto a el 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 agente a cualquier lugar (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 motor de razonamiento de AI Platform agente de servicio del agente de servicio 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.

    • Del agente a cualquier lugar (salida): Otorga al agente de servicio de Extensiones de servicio 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.

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 las solicitudes entrantes del cliente al agente y 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 las solicitudes salientes del agente al sistema externo y las respuestas entrantes del sistema externo al agente.

Protección de cliente a agente (entrada)

Defines las plantillas que usa Model Armor para evaluar lo siguiente:

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

Puedes aplicar una sola plantilla a ambas direcciones o configurar diferentes plantillas 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 filtra la respuesta y Agent Gateway la permite o la bloquea según el veredicto.

Protección del agente a cualquier lugar (salida)

Defines las plantillas que usa Model Armor 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, incluidos los siguientes:

  • LLMs 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, la conexión finaliza.
  3. Si se permite, la solicitud se envía al sistema externo.
  4. El sistema externo envía una respuesta. Agent Gateway intercepta esta respuesta entrante.
  5. Model Armor filtra 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.

Haz 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 a través de varios servicios en un sistema distribuido. Esto incluye las aplicaciones 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 se habilita Google Cloud Observability, Agent Gateway genera automáticamente un ID de seguimiento y lo propaga a través del sistema.

  • Proporcionado por el usuario: Puedes anular el ID de seguimiento generado por el sistema si proporcionas el tuyo con el encabezado HTTP traceparent en tus solicitudes.

    En la siguiente muestra de código, se muestra 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: la región en la que se encuentra el motor de razonamiento
    • PROJECT_ID: el ID de tu Google Cloud proyecto
    • REASONING_ENGINE_ID: 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 llamador a través de Agent Gateway a Model Armor y cualquier agente descendente. Esto es esencial para la depuración, la comprensión de las acciones de seguridad y la supervisión del rendimiento. Para obtener más información, consulta Visualiza los intervalos de seguimiento de Model Armor spans.

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 dentro de los registros de Model Armor, específicamente 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 limpia Model Armor.

Tráfico de cliente a agente (entrada)

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

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

Tráfico del agente a cualquier lugar (salida)

Para el tráfico del agente a cualquier lugar (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 MCP (por ejemplo, todos los errores que no sean errores 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 GPT en openai.com así como cualquier otro modelo a través de servidores LLM compatibles con la API de OpenAI (como vLLM). Las cargas útiles que no se enumeran aquí se permiten sin limpieza.