Agentes de IA para desenvolvedores: crie um auditor SEO

definido pelo seu catálogo interno | | observed | Trecho, campo extraído ou cadeia de redirecionamento | | expected | Condição esperada segundo o critério usado | | criterion_ref | Documento, versão e seção que sustentam o diagnóstico | | recommendation | Correção limitada ao que a evidência permite concluir | | confidence | Nível de confiança e motivo | | collection_status | Estado da coleta, renderização e interpretação |

O campo observed muda conforme o diagnóstico:

• Título ou meta description: devolva o conteúdo extraído, a quantidade encontrada e o seletor ou campo de origem.
• Canonical: registre o valor do href, a URL final resolvida e qualquer divergência detectada.
• Status HTTP: inclua o código recebido e a URL consultada.
• Redirecionamento: preserve a cadeia completa, como URL A → 301 → URL B → 302 → URL C → 200.
• Conteúdo renderizado: guarde o trecho relevante e informe se veio do HTML inicial ou do DOM após JavaScript.
• Diretiva de indexação: devolva o valor observado e sua origem, como cabeçalho HTTP ou elemento meta.

Se a ferramenta não preencher a evidência mínima, o agente não deve completar o campo por inferência nem emitir o achado como diagnóstico. Ele deve registrar o campo avaliado como não verificado ou inconclusivo e informar o motivo da insuficiência de evidência.

Separe a observação do critério aplicado

A evidência mostra o que a página entregou. O critério explica por que isso representa um problema. Misturar os dois permite que o modelo transforme preferência em erro técnico.

Considere este caso:

• URL analisada: /produto-a;
• valor observado em canonical: /categoria;
• critério interno: páginas de produto devem apontar para a própria URL quando forem indexáveis;
• diagnóstico: canonical divergente do padrão do projeto;
• recomendação: revisar o href e confirmar se a consolidação em /categoria foi intencional.

A recomendação não pode avançar para “troque obrigatoriamente pela própria URL” sem consultar o padrão do projeto. A divergência pode representar uma configuração deliberada.

Disponibilize critérios internos pelo Brain

Use o Brain ou um armazenamento equivalente para fornecer ao agente:

• padrões de canonical e indexação do projeto;
• convenções para URLs, paginação e parâmetros;
• requisitos do CMS;
• exceções aprovadas pelo time;
• critérios de severidade;
• histórico de decisões técnicas;
• procedimentos de correção aceitos pela equipe.

Cada trecho recuperado precisa manter nome do documento, versão, seção e citação textual. Assim, o achado aponta tanto para a página observada quanto para o conhecimento usado na interpretação.

Por exemplo, o agente pode devolver:

Evidência da página: canonical="/categoria"
Critério citado: “Páginas de produto indexáveis usam canonical autorreferente.”
Origem interna: Padrões SEO — versão 3 — seção Canonical

Na Catcher Agents, o Brain cumpre esse papel ao disponibilizar conhecimento com citação. Quando não encontra uma fonte interna capaz de sustentar o critério, o agente deve declarar essa ausência. Ele não deve substituir o padrão desconhecido por uma prática genérica apresentada como regra do projeto.

Trate falha de coleta como limite, não como diagnóstico

Uma página inacessível não é automaticamente uma página com erro de SEO. Diferencie estados como:

• access_denied: autenticação, bloqueio ou restrição impediu o acesso;
• fetch_failed: a coleta não recebeu uma resposta utilizável;
• render_failed: o navegador não concluiu a renderização;
• content_missing: o campo necessário não apareceu no HTML ou DOM coletado;
• interpretation_uncertain: existem dados, mas eles não sustentam uma conclusão segura;
• completed: coleta e interpretação concluídas.

A resposta deve dizer exatamente o que ficou fora do alcance:

Não foi possível verificar o canonical porque a renderização não terminou. Nenhum diagnóstico foi emitido para esse campo.

Esse limite evita falsos positivos. Também orienta a próxima ação: repetir a coleta, fornecer autenticação, ajustar o renderizador ou encaminhar a página para revisão manual.

Antes de liberar qualquer achado, aplique três bloqueios:

1. Há uma URL identificável?
2. Existe uma evidência observada, como trecho, campo ou cadeia de redirecionamento?
3. O critério e a recomendação estão sustentados pelo Brain ou por uma regra determinística registrada?

