Como lidar com tráfego Unknown no seu app

Unknown é um erro ou um resultado?

Quando você começa a classificar interações como Human, Human + AI, Agent ou Unknown, o grupo Unknown muitas vezes é maior do que as pessoas esperam. É tentador tratar isso como uma lacuna a esconder, seja colocando Unknown dentro de Human, seja tratando-o como suspeito. Ambas as escolhas causam problemas.

Unknown significa que a evidência disponível não dá suporte a uma determinação confiável. Uma request de um client que não executa JavaScript, uma chamada para um endpoint em que você não coleta sinais, uma sessão que terminou depois de uma página: tudo isso pode ser perfeitamente legítimo, e nenhum desses casos lhe dá informação suficiente para dizer quem ou o que estava atuando.

Relatar Unknown com honestidade é o que mantém as outras classes confiáveis. Se seu sistema nunca diz Unknown, todo resultado Human é em parte um palpite, e você não consegue saber qual parte. Nosso artigo sobre por que Unknown é um resultado válido ao classificar tráfego de IA explica o raciocínio com mais profundidade.

Este guia cobre como lidar com Unknown na prática: fallbacks explícitos por route, as regras que impedem seu vazamento para outras classes, como monitorá-lo e como reduzi-lo onde isso importa.

Etapa 1: Nunca use Human como padrão

O erro mais comum é uma função de classificação que retorna Human sempre que não encontra sinal de automação. Parece razoável e está errado. A ausência de um sinal de bot não é a presença de um sinal humano.

// Wrong: silence becomes Human
function classifyWrong(e: Evidence) {
  if (e.signatureValid) return { actor: "agent", basis: "verified" };
  if (e.declaredAgent) return { actor: "agent", basis: "declared" };
  return { actor: "human", basis: "inferred" };
}

// Right: Human requires positive evidence, otherwise Unknown
function classify(e: Evidence) {
  if (e.signatureValid) return { actor: "agent", basis: "verified" };
  if (e.declaredAgent) return { actor: "agent", basis: "declared" };
  if (e.interactiveSession) return { actor: "human", basis: "inferred" };
  return { actor: "unknown", basis: "unknown" };
}

Aplique a mesma regra em todos os lugares em que os resultados são produzidos: timeouts, erros, entradas de cache desatualizadas e telemetria ausente devem todos produzir Unknown. Escreva um teste para cada um desses caminhos para que o comportamento não possa regredir silenciosamente. O exemplo abaixo usa o Node.js test runner integrado.

import { test } from "node:test";
import assert from "node:assert/strict";

test("missing evidence is unknown, not human", () => {
  const r = classify({ signatureValid: false, declaredAgent: false, interactiveSession: false });
  assert.equal(r.actor, "unknown");
});

Etapa 2: Dê a cada route um fallback explícito

Unknown precisa de um comportamento definido, e o comportamento certo depende da route. Decida isso por route, documente e mantenha em configuração. Para ver como esses fallbacks se encaixam em um modelo de policy mais amplo, consulte como projetar policies em nível de app para humanos e agentes de IA.

O padrão é simples. Para routes de baixo risco, Unknown se comporta como tráfego normal. Para routes de alto risco, Unknown recebe a mesma proteção que a route já possui. Em nenhum dos casos o resultado do actor torna as coisas piores para um usuário não classificado, mas legítimo.

type Fallback = "allow" | "standard_limit" | "existing_checks" | "review";

const unknownFallback: Record<string, Fallback> = {
  "GET /docs/*": "allow",
  "GET /api/catalog": "standard_limit",
  "POST /signup": "existing_checks",
  "POST /account/password": "existing_checks",
  "POST /exports": "review",
};

Etapa 3: Trate timeouts e erros da mesma forma

A avaliação de actor fica no caminho da request, então precisa de um orçamento de tempo estrito. Quando o orçamento for excedido, produza Unknown e aplique o fallback da route. Nunca bloqueie uma request porque a avaliação ficou lenta.

async function withBudget<T>(work: Promise<T>, ms: number, onTimeout: T): Promise<T> {
  let timer: NodeJS.Timeout;
  const timeout = new Promise<T>((resolve) => {
    timer = setTimeout(() => resolve(onTimeout), ms);
  });
  try {
    return await Promise.race([work, timeout]);
  } finally {
    clearTimeout(timer!);
  }
}

const result = await withBudget(evaluateActor(req), 150, { actor: "unknown", basis: "unknown" });

Registre por que um resultado é Unknown: sem evidência, timeout, erro de avaliação ou evidência desatualizada. Esses motivos mostram o que você precisa corrigir.

Etapa 4: Não trate Unknown como suspeito

Unknown não é uma pontuação de risco. Muitos clients legítimos sempre serão Unknown em algumas routes: ferramentas de linha de comando, integrações server-side sem assinaturas, ferramentas de acessibilidade, browsers com foco em privacidade e leitores simples de feeds. Até grandes operadores de IA identificam hoje seus fetchers principalmente por user agent e intervalos de IP publicados. A documentação de crawler da OpenAI, por exemplo, lista uma string de user agent e um arquivo de endereços IP publicado para cada um de seus bots, em novembro de 2026.

Se você quiser agir sobre comportamento suspeito, baseie isso em comportamento que você consiga descrever, como taxas de request, padrões de login com falha ou relatos de abuso, com sua própria evidência. Mantenha essa lógica separada da classe de actor para que nenhuma distorça a outra.

Etapa 5: Como monitorar sua taxa de Unknown?

A taxa de Unknown é a parcela de interações classificadas como Unknown. Acompanhe por route, por contexto de integração e ao longo do tempo. Ela é uma das métricas de saúde mais úteis que você tem.

type Row = { route: string; actor: string };

