Visión general de la arquitectura
ShieldAgent aplica seguridad en el límite entre los agentes de IA y las herramientas que utilizan. La ubicación exacta de ese límite en tu stack es flexible — despliega el proxy inline entre el agente y el upstream, o llama a la API de veredicto desde tu propio servidor antes de ejecutar solicitudes.
Dónde posicionar ShieldAgent
ShieldAgent puede insertarse en varios puntos de la cadena de llamadas de agente a herramienta. La posición correcta depende de lo que controles en tu stack y el nivel de visibilidad que necesitas. Todas las posiciones usan el mismo pipeline de seguridad multi-etapa; solo el método de integración difiere. Las posiciones 2 y 3 usan la API REST de veredicto — tu código envía los payloads de solicitud a ShieldAgent para escanearlos y aplica el veredicto devuelto.
Posición 1 — Proxy entre el agente y el MCP
El agente apunta su cliente MCP al proxy de ShieldAgent en lugar del servidor upstream directamente. Sin cambios de código en el agente ni en el servidor MCP. El proxy intercepta cada llamada a herramienta, ejecuta el pipeline de seguridad completo y reenvía las solicitudes aprobadas. Este es el modelo de despliegue principal y el que te da visibilidad completa de todas las llamadas a herramientas.
Ideal cuando: no posees el agente ni el servidor MCP, o quieres un despliegue sin intervención. La segmentación de red debe garantizar que los agentes no puedan eludir el proxy.
Posición 2 — Verdict API en tu propia API
Si tus agentes llaman a una API REST que tú posees y operas, llama al endpoint REST de análisis de ShieldAgent antes de ejecutar cada solicitud. ShieldAgent ejecuta el pipeline de seguridad completo multi-etapa y devuelve un veredicto (allow / block / human_review). Tu código aplica el veredicto — ejecuta si está permitido, rechaza si está bloqueado. El pipeline de seguridad se ejecuta en el proxy de ShieldAgent, no en proceso.
Ideal cuando: posees la capa de API que llaman tus agentes y quieres añadir escaneo de seguridad sin cambiar el flujo de tráfico. Tu código sigue en control — ShieldAgent escanea y devuelve un veredicto, tú lo aplicas.
Los ejemplos de SDK se han retirado. Para integrar ShieldAgent, usa la referencia OpenAPI.
Posición 3 — Verdict API en tu propio servidor MCP
Si operas un servidor MCP al que se conectan los agentes, llama a POST /tenants/:tenantId/scan antes de cada manejador de herramienta. Cuando un agente solicita una herramienta, tu servidor envía el nombre de la herramienta y los argumentos a ShieldAgent para escanearlos. ShieldAgent devuelve un veredicto — tu código ejecuta la herramienta solo si está permitido. Esto te da visibilidad profunda y aplicación de políticas en el punto donde se definen las herramientas, manteniendo ShieldAgent centralizado.
Ideal cuando: construyes y mantienes el servidor MCP y quieres aplicación de seguridad en la capa de definición de herramientas. Tu servidor sigue en control — ShieldAgent escanea, tú aplicas. Contexto más rico para la evaluación de políticas que el posicionamiento proxy externo.
Los ejemplos de SDK se han retirado. Para integrar ShieldAgent, usa la referencia OpenAPI.
| Posición | Qué debes poseer | Cambios en el código del agente | Ve llamadas salientes a herramientas | Aplicación |
|---|---|---|---|---|
| 1 — Proxy inline | Nada | Apuntar a la URL del proxy | Sí | Infraestructura |
| 2 — Verdict API (REST) | Tu servidor API | Llamar al endpoint REST de análisis | Sí | Código del cliente |
| 3 — Verdict API (MCP) | Tu servidor MCP | Llamar al endpoint REST de análisis | Sí | Código del cliente |
Las posiciones 1-3 cubren los principales patrones de integración para ShieldAgent SaaS.
Passthrough vs. Verdict API
Existen dos patrones de integración REST para clientes que poseen su propio servidor. Elige según si ShieldAgent necesita reenviar el tráfico a un upstream separado.
| Escenario | Patrón | Cómo funciona |
|---|---|---|
| Tu servidor es un gateway hacia un upstream diferente | Reenvío proxy REST | Tu cliente REST envía la solicitud al proxy de ShieldAgent. El proxy escanea, luego reenvía al upstream real y devuelve la respuesta. |
| Tu servidor ES el proveedor de herramientas (sin upstream separado) | API de veredicto (REST) | Tu cliente REST envía el payload a ShieldAgent. ShieldAgent devuelve un veredicto (allow/block/human_review). Tu servidor ejecuta o rechaza localmente. |
Modelo de aplicación
Todas las posiciones de despliegue ejecutan el mismo pipeline de seguridad multi-etapa — detección, evaluación de políticas, puntuación de riesgo y auditoría son gestionadas por ShieldAgent. Lo que difiere es quién aplica el veredicto. La Posición 1 bloquea llamadas enrutadas antes de reenviarlas en modo de aplicación; el modo sombra registra sin bloquear. Las Posiciones 2 y 3 usan la Verdict API: ShieldAgent detecta amenazas y devuelve un veredicto; el código de tu servidor lo aplica.
Comparación de aplicación
| Posición | Aplicado por | Mecanismo de bloqueo | Garantía |
|---|---|---|---|
| 1 — Proxy inline | ShieldAgent | El proxy rechaza solicitudes enrutadas en modo de aplicación | Solo para llamadas enrutadas en modo de aplicación; el modo sombra registra sin bloquear |
| 2 — Verdict API (REST) | Tu código de servidor | Tu manejador lanza o devuelve error | A nivel de código — depende de la implementación |
| 3 — Verdict API (MCP) | Tu código de servidor | Tu manejador de herramienta rechaza | A nivel de código — depende de la implementación |
Matriz de responsabilidades
| Responsabilidad | Posición 1 (Proxy Inline) | Posiciones 2 y 3 (Verdict API) |
|---|---|---|
| Detección de amenazas | ShieldAgent | ShieldAgent |
| Evaluación de políticas | ShieldAgent | ShieldAgent |
| Puntuación de riesgo | ShieldAgent | ShieldAgent |
| Registro de auditoría | ShieldAgent | ShieldAgent |
| Documentación de cumplimiento (Anexo IV) | ShieldAgent | ShieldAgent |
| Bloqueo de amenazas | ShieldAgent — para llamadas enrutadas en modo de aplicación | Código del cliente — confirmaciones autodeclaradas |
| Evidencia de bloqueo | Decisión del proxy para llamadas enrutadas en modo de aplicación | Confirmaciones opcionales del cliente; no prueban el bloqueo de forma independiente |
Impacto en los marcos de cumplimiento
| Marco | Posición 1 (Proxy Inline) | Posiciones 2 y 3 (Verdict API) |
|---|---|---|
| SOC 2 CC6.1 (Controles de acceso lógico) | ShieldAgent evidencia la parte de tráfico de agentes de este control; el alcance es un subconjunto de CC6.1. | ShieldAgent proporciona detección + auditoría. Tu código de aplicación forma parte del control combinado evaluado por los auditores. |
| ISO 42001 A.6.2.6 (Operación y supervisión del sistema de IA) | ShieldAgent aporta la evidencia de operación y supervisión en tiempo de ejecución, y reporta el control como cubierto o parcial a partir de ella. Que tu sistema de gestión de IA sea conforme lo determina tu auditoría. | Idéntico — la evidencia de supervisión no depende de la topología de aplicación. La cobertura sigue determinándose por la evidencia presente, no por la integración que elijas. |
| Ley de IA de la UE Art. 9 (Gestión de riesgos) | ShieldAgent evalúa amenazas y puede bloquear llamadas enrutadas en modo de aplicación; estas decisiones pueden apoyar los controles de riesgo del proveedor. | ShieldAgent evalúa amenazas; el código del cliente decide si aplica los veredictos. Documenta los controles reales de la integración cuando corresponda. |
| Ley de IA de la UE Art. 14 (Supervisión humana) | Revisión humana a través del panel de ShieldAgent. | Revisión humana a través del panel + tu decisión explícita de aplicación tras recibir un veredicto human_review. |
| Ley de IA de la UE Anexo IV (Documentación técnica) | Las decisiones del proxy sobre llamadas enrutadas en modo de aplicación pueden apoyar la documentación técnica. | Describe el mecanismo real de aplicación cuando corresponda; la tasa de confirmaciones de ShieldAgent es telemetría opcional autodeclarada, no un requisito del Anexo IV. |
Pipeline de seguridad
Cada solicitud interceptada viaja por el mismo pipeline de seguridad ordenado independientemente de la posición de despliegue que uses. Las capacidades marcadas como siempre se ejecutan incondicionalmente; el resto se omiten en modo sombra o cuando no están configuradas.
Verifica las credenciales, identifica al inquilino y al agente, y determina si aplica el modo sombra.
Aplica límites de tasa configurables por inquilino y por agente para proteger los servicios upstream de la sobrecarga.
Evalúa tus reglas de política configurables contra cada solicitud — permitir, denegar o escalar a revisión humana. El modo sombra registra sin bloquear.
Detecta inyección de prompts, exfiltración de datos, uso indebido de herramientas y otras amenazas mediante coincidencia de patrones y aprendizaje automático.
Asigna una puntuación de riesgo a cada agente basada en patrones de comportamiento. Bloquea o escala cuando el riesgo supera tus umbrales configurados.
Registra un evento de auditoría a prueba de manipulaciones para cada solicitud y veredicto, incluidas las solicitudes denegadas. Nunca bloquea la ruta de la solicitud.
Las capacidades se ejecutan en secuencia. Cualquier paso puede cortocircuitar el pipeline devolviendo una decisión de deny. El registro de auditoría siempre se ejecuta, incluso para las solicitudes denegadas.
Aislamiento de datos y multi-tenancy
La plataforma SaaS de ShieldAgent aplica un aislamiento lógico estricto entre todos los inquilinos. Toda la infraestructura está completamente gestionada — tú eliges dónde posicionar ShieldAgent en tu stack, no cómo operarlo.
Aislamiento lógico multi-inquilino
Todos los inquilinos comparten un único proxy gestionado. El aislamiento se aplica en cada capa — claims JWT por solicitud, controles de acceso a nivel de fila y límites de tasa por inquilino. Tus datos nunca se mezclan con los de otro inquilino.
| Topología | Aislamiento | Gestionado por | Aplicable a |
|---|---|---|---|
| Compartido (SaaS) | Lógico | ShieldAgent | Todos los planes |
Capacidades de la plataforma
ShieldAgent proporciona una plataforma de seguridad completa para operaciones de agentes de IA. Todas las capacidades están completamente gestionadas — no hay infraestructura que configurar o desplegar.
| Capacidad | Qué hace |
|---|---|
| Security Scanning | Escanea cada llamada de herramienta y solicitud API en busca de amenazas, incluyendo inyección de prompts, exfiltración de datos y uso indebido de herramientas, antes de que lleguen a tus sistemas. |
| Policy Enforcement | Evalúa reglas de política configurables contra cada solicitud. Las políticas pueden permitir, denegar o escalar a revisión humana. El modo sombra te permite observar sin bloquear. |
| Dashboard & Monitoring | Panel de seguridad en tiempo real para monitorear la actividad de agentes, gestionar políticas, explorar registros de auditoría y registrar agentes. |
| Audit Trail | Registro de auditoría a prueba de manipulaciones de cada llamada de herramienta y veredicto. Exporta en cualquier momento a través del panel de control o un webhook configurado. |
| Risk Scoring | Puntuación de riesgo continua por agente con detección de anomalías de comportamiento y umbrales de alerta configurables. |
| Compliance Reporting | Documentación de cumplimiento generada automáticamente para marcos SOC 2, ISO 42001 y Ley de IA de la UE, incluyendo evidencia del Anexo IV. |
Transportes compatibles
El proxy admite transportes MCP tanto de red como basados en procesos. Elige según cómo se comunica tu framework de agentes con los servidores MCP.
| Transporte | Protocolo | Caso de uso |
|---|---|---|
| HTTP/SSE | HTTP streaming | Agentes de red, despliegues con múltiples réplicas |
| stdio | Standard I/O | El agente lanza el proxy como proceso hijo (desarrollo local, apps de escritorio) |
| REST API proxy | HTTP methods | Pass-through para APIs REST no MCP con aplicación de políticas |
Cómo escala ShieldAgent
Escalado automático
ShieldAgent escala de forma transparente según tu volumen de tráfico. La capacidad del proxy, la afinidad de sesiones y el rendimiento de la base de datos se gestionan automáticamente — sin configuración requerida por tu parte.
Fiabilidad de conexiones SSE
Las conexiones Server-Sent Event son de larga duración y se gestionan con enrutamiento de reconexión automático. La afinidad de sesión es gestionada por la plataforma para que tus agentes se reconecten sin pérdida de datos.
Rendimiento de auditoría
El registro de auditoría está diseñado para alto rendimiento. Los eventos se escriben de forma asíncrona y nunca bloquean la ruta de la solicitud. Exporta en cualquier momento a través del panel de control o un webhook configurado.
Incluido en ShieldAgent SaaS
Toda la infraestructura es operada por ShieldAgent. Las siguientes capacidades están incluidas — nada que desplegar ni mantener de tu parte.
Escaneo de seguridad · Aplicación de políticas · Panel y monitoreo · Registro de auditoría · Puntuación de riesgo · Informes de cumplimiento