Se uma resposta for negativa, o agente não deve emitir o achado como diagnóstico. Ele deve registrar o campo avaliado como não verificado ou inconclusivo, informar o motivo e nunca preencher a lacuna com uma explicação plausível.

Teste o auditor com casos reproduzíveis

Uma arquitetura correta ainda pode falhar por mudança de prompt, parser, ferramenta ou modelo. O próximo passo é transformar os diagnósticos esperados em uma suíte de regressão.

Crie um conjunto de teste com falhas conhecidas

Não valide o agente em sites aleatórios. Monte um corpus versionado com páginas controladas, cada uma ligada a um resultado esperado.

Inclua casos positivos e negativos para cada categoria:

| Categoria | Página de teste | Resultado esperado | |---|---|---| | Status HTTP | URL retorna erro | Detectar o status e registrar a URL afetada | | Redirecionamento | Cadeia entre URLs | Informar cada salto observado | | Canonical | Canonical aponta para outra página | Identificar o destino declarado | | Indexação | Diretiva bloqueia indexação | Exibir a diretiva encontrada | | Metadados | Página sem title | Apontar ausência do elemento | | Links internos | Link aponta para URL inexistente | Associar origem, destino e resposta | | Renderização | Conteúdo aparece apenas após JavaScript | Diferenciar HTML inicial do conteúdo renderizado | | Caso negativo | Página sem a falha avaliada | Não produzir achado para essa categoria |

Para cada fixture, salve:

1. URL ou identificador da página;
2. snapshot do HTML e das respostas HTTP;
3. categoria avaliada;
4. achados esperados;
5. achados que não podem aparecer;
6. evidência mínima exigida;
7. severidade esperada, quando aplicável.

Esse conjunto vira a suíte de regressão. Um novo prompt, modelo ou parser só avança se continuar detectando as falhas conhecidas sem começar a acusar problemas nas páginas negativas.

Meça erro, cobertura e custo separadamente

Uma taxa geral de acerto esconde categorias frágeis. Calcule as métricas por tipo de diagnóstico e também para o conjunto completo.

• Verdadeiro positivo: o auditor encontrou uma falha presente no resultado esperado.
• Falso positivo: o auditor reportou uma falha ausente na página.
• Falso negativo: a falha existe, mas não apareceu no diagnóstico.
• Precisão: entre os achados produzidos, quantos estavam corretos.
• Recall: entre as falhas esperadas, quantas foram detectadas.
• Cobertura de URLs: quantas URLs previstas foram coletadas e analisadas.
• Custo: cost_usd total, por URL processada e por achado válido.
• Latência: tempo total da execução e percentis por etapa, como coleta, ferramenta e interpretação do modelo.

Acompanhe os resultados em uma matriz:

| Categoria | Esperados | Detectados | Falsos positivos | Falsos negativos | Cobertura | Custo | Latência | |---|---:|---:|---:|---:|---:|---:|---:| | Canonical | | | | | | | | | Indexação | | | | | | | | | Redirecionamento | | | | | | | | | Links internos | | | | | | | | | Renderização | | | | | | | |

Uma execução pode ter boa precisão e cobertura ruim. Isso acontece quando os diagnósticos emitidos estão corretos, mas parte do site não foi percorrida. Também pode ter recall alto e precisão baixa, sinal de que o agente encontra os erros conhecidos às custas de muitos alarmes falsos.

Compare uma mudança por vez

Use o mesmo snapshot de páginas para comparar versões. Se o corpus mudar junto com o prompt, você não saberá qual alteração causou a diferença.

Registre em cada rodada:

• versão e hash do prompt;
• modelo e parâmetros de geração;
• versão das regras determinísticas;
• versão de cada ferramenta;
• snapshot do corpus;
• limite de URLs e budget;
• run_id, custo e latência;
• saída estruturada e evidências retornadas.

Crie uma versão de controle e altere apenas uma variável por experimento:

1. Prompt A versus prompt B, com o mesmo modelo, regras e ferramentas.
2. Modelo A versus modelo B, com o mesmo prompt e entradas.
3. Regra A versus regra B, sem trocar a interpretação do modelo.
4. Ferramenta A versus ferramenta B, preservando o restante do fluxo.

Quando houver geração não determinística, execute cada variante várias vezes sobre o mesmo corpus. Compare a média e a variação dos resultados, não apenas a melhor execução. Uma versão que acerta uma vez e falha nas demais não serve como baseline de produção.