export function unknownRate(rows: Row[]) {
  const byRoute = new Map<string, { total: number; unknown: number }>();
  for (const r of rows) {
    const s = byRoute.get(r.route) ?? { total: 0, unknown: 0 };
    s.total += 1;
    if (r.actor === "unknown") s.unknown += 1;
    byRoute.set(r.route, s);
  }
  return [...byRoute].map(([route, s]) => ({ route, rate: s.unknown / s.total, total: s.total }));
}

O que os números dizem:

• Uma taxa alta e estável em uma route normalmente significa que você está perdendo um sinal ali. Uma page que nunca carrega sua integração de browser, ou uma API que nunca recebe requests assinadas, permanecerá majoritariamente Unknown.
• Uma alta repentina geralmente significa que algo mudou na sua stack, por exemplo uma release que removeu um header, uma regra de CDN que remove headers de assinatura ou uma mudança no frontend que parou de enviar as declarações do seu app.
• Uma queda repentina também merece verificação. Se Unknown cai enquanto Human sobe, confirme que houve entrada de nova evidência, e não uma mudança silenciosa de fallback.

Alerta para mudanças bruscas, não para níveis absolutos. Cada application tem seu próprio normal.

Etapa 6: Como reduzir Unknown onde isso importa?

Você não precisa levar Unknown a zero. Você precisa de evidência suficiente nas routes em que as decisões importam. Trabalhe nelas em ordem de impacto:

1. Adicione evidência primeiro nas routes de alto impacto. Se as mudanças de conta são em sua maioria Unknown, é aí que uma integração de browser ou uma checagem server-side traz retorno.
2. Convide clients automatizados a se identificar. Publique documentação para sua API explicando como agents podem assinar requests com HTTP Message Signatures e as convenções do IETF Web Bot Auth, e ofereça uma experiência melhor para clients verificados, como limites maiores ou respostas estruturadas. Clients que puderem se verificar começarão a fazê-lo.
3. Use o conhecimento do seu próprio application. Se os usuários interagem com seu assistente integrado, registre isso como uma declaração. Seu app muitas vezes sabe mais do que a rede sabe.
4. Corrija a infraestrutura. Garanta que os proxies encaminhem os headers de que você depende e que a avaliação tenha orçamento de tempo suficiente para concluir.

Para uma visão prática dos sinais que tiram tráfego de Unknown, leia como saber se o tráfego do website vem de agentes de IA.

Etapa 7: Mostre Unknown com honestidade nos dashboards

Exiba Unknown como sua própria série, com o mesmo peso visual que as outras classes. Não o esconda em um bucket "other" e não o colore como um alerta. Quando as partes interessadas veem uma grande parcela Unknown, a reação certa é "onde precisamos de mais evidência", e não "onde estão os bots".

Etapa 8: Revise Unknown com base em resultados, não em suposições

A cada poucas semanas, pegue uma amostra de interações Unknown das suas routes mais importantes e veja o que realmente aconteceu. A sessão concluiu uma compra, criou um projeto, leu três articles ou falhou repetidamente no login? Os resultados mostram que tipo de tráfego está no bucket sem forçar um rótulo prematuro sobre ele.

Agrupe o que você encontrar em três categorias práticas:

1. Legítimo e de baixo risco. Feed readers, link previews, ferramentas de monitoramento e pessoas com configurações de privacidade. Mantenha o fallback da route como está.
2. Automação legítima que poderia se identificar. Integrações e agents que usariam de bom grado um caminho estruturado ou assinariam requests se você oferecesse um. Publique orientação e entre em contato quando puder.
3. Comportamento que precisa de seu próprio controle. Padrões de credential stuffing ou scraping, ambos catalogados no projeto OWASP Automated Threats to Web Applications. Aborde isso com controles baseados em comportamento que tenham sua própria evidência, como taxas de falha de login, e mantenha-os separados da classe de actor.

Essa revisão mantém seus fallbacks ancorados no tráfego real e lhe dá uma lista clara de onde adicionar evidência em seguida.

Perguntas comuns

Unknown deve contar para rate limits? Use seus limites padrão. Rate limiting por classe é aceitável para agents verificados, que podem receber limites maiores, mas Unknown deve receber o limite normal, não um limite punitivo.

Podemos challenge usuários Unknown? Apenas onde a route já challenge todos nessa situação. Adicionar um challenge apenas porque o resultado é Unknown penaliza usuários legítimos cujos clients enviam menos sinais.

Unknown vai diminuir à medida que os standards amadurecem? À medida que mais clients automatizados assinarem requests, mais tráfego de agents sairá de Unknown ou declared e passará para verified. Seu monitoramento mostrará essa mudança route por route.

Onde Proof of Actor se encaixa

Proof of Actor reporta Unknown como um resultado de primeira classe, com o motivo, e nunca o converte em Human. Seu application escolhe o fallback para cada route, e as analytics mostram onde a cobertura termina para que você possa adicionar evidência onde isso importa.

Para configurar isso em um application de produção com a nossa equipe, candidate-se ao acesso antecipado. Para entender exatamente o que a evidência pode estabelecer, leia Detection & Limitations.

Fontes

• RFC 9421: HTTP Message Signatures: o standard que clients automatizados podem usar para assinar requests
• draft-ietf-webbotauth-httpsig-protocol: rascunho do IETF Web Bot Auth para tráfego automatizado assinado (work in progress em novembro de 2026)
• OpenAI: Overview of OpenAI Crawlers: strings de user agent e arquivos de endereços IP publicados para bots da OpenAI
• OWASP Automated Threats to Web Applications: taxonomia de ameaças automatizadas como credential stuffing e scraping
• Node.js test runner: o módulo node:test usado no exemplo