Detecção de agentes de IA

Agentes de IA e navegadores autônomos representam uma parcela crescente do tráfego web. OpenAI Operator, Claude for Chrome, Perplexity Comet, Browserbase e outros frameworks de agentes criam sessões reais em navegadores reais, então checagens de User-Agent sozinhas não bastam. cside Device Intelligence expõe esses visitantes pelo objeto bot retornado por /token/v2/verify na Events API.

O que o cside detecta

O veredito de bot combina dois modelos e checagens determinísticas:

• Modelo 1 pontua o fingerprint do dispositivo e os sinais de rede: marcadores de headless e automação (navigator.webdriver, uso de CDP, globais de automação injetadas), anomalias de renderização e de fontes, características TCP e TLS e IPs de datacenter ou hosting
• Modelo 2 pontua o comportamento na página: movimento do cursor, timing dos eventos, eventos não confiáveis (disparados por script) e hooks de APIs JavaScript
• Agentes conhecidos são associados a um bot_agent_id, como google-googleother, quando o tráfego corresponde à assinatura de um crawler ou agente conhecido

Juntos, eles identificam agentes autônomos de navegador, navegadores headless (Puppeteer, Playwright, Selenium), runtimes instrumentados controlados por WebDriver ou CDP e crawlers e scrapers clássicos. A detecção roda server-side depois que o navegador envia a telemetria, então alterar apenas os headers não a contorna.

Ler o veredito de bot

Troque o token de sessão em /token/v2/verify com a sua chave de API de backend. A resposta contém um 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	O veredito. true quando a probabilidade cruza o limiar de decisão ou uma checagem determinística dispara.
bot_probability	number	Probabilidade de o visitante ser um bot, de 0 a 1.
bot_confidence	number	Quão certo o modelo está dessa probabilidade, de 0 a 1. Confiança baixa normalmente significa que havia poucos dados comportamentais disponíveis.
bot_agent_id	string	Bot ou agente identificado quando o tráfego corresponde a uma assinatura conhecida. Vazio quando não há correspondência.
reasons	string[]	Explicações legíveis por trás do veredito.
model_1_score, model_1_threshold	number	Pontuação do modelo de fingerprint e rede e o limiar aplicado a ela.
model_2_score, model_2_threshold	number	Pontuação do modelo comportamental e o seu limiar. Ausentes quando nenhum dado comportamental foi coletado.
session_event_count	number	Número de eventos comportamentais que a sessão produziu.

Decida com base em is_bot. Use bot_probability e bot_confidence quando quiser respostas graduais, por exemplo um desafio entre 0.5 e o limiar e um bloqueio acima dele.

const { status, bot } = data;

if (status !== "completed" || !bot) {
  // A avaliação está pendente ou falhou: fail open
  return allow();
}

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

Combine o veredito com outros sinais da mesma resposta para maior confiança:

• Campos de automação em fingerprint (web_driver, cdp, tamper_injected_global_ids, tamper_probe_blocked) mostram a evidência de automação diretamente
• fingerprint.developer_tools_detected é comum em agentes executados localmente
• fingerprint.virtual_machine_detected sinaliza sessões rodando em VM ou sandbox
• ip_enrichment.hosting e ip_enrichment.is_datacenter_ip sinalizam tráfego de provedores de nuvem

Exemplo de integração

No seu JavaScript do lado do cliente, solicite o token de sessão de fingerprint:

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

if (result.errors) {
  console.error(result.errors);
  throw new Error("A solicitação de telemetria falhou.");
}

const { token: sessionToken } = result;

No seu backend, troque o token de sessão com https://api.cside.com/token/v2/verify e então avalie 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 || "A troca de fingerprint falhou.");
}

if (data.status !== "completed") {
  // 202 pendente ou avaliação com falha: tente de novo depois ou fail open
  return allow();
}

if (data.bot?.is_bot) {
  // Bloqueie, desafie ou registre a requisição
  return respondWithChallenge();
}

/token/v2/verify retorna 202 Accepted com { "status": "pending" } enquanto a avaliação ainda está em processamento. Consulte de novo após um curto intervalo ou faça fail open.

No painel

A linha Bot / Agents na aba Overview de uma sessão mostra o mesmo veredito com as pontuações dos modelos por trás dele. A aba Captured metadata lista as características do modelo de bot quando um vetor de características foi capturado.

Casos de uso comuns

• Proteja formulários e fluxos de checkout - descarte o tráfego de agentes antes que ele chegue ao pagamento ou à criação de conta
• Restrinja o scraping por IA de conteúdo pago - aplique limites de requisição ou níveis de acesso diferentes quando agentes de IA forem detectados
• Meça a parcela de tráfego vinda de agentes - registre bot.is_bot, bot_probability, bot_agent_id e a string user_agent para reportar quanto do seu tráfego é automatizado
• Evidências de chargeback e fraude - combine o objeto bot com fingerprint.device_id para montar uma trilha de auditoria das sessões automatizadas

Próximos passos

• Leia a referência completa da Events API para ver o formato completo da resposta
• Revise o objeto bot_evaluation da exportação S3 para os mesmos campos em exportações batch
• Fale com vendas para ativar Device Intelligence na sua conta