Defina critérios de aprovação antes do teste. Por exemplo: nenhum novo falso positivo em diretivas de indexação, cobertura integral das fixtures obrigatórias e custo por URL dentro do budget. Assim, a decisão de publicar uma versão deixa de depender de uma leitura subjetiva da resposta do agente.

Leve o agente ao runtime sem misturar clientes

No protótipo, uma variável global e um histórico compartilhado podem passar despercebidos. Em produção, cada execução precisa nascer vinculada a dois identificadores: o tenant que contratou o serviço e o usuário final que iniciou a auditoria.

Isole o contexto em quatro camadas

Não confie no prompt para separar clientes. Aplique o escopo no servidor, antes de recuperar memória, liberar ferramentas ou consultar evidências.

| Camada | Escopo recomendado | O que não pode acontecer | |---|---|---| | Memória | tenant_id + user_id | Um analista receber contexto salvo por outro cliente | | Credenciais | tenant_id + ferramenta autorizada | Uma auditoria usar token ou propriedade de outro tenant | | Histórico | tenant_id + user_id + sessão | O modelo incorporar conversas de outro usuário | | Evidências | tenant_id + run_id + URL | Um achado apontar para HTML coletado em outra execução |

O tenant_id deve vir da autenticação do seu backend, não de um campo editável enviado pelo navegador. O mesmo vale para credenciais de APIs, crawlers e serviços externos: mantenha os segredos no servidor e entregue às ferramentas apenas a autorização necessária para aquela execução.

A memória também exige dois níveis. Dados permanentes do projeto, como domínio principal e preferências de rastreamento, podem pertencer ao tenant. Já decisões, comentários e auditorias anteriores devem respeitar o usuário final. Essa separação permite que uma agência opere vários clientes sem criar um histórico único e contaminado.

Transmita o progresso por REST e SSE

Uma auditoria pode percorrer muitas URLs e chamar várias ferramentas. Se o frontend esperar uma resposta única, a interface parece travada e o usuário não sabe se o agente está trabalhando ou falhou.

Exponha a execução por REST e publique eventos por SSE conforme o runtime avança:

1. Descoberta: domínio validado, sitemap localizado e fila de URLs criada.
2. Coleta: página processada, status recebido e evidência armazenada.
3. Análise: regras executadas e páginas encaminhadas ao modelo.
4. Conclusão: achados consolidados, custos registrados e relatório disponível.

Cada evento deve carregar pelo menos o run_id, a fase atual e um resumo seguro para exibição. Evite transmitir credenciais, HTML completo ou conteúdo interno de outras ferramentas.

Na Catcher Agents, a gente embute esse fluxo por REST + SSE em três chamadas: seu backend fornece um runtime token com escopo, o app abre a sessão e envia a mensagem acompanhando os eventos. Assim, você integra o auditor sem prender o produto a um SDK proprietário.

Torne cada auditoria reconstruível

O relatório final não basta para depurar produção. Você precisa saber qual ferramenta rodou, quanto tempo levou, que evidência retornou e quanto daquela execução consumiu o budget.

Registre estes campos desde o início:

• run_id: identificador único usado em eventos, logs, evidências e relatório;
• tenant_id e user_id: escopo que autorizou a execução;
• tool_calls: ferramenta, entrada autorizada, saída, erro e duração;
• latência total e latência por etapa;
• cost_usd: custo acumulado da execução;
• budget: limite definido antes de iniciar o trabalho;
• referências das evidências usadas em cada achado;
• estado final: concluído, interrompido, expirado ou limitado pelo budget.

Use o mesmo run_id em toda a cadeia. Se o agente afirmar que uma página não possui canonical, você deve conseguir localizar a coleta daquela URL, verificar o HTML observado, identificar a regra aplicada e conferir se o modelo apenas explicou o diagnóstico.

No Console da Catcher Agents, a gente centraliza turnos, tool calls, latência, cost_usd e uso do budget. Isso permite reconstruir uma auditoria específica sem combinar manualmente logs do backend, do crawler e do provedor do modelo. Para um SaaS B2B2C, essa rastreabilidade transforma agentes de IA para desenvolvedores em uma operação auditável por cliente, usuário e execução.

Corrija os bloqueios que mais quebram auditorias em produção

O fluxo pode funcionar no corpus e falhar em sites reais por causa de JavaScript, redirecionamentos, parâmetros, paginação e respostas instáveis. Esses casos precisam virar estados explícitos do pipeline.

