Skip to main content
Sign in →

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 basándose en señales de comportamiento. Las puntuaciones se actualizan en 100 ms tras cada llamada de herramienta; ventana deslizante de 7 días con decaimiento ponderado en el tiempo.

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

Rango de puntuaciónNivelAcción predeterminada
0 – 59NormalSin restricciones. Rendimiento completo.
60 – 79ElevadoAlerta en cruces de umbral.
80 – 89AltoLimitación de tasa. Forzado a modo monitoreo.
90 – 100CríticoBloqueo automático + alerta inmediata. Liberación manual requerida.

Consultar puntuaciones de riesgo

bash
# Get current risk scores for all agents in a tenant
curl "https://api.shieldagent.io/risk/scores?tenantId=<tenant-id>" \
  -H 'Authorization: Bearer <admin-key>'

# Get risk history for a specific agent (last 24h)
curl "https://api.shieldagent.io/risk/scores/<agent-id>/history?window=24h" \
  -H 'Authorization: Bearer <admin-key>'
Risk score response
{
  "agentId": "agt_01HXYZ...",
  "score": 67,
  "tier": "elevated",
  "securityScore": 71,
  "complianceScore": 63,
  "trend": "increasing",
  "trendDelta": 14,
  "updatedAt": "2026-04-16T14:23:00Z"
}

Configurar umbrales de aplicación

Anula los umbrales globales por tenant o por agente. Cuando una puntuación supera un umbral, ShieldAgent cambia automáticamente de modo monitor a modo bloqueo.

bash
# Set per-tenant risk thresholds
curl -X PATCH "https://api.shieldagent.io/risk/config?tenantId=<tenant-id>" \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <admin-key>' \
  -d '{
    "elevatedThreshold": 60,
    "highThreshold": 80,
    "criticalThreshold": 90
  }'

autoLockThreshold — cuando se supera, el agente queda suspendido hasta que un revisor humano lo desbloquea. Los eventos se escriben en el registro de auditoría.

Líneas base de comportamiento

ShieldAgent aprende el patrón normal de uso de herramientas de cada agente durante un período de calentamiento configurable. Las desviaciones de la línea base aumentan la puntuación de deriva de herramientas.

bash
# View baseline for an agent
curl "https://api.shieldagent.io/risk/baselines/<agent-id>" \
  -H 'Authorization: Bearer <admin-key>'

# Reset baseline (e.g., after an agent update changes its behavior)
curl -X DELETE "https://api.shieldagent.io/risk/baselines/<agent-id>" \
  -H 'Authorization: Bearer <admin-key>'

Período de calentamiento de línea base

Configura con BASELINE_WARMUP_DAYS . Durante el calentamiento, la puntuación de deriva de herramientas se ajusta para evitar falsos positivos en agentes nuevos.

Alertas de riesgo

Configura reglas de alerta para activarse en umbrales de puntuación de riesgo:

bash
curl -X POST https://api.shieldagent.io/alerts/rules \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <admin-key>' \
  -d '{
    "tenantId": "<tenant-id>",
    "name": "High risk agent alert",
    "condition": "riskScore >= 70",
    "severity": "high",
    "channels": ["webhook", "email"],
    "webhookUrl": "https://hooks.slack.com/..."
  }'
Puntuación de riesgo