Detección de agentes de IA

Los agentes de IA y los navegadores autónomos representan una parte creciente del tráfico web. OpenAI Operator, Claude for Chrome, Perplexity Comet, Browserbase y otros frameworks de agentes generan sesiones reales en navegadores reales, por lo que las comprobaciones de User-Agent por sí solas no los detectan. cside Device Intelligence expone estos visitantes mediante el objeto bot que devuelve /token/v2/verify en la Events API.

Qué detecta cside

El veredicto de bot combina dos modelos más comprobaciones deterministas:

• Modelo 1 puntúa el fingerprint del dispositivo y las señales de red: marcadores de headless y automatización (navigator.webdriver, uso de CDP, globales de automatización inyectados), anomalías de renderizado y fuentes, características TCP y TLS, e IPs de centro de datos o hosting
• Modelo 2 puntúa el comportamiento en la página: movimiento del cursor, timing de eventos, eventos no confiables (despachados por script) y hooks de APIs de JavaScript
• Agentes conocidos se asocian a un bot_agent_id, como google-googleother, cuando el tráfico encaja con la firma de un crawler o agente conocido

En conjunto identifican agentes de navegador autónomos, navegadores headless (Puppeteer, Playwright, Selenium), runtimes instrumentados controlados por WebDriver o CDP, y crawlers y scrapers clásicos. La detección se ejecuta server-side después de que el navegador envía la telemetría, por lo que cambiar solo los headers no la evita.

Leer el veredicto de bot

Intercambie el token de sesión en /token/v2/verify con su clave API de backend. La respuesta contiene un objeto bot:

{
  "status": "completed",
  "bot": {
    "is_bot": true,
    "bot_probability": 0.94,
    "bot_confidence": 0.88,
    "bot_agent_id": "",
    "reasons": [
      "navigator.webdriver is set",
      "cursor movement scored as automated"
    ],
    "model_1_score": 0.91,
    "model_1_threshold": 0.7,
    "model_2_score": 0.86,
    "model_2_threshold": 0.6,
    "session_event_count": 42
  }
}

Campo	Tipo	Significado
is_bot	boolean	El veredicto. true cuando la probabilidad supera el umbral de decisión o se activa una comprobación determinista.
bot_probability	number	Probabilidad de que el visitante sea un bot, de 0 a 1.
bot_confidence	number	Grado de certeza del modelo en esa probabilidad, de 0 a 1. Una confianza baja suele significar que había pocos datos de comportamiento disponibles.
bot_agent_id	string	Bot o agente identificado cuando el tráfico coincide con una firma conocida. Vacío cuando no hay coincidencia.
reasons	string[]	Explicaciones legibles detrás del veredicto.
model_1_score, model_1_threshold	number	Puntuación del modelo de fingerprint y red, y el umbral que se le aplica.
model_2_score, model_2_threshold	number	Puntuación del modelo de comportamiento y su umbral. Ausentes cuando no se recopilaron datos de comportamiento.
session_event_count	number	Número de eventos de comportamiento que produjo la sesión.

Tome la decisión con is_bot. Use bot_probability y bot_confidence cuando quiera respuestas graduadas, por ejemplo un challenge entre 0.5 y el umbral y un bloqueo por encima de él.

const { status, bot } = data;

if (status !== "completed" || !bot) {
  // La evaluación está pendiente o falló: fail open
  return allow();
}

if (bot.is_bot) {
  return respondWithChallenge(bot.reasons);
}

Combine el veredicto con otras señales de la misma respuesta para mayor confianza:

• Campos de automatización en fingerprint (web_driver, cdp, tamper_injected_global_ids, tamper_probe_blocked) muestran la evidencia de automatización directamente
• fingerprint.developer_tools_detected es habitual en agentes ejecutados localmente
• fingerprint.virtual_machine_detected marca sesiones que se ejecutan en una VM o sandbox
• ip_enrichment.hosting e ip_enrichment.is_datacenter_ip marcan tráfico procedente de proveedores cloud

Ejemplo de integración

En su JavaScript del lado del cliente, solicite el token de sesión de fingerprint:

const result = await sendClientTelemetry({
  userId: "1234567890",
});

if (result.errors) {
  console.error(result.errors);
  throw new Error("La solicitud de telemetría falló.");
}

const { token: sessionToken } = result;

En su backend, intercambie el token de sesión con https://api.cside.com/token/v2/verify y luego evalúe bot.is_bot:

const response = await fetch("https://api.cside.com/token/v2/verify", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CSIDE_FINGERPRINT_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ token: sessionToken }),
});

const data = await response.json();

if (!response.ok) {
  throw new Error(data.error || "El intercambio de fingerprint falló.");
}

if (data.status !== "completed") {
  // 202 pending o una evaluación fallida: reintente más tarde o fail open
  return allow();
}

if (data.bot?.is_bot) {
  // Bloquee, lance un challenge o registre la solicitud
  return respondWithChallenge();
}

/token/v2/verify devuelve 202 Accepted con { "status": "pending" } mientras la evaluación sigue en proceso. Vuelva a consultar tras una breve espera o aplique fail open.

En el panel

La fila Bot / Agents en la pestaña Overview de una sesión muestra el mismo veredicto con las puntuaciones de los modelos detrás de él. La pestaña Captured metadata enumera las features del modelo de bot cuando se capturó un vector de features.

Casos de uso comunes

• Proteger formularios y flujos de pago - descarte el tráfico de agentes antes de que llegue al pago o a la creación de cuentas
• Restringir el scraping de IA en contenido de pago - aplique límites de solicitudes o niveles de acceso distintos cuando se detecten agentes de IA
• Medir la proporción de tráfico automatizado - registre bot.is_bot, bot_probability, bot_agent_id y la cadena user_agent para informar sobre qué parte de su tráfico está automatizada
• Evidencia para contracargos y fraude - combine el objeto bot con fingerprint.device_id para crear un registro de auditoría de las sesiones automatizadas

Siguientes pasos

• Lea la referencia completa de Events API para ver la forma completa de la respuesta
• Revise el objeto bot_evaluation de la exportación S3 para ver los mismos campos en las exportaciones batch
• Contacte a ventas para activar Device Intelligence en su cuenta