Diferencie página limpa de página que o rastreador não conseguiu acessar

Um 200 OK não prova que o conteúdo útil estava disponível. O auditor precisa registrar como a página foi obtida, o que foi renderizado e por que uma URL ficou sem análise.

| Bloqueio | Falha comum | Tratamento no pipeline | |---|---|---| | JavaScript | Analisar apenas o HTML inicial e concluir que faltam conteúdo, links ou metadados | Compare HTML recebido e DOM renderizado. Acione navegador headless apenas quando a página depender de JavaScript | | Loop de redirecionamento | Seguir a cadeia até atingir timeout | Guarde cada URL visitada, interrompa ao reencontrar uma delas e registre a cadeia completa | | URLs duplicadas | Auditar separadamente versões com barra final, caixa diferente ou parâmetros equivalentes | Normalize a URL antes de enfileirar e mantenha a URL original como evidência | | Parâmetros | Rastrear combinações de filtros, ordenação e rastreamento | Classifique parâmetros por função e defina quais alteram conteúdo relevante | | Paginação | Parar na primeira página ou entrar em sequências sem fim | Detecte o padrão, registre relações entre páginas e aplique limite de profundidade | | Respostas instáveis | Tratar um timeout ou erro temporário como problema permanente | Faça novas tentativas controladas e preserve status, horário, duração e hash da resposta | | Bloqueio de rastreamento | Declarar que a página não existe quando houve bloqueio por autenticação, firewall ou política de rastreamento | Retorne estado blocked ou inconclusive, nunca passed |

O renderizador deve ser seletivo. Primeiro, faça uma requisição HTTP simples. Use JavaScript apenas quando o HTML inicial não contiver os elementos necessários ou quando a aplicação carregar conteúdo depois da resposta. Renderizar todas as páginas em navegador headless aumenta fila, latência e custo sem melhorar todos os diagnósticos.

Para redirecionamentos, mantenha um conjunto visited_urls por cadeia e um limite max_redirect_hops. Se a URL reaparecer, encerre a coleta com redirect_loop. Se o limite for atingido, retorne redirect_limit_exceeded. Não entregue essa decisão ao modelo.

Controle a expansão do rastreamento antes de chamar o modelo

Calendários, buscas internas, filtros e parâmetros podem gerar um espaço de URLs que cresce a cada página. Um auditor sem fronteiras continua descobrindo URLs até consumir o budget ou travar a fila.

Defina limites explícitos por execução:

• max_urls: total de URLs que o run_id pode processar;
• max_depth: distância máxima desde as URLs de entrada;
• max_query_variants: variações aceitas para o mesmo caminho;
• max_redirect_hops: tamanho permitido para uma cadeia;
• max_rendered_pages: quantidade de páginas que pode usar navegador;
• max_retries: novas tentativas para respostas instáveis;
• timeout_ms: tempo máximo por requisição e por renderização;
• budget: teto operacional da execução.

Quando um limite for atingido, o relatório deve indicar cobertura parcial. Registre quantas URLs foram descobertas, processadas, ignoradas, bloqueadas e interrompidas pelo budget. Sem essa distinção, uma auditoria incompleta parece uma auditoria sem erros.

A fila também precisa de controle por domínio e por tenant. Separe descoberta, coleta, renderização e análise em jobs distintos. Assim, uma página lenta não segura toda a execução, e um site grande não ocupa os workers destinados a outros clientes.

Normalize sem apagar diferenças relevantes

Deduplicação não significa remover parâmetros indiscriminadamente. ?utm_source=x pode representar o mesmo conteúdo, enquanto ?page=2 ou ?color=azul pode alterar a página analisada.

Crie duas representações:

1. source_url: URL encontrada no HTML, sitemap ou redirecionamento;
2. normalized_url: versão usada para deduplicação e controle de fila.

A normalização pode ajustar host, protocolo, fragmento, barra final e parâmetros classificados como irrelevantes. Preserve a transformação aplicada. Isso permite reconstruir por que duas URLs entraram no mesmo grupo.

Para paginação, não remova o parâmetro antes de identificar sua função. Agrupe as páginas pela coleção, mas mantenha cada posição necessária para verificar links, conteúdo e comportamento da sequência. Interrompa padrões que avancem sem produzir conteúdo novo, como calendários com datas indefinidas.

Não envie o HTML integral ao modelo

O HTML bruto carrega scripts, estilos, menus repetidos, dados de rastreamento e atributos que não ajudam no diagnóstico. Enviá-lo integralmente aumenta tokens, cost_usd e ruído de interpretação.

Faça a extração antes da chamada ao modelo. O payload pode conter:

• URL original e normalizada;
• status HTTP e cadeia de redirecionamentos;
• título e meta description;
• diretivas encontradas;
• headings em ordem;
• links internos relevantes;
• dados estruturados extraídos;
• texto principal em blocos;
• diferenças entre HTML inicial e DOM renderizado;
• identificadores das evidências armazenadas;
• erros, timeouts e bloqueios observados.

Mantenha o snapshot bruto fora do prompt. O agente recebe trechos selecionados e pode solicitar evidências adicionais por ferramenta quando precisar investigar uma hipótese. Isso reduz custo sem perder rastreabilidade.

Separe regra, interpretação e recomendação

Misturar tudo em um prompt transforma um resultado verificável em opinião difícil de reproduzir. Organize o pipeline em três saídas:

• Regra determinística: detecta status, ausência, contagem, duplicidade, loop ou divergência observável.
• Interpretação do modelo: explica contexto, prioridade provável e relação entre achados.
• Recomendação: propõe uma ação compatível com a evidência disponível.

O modelo não deve decidir se houve loop de redirecionamento ou se uma URL retornou determinado status. O coletor já possui esses dados. O modelo pode explicar o impacto provável e sugerir a investigação seguinte.

Também não aceite texto livre como resposta final. Valide a saída contra um schema com campos como finding_type, severity, confidence, source_url, evidence_ids, diagnosis, recommendation e requires_human_review. Rejeite objetos sem evidência, tipos desconhecidos ou severidade fora dos valores aceitos. Faça retry apenas do estágio que falhou, não do rastreamento inteiro.

Use cache sem esconder respostas instáveis

O cache deve evitar trabalho repetido, não substituir evidência recente sem aviso. Monte a chave com tenant, URL normalizada, método de coleta, configuração de renderização e versão do extrator.

Armazene junto:

• horário da coleta;
• status e cabeçalhos relevantes;
• hash do corpo;
• versão do pipeline;
• origem do resultado: fresh ou cache;
• tempo de expiração;
• tentativas realizadas.

Se duas coletas próximas retornarem status, conteúdo ou redirecionamentos diferentes, marque o achado como instável. Preserve as duas respostas. Escolher uma delas silenciosamente torna o diagnóstico impossível de reproduzir.

Exija revisão humana antes de mudanças de alto impacto

O auditor pode abrir tarefas e preparar correções. Ele não deve publicar automaticamente alterações amplas com base em uma única execução.

Encaminhe para revisão humana recomendações que envolvam:

• mudanças em robots.txt;
• aplicação de noindex;
• alteração de canonical;
• redirecionamentos em massa;
• remoção de páginas;
• mudanças em templates compartilhados;
• reescrita de navegação ou paginação;
• correções que afetem vários tenants, domínios ou ambientes.

A tela de revisão deve mostrar evidência, regra acionada, interpretação, URLs afetadas, cobertura da execução e limites atingidos. Preserve também run_id, configuração, versão das ferramentas, chamadas realizadas, latência e cost_usd. Assim, o time consegue repetir a auditoria, comparar duas execuções e descobrir se a diferença veio do site, do coletor, das regras ou do modelo.

Conclusão

Um auditor de SEO técnico confiável separa coleta, regras, interpretação e evidência. O modelo não decide sozinho o que existe na página. Ele recebe dados estruturados, interpreta achados verificáveis e devolve cada diagnóstico ligado ao trecho, status HTTP ou metadado que o produziu.

Comece com um único teste, como detectar divergências entre URL final e canonical. Crie páginas de teste com casos válidos e inválidos, execute o fluxo duas vezes e compare achado, evidência, severidade e recomendação. Só adicione novos diagnósticos quando esse resultado for reproduzível.

Ao levar o auditor para um SaaS, a Catcher Agents permite expor esse fluxo por REST + SSE, conectar ferramentas de coleta e manter cada tenant isolado. No Console, você reconstrói os turnos pelo run_id e inspeciona tool calls, latência, cost_usd e consumo de budget antes de ampliar a auditoria.