Puntuación de riesgo

Comprende cómo ShieldAgent calcula las puntuaciones de riesgo por agente y configura los umbrales de aplicación.

Cómo funcionan las puntuaciones de riesgo

ShieldAgent calcula una puntuación de riesgo continua (0–100) para cada agente a partir de una ventana de 7 días de eventos con decaimiento ponderado en el tiempo. Un proceso en segundo plano recalcula la puntuación de cada agente a un intervalo fijo (cada 5 minutos por defecto); también puedes forzar un recálculo inmediato a través de la API.

Composición de la puntuación

Puntuación de inyecciónConfianza del clasificador ML en que los inputs contienen inyección de prompt

Puntuación de deriva de herramientasDesviación de la línea base de uso de herramientas establecida del agente

Puntuación de agencia excesivaFrecuencia y alcance de llamadas de herramientas de alto impacto por sesión

Puntuación de anomalíaDesviación estadística del comportamiento de agentes pares

Tasa de violación de políticasProporción de solicitudes que activaron una regla de denegación

Niveles de puntuación

La aplicación de riesgo es un interruptor por tenant que está desactivado por defecto. Con él desactivado, la etapa de aplicación de riesgo del pipeline deja pasar toda solicitud sin cambios — la autenticación, la limitación de tasa, el acceso a herramientas, las políticas y la seguridad/DLP siguen ejecutándose y pueden denegar una solicitud por sí solas. Las acciones siguientes aplican solo cuando un tenant activa la aplicación de riesgo.

Rango de puntuación	Nivel	Acción una vez activado
0 – 59	Normal	Sin acción.
60 – 79	Elevado	El multiplicador nominal del nivel es 0.50 por defecto (configurable). Con la aplicación de riesgo activada para el tenant, un nivel efectivo Elevado tras la anulación, sin período de gracia activo y con un limitador configurado, la etapa anterior de limitación aplica el multiplicador efectivo al límite del tenant en esta comprobación. No crea una cuota por agente ni modifica el límite global. En modo sombra preexistente, se observa y registra un exceso del límite sin bloquear.
80 – 89	Alto	El multiplicador nominal del nivel es 0.25 por defecto (configurable). Las mismas condiciones de nivel efectivo, gracia y limitador se aplican al límite del tenant. Alto activa el modo sombra más tarde en el pipeline para el resto de esta solicitud; eso no convierte en observación la comprobación anterior del limitador. Solo el modo sombra preexistente permite observar un exceso sin bloquear.
90 – 100	Crítico	Bloqueado de inmediato — sin período de gracia — excepto métodos en la lista de permitidos (initialize y ping por defecto) y en modo sombra, donde el bloqueo solo se registra. No es un bloqueo persistente: se reevalúa a partir de la puntuación actual del agente en cada solicitud, así que se libera por sí solo en cuanto el siguiente recálculo (cada 5 minutos por defecto) baje la puntuación — un administrador también puede liberarlo antes, sin esperar.

Consultar puntuaciones de riesgo

Los ejemplos de SDK se han retirado. Para integrar ShieldAgent, usa la referencia OpenAPI.

risk.listAll() response

[
  {
    "agentId": "agt_01HXYZ...",
    "agentName": "support-bot",
    "riskTier": "elevated",
    "score": 67,
    "calculatedAt": "2026-04-16T14:23:00Z"
  }
]

risk.getForAgent() response

{
  "agentId": "agt_01HXYZ...",
  "score": 67,
  "calculatedAt": "2026-04-16T14:23:00Z",
  "trend": "rising",
  "deltaVs24h": 14,
  "windows": [
    { "label": "1h", "avgScore": 71, "minScore": 65, "maxScore": 78, "sampleCount": 12 },
    { "label": "24h", "avgScore": 53, "minScore": 40, "maxScore": 67, "sampleCount": 288 }
  ]
}

Configurar umbrales de aplicación

Los umbrales, los multiplicadores de tasa, el período de gracia y la lista de permitidos del nivel Crítico viven en la configuración de riesgo de cada tenant — elevatedThreshold (por defecto 60), highThreshold (por defecto 80), criticalThreshold (por defecto 90), elevatedRateMult (por defecto 0.50), highRateMult (por defecto 0.25), gracePeriodSeconds (por defecto 300), criticalAllowedMethods (por defecto ["initialize", "ping"]). Se leen y escriben mediante PUT /tenants/:tenantId/risk-config en la API de gestión. Usa el endpoint REST documentado.

Líneas base de comportamiento

ShieldAgent aprende el patrón normal de uso de herramientas de cada agente y compara las llamadas en vivo contra esa línea base. Las desviaciones de la línea base aumentan la puntuación de deriva de herramientas.

Los ejemplos de SDK se han retirado. Para integrar ShieldAgent, usa la referencia OpenAPI.

anomalies.getBaseline() response

{
  "agentId": "agt_01HXYZ...",
  "baseline": {
    "tools": [
      { "toolName": "read_file", "callCount": 142, "avgCallsPerHour": 5.9, "stddevCallsPerHour": 1.2, "commonPatterns": ["read_file:/docs/*"] },
      { "toolName": "search_docs", "callCount": 58, "avgCallsPerHour": 2.4, "stddevCallsPerHour": 0.6, "commonPatterns": [] }
    ],
    "totalCalls": 200,
    "windowDays": 14,
    "updatedAt": "2026-04-16T09:00:00Z"
  }
}

No existe una API para restablecer una línea base a demanda. windowDays en la respuesta indica cuántos días del propio historial de ese agente se usaron para calcular la línea base — no existe un ajuste de calentamiento a nivel de tenant.

Alertas de riesgo

Configura reglas de alerta para activarse en umbrales de puntuación de riesgo. La API acepta canales webhook y de email, pero el evaluador de alertas en producción nunca recibe un remitente de email funcional — todos los puntos de instanciación lo construyen sin ninguno, así que las entregas por email se registran como fallidas; webhook es el único canal que realmente se envía hoy.

Los ejemplos de SDK se han retirado. Para integrar ShieldAgent, usa la referencia OpenAPI.