Integra Model Armor con Agent Gateway

Gemini Enterprise Agent Platform es una plataforma para crear y administrar agentes de IA de nivel empresarial. La puerta de enlace de agentes funciona como un plano de control que administra, protege y controla cómo los agentes de IA se conectan e interactúan dentro del entorno de Google Cloud y con agentes externos, aplicaciones de IA y LLM. La integración de Model Armor y Agent Gateway incorpora las capacidades de detección de Model Armor directamente en las rutas de comunicación que administra Gemini Enterprise Agent Platform. Cuando el contenido pasa por Agent Gateway, se invoca Model Armor para aplicar tus plantillas de seguridad predefinidas. Puedes configurar tu plantilla para bloquear y redactar el contenido que incumpla las políticas, o bien para solo inspeccionar el contenido y registrar 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íticas en el contenido que pasa por Agent Gateway, se puede configurar para que registre estos eventos. Puedes ver estos resultados en la página Model Armor de la consola de Google Cloud (Ir a Model Armor). Estos resultados también se muestran en Security Command Center. Para obtener más información, consulta Revisa los resultados en la consola deGoogle Cloud .

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

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 en varios proyectos: Cuando se usa una plantilla de Model Armor en un proyecto para sanear solicitudes de un servicio, como Agent Gateway, en otro proyecto, 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 de MCP, los 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.

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.

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 (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)

Defines plantillas que Model Armor usa para evaluar lo siguiente:

  • Son las solicitudes entrantes del cliente (usuarios finales o aplicaciones que realizan llamadas) a tu agente de IA.
  • Son las respuestas que el agente de IA envía al cliente.

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

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 Agent Runtime.

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.

Flujo de tráfico de cliente a agente

  1. Un cliente envía una instrucción al agente. La puerta de enlace del agente 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 bloquea según el veredicto.

Protección de salida del agente a cualquier lugar

Defines plantillas que Model Armor usa para evaluar lo siguiente:

  • Son las solicitudes salientes de tu agente de IA a sistemas externos.
  • Son las 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 para la función 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. La puerta de enlace del agente 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.

Cómo hacer un seguimiento de las solicitudes de transmisión y depurarlas

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.

Cómo usar 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 seguridad que Model Armor aplica dentro de la ruta de solicitud del recurso de Agent Gateway.

Cada registro de 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 registro de seguimiento. Los registros que se generan 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 propio con el encabezado HTTP traceparent en tus solicitudes.

    En el 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: 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 llamador a través de Agent Gateway hasta Model Armor y cualquier agente de nivel inferior. Esto es fundamental para depurar, comprender las acciones de seguridad y supervisar el rendimiento. Para obtener más información, consulta Cómo ver los intervalos de seguimiento de Model Armor.

Para ver los registros de la operación de saneamiento 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.

Cómo usar 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 saneamiento 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, específicamente para las sesiones de transmisión de entrada. Para obtener más información, consulta Cómo correlacionar registros y eventos relacionados.