Agentes de IA para desenvolvedores: crie um auditor de SEO

houver um relatório utilizável, mas parte das páginas, verificações ou da priorização tiver falhado. Reserve failed para execuções que não produziram evidência suficiente para um relatório técnico.

Em uma execução partial, identifique o estágio afetado e seu alcance. Exemplos: “12 de 140 páginas excederam o timeout”, “a verificação check_id=structured_data falhou em 8 páginas” ou “os achados foram produzidos, mas a etapa de priorização não terminou”. O relatório continua disponível, porém não esconde os limites da auditoria.

Estruture achados que um desenvolvedor consiga corrigir

Use um schema fixo para cada diagnóstico

Não deixe o agente devolver um parágrafo livre. Cada achado precisa seguir um contrato que o backend consiga validar, armazenar e transformar em ticket.

| Campo | O que deve conter | Exemplo | |---|---|---| | category | Área técnica do problema | metadata | | severity | Prioridade conforme critérios definidos pelo produto | high | | affected_url | URL exata em que o problema foi observado | /produtos/tenis-azul | | observed_evidence | Dado retornado pela ferramenta, sem interpretação | title: null | | expected_impact | Consequência provável, descrita sem promessa | A página fica sem um título próprio nos resultados de busca. | | suggested_fix | Alteração técnica executável | Adicionar uma tag <title> única no template de produto. | | confidence | Confiança do agente na interpretação | 0.98 |

Um objeto mínimo pode seguir este formato:

{
  "category": "metadata",
  "severity": "high",
  "affected_url": "https://exemplo.com/produtos/tenis-azul",
  "observed_evidence": {
    "check": "document_title",
    "value": null,
    "source": "rendered_html"
  },
  "expected_impact": "A página fica sem um título próprio nos resultados de busca.",
  "suggested_fix": "Adicionar uma tag <title> única no template de produto.",
  "confidence": 0.98
}

Defina os valores aceitos para category e severity com enums. Isso impede variações como alta, grave e crítico para a mesma prioridade. Valide também tipos, campos obrigatórios e URLs antes de persistir o resultado.

Separe evidência, validação e interpretação

observed_evidence deve registrar apenas o que a coleta encontrou. O resultado técnico da regra pertence ao validador. Impacto, causa provável e correção pertencem à interpretação do modelo.

Considere uma página que retorna estas informações:

{
  "status_code": 200,
  "canonical": null,
  "robots_meta": "index,follow"
}

O fato coletado é: a ferramenta não encontrou uma canonical no HTML analisado. O validador pode classificar o resultado conforme a regra documentada para canonical_missing. O agente não pode converter isso em “a página está duplicada”. Duplicidade exige comparação com outras URLs e conteúdo adicional.

Estruture essa fronteira no próprio objeto:

{
  "observed_evidence": {
    "canonical": null,
    "status_code": 200,
    "collection_source": "rendered_html"
  },
  "validation": {
    "check_id": "canonical_missing",
    "result": "failed",
    "criterion_version": "canonical_rules_v1"
  },
  "interpretation": {
    "expected_impact": "A ausência de canonical pode dificultar a indicação da URL preferencial quando houver versões equivalentes.",
    "suggested_fix": "Verificar se existe uma URL equivalente e, nesse caso, declarar a canonical correspondente.",
    "confidence": 0.72
  }
}

A interface também deve exibir os blocos separadamente. O desenvolvedor precisa distinguir o dado reproduzível, o resultado da regra e a explicação gerada pelo agente.

Agrupe repetições sem perder as páginas afetadas

Um erro no template de produto pode aparecer em centenas de páginas. Criar um ticket por URL gera ruído; mostrar apenas três exemplos esconde o alcance real.

Mantenha cada ocorrência individual e crie uma camada de agrupamento por:

categoria e código do diagnóstico;
template identificado;
padrão de URL;
evidência equivalente;
correção sugerida.

{
  "group_id": "missing-title-product-template",
  "issue_code": "TITLE_MISSING",
  "url_pattern": "/produtos/*",
  "template": "product-detail",
  "affected_urls": [
    "https://exemplo.com/produtos/tenis-azul",
    "https://exemplo.com/produtos/tenis-verde",
    "https://exemplo.com/produtos/tenis-preto"
  ],
  "suggested_fix": "Adicionar a geração da tag <title> ao template product-detail."
}

No painel, você pode paginar a lista. No armazenamento, preserve todas as URLs e os respectivos achados atômicos. Assim, o time corrige uma causa comum e depois consegue executar outra coleta para verificar cada página.

Trate ausência de dados como resultado inconclusivo

O agente deve recusar o diagnóstico quando a ferramenta não retornar evidência suficiente. Timeout, bloqueio do crawler, HTML vazio e falha de renderização não provam que um elemento está ausente.

Nesses casos, devolva um estado explícito em vez de fabricar um achado:

{
  "status": "inconclusive",
  "affected_url": "https://exemplo.com/area-restrita",
  "reason": "render_timeout",
  "missing_data": [
    "rendered_html",
    "document_head"
  ],
  "suggested_action": "Repetir a coleta com autenticação e limite de tempo adequado."
}

A regra operacional deve ser rígida:

Há evidência suficiente: o validador gera o resultado, e o agente pode explicá-lo.
A coleta falhou: marque como inconclusive.
A evidência admite mais de uma explicação: reduza confidence e descreva a incerteza.
A conclusão depende de um dado não coletado: informe qual dado falta e não atribua severidade ao suposto problema.

Essa recusa evita que uma falha do coletor vire um ticket falso para o time de desenvolvimento.

Conecte o agente ao produto sem acoplar um SDK

A integração pode ficar restrita a HTTP: seu backend emite a credencial, seu app abre a sessão e o runtime transmite a execução por SSE. Assim, o auditor funciona em um SaaS, painel interno ou job assíncrono sem depender de um SDK proprietário.

Faça a integração em três chamadas

Obtenha um runtime token no backend. Associe o token ao tenant e ao usuário final autenticado. Não envie credenciais administrativas ao navegador.
Abra a sessão do auditor. Envie o runtime token e preserve o identificador retornado. Essa sessão mantém o contexto das auditorias daquele usuário.
Envie a solicitação por REST e consuma o stream por SSE. O pedido pode incluir domínio, escopo do crawl e identificador do relatório. Enquanto o pipeline e o agente trabalham, seu app recebe eventos de progresso, chamadas de ferramenta, achados parciais, erros e resposta final.

No frontend, trate o stream como uma sequência de estados, não como texto contínuo:

queued: auditoria recebida;
tool_call: crawler ou serviço interno acionado pelo pipeline ou por uma solicitação adicional autorizada;
tool_result: resultado estruturado disponível;
finding: diagnóstico pronto para exibição;
completed: execução encerrada;
error: falha que exige nova tentativa ou intervenção.

Guarde o run_id desde o primeiro evento. Ele conecta o relatório mostrado ao usuário com a execução registrada no runtime.

Exponha seus serviços como ferramentas REST

O runtime não precisa acessar diretamente seu crawler, banco ou fila. Publique operações específicas como ferramentas REST com autenticação, schema de entrada e resposta estruturada.

| Integração | Operação da ferramenta | Entrada mínima | Saída esperada | |---|---|---|---| | Crawler | iniciar ou consultar um crawl | tenant_id, domínio, limite de URLs | status, páginas processadas, identificador do crawl | | Banco | carregar dados de uma auditoria | tenant_id, identificador do projeto | URLs, respostas HTTP e metadados coletados | | Fila | agendar análise extensa | prioridade, projeto, escopo | identificador do job e estado | | Serviço interno | consultar configuração do site | projeto, ambiente | domínio canônico, sitemap e regras cadastradas |

Prefira ferramentas estreitas. buscar_pagina(url) é mais controlável do que executar_auditoria(payload), porque permite validar cada entrada, registrar cada chamada e identificar onde a execução falhou.

Também separe leitura de escrita. Uma ferramenta que consulta o resultado do crawler não deve alterar o projeto. Se o agente puder criar uma tarefa no backlog, exponha essa ação em outro endpoint e exija campos como finding_id, evidência e severidade.

Isole sessão, memória e histórico por tenant

O identificador do usuário sozinho não basta em um SaaS B2B2C. O mesmo e-mail pode participar de empresas diferentes, e cada empresa precisa manter dados, decisões e relatórios separados.

Use uma chave de escopo composta:

tenant_id + end_user_id + agent_id

Aplique esse escopo a quatro registros:

sessão ativa;
memória do usuário final;
histórico de auditorias;
decisões anteriores, como achados aceitos, ignorados ou reclassificados.

Nunca peça ao modelo para respeitar o isolamento por prompt. O runtime deve aplicar o escopo no servidor antes de carregar memória, Brain, ferramentas ou histórico. Na Catcher Agents, esse isolamento faz parte do runtime multi-tenant, com memória por usuário final e schema dedicado por tenant.

Torne a execução inspecionável

Streaming resolve a experiência do usuário, mas o time técnico precisa reconstruir o que aconteceu depois. Na Catcher Agents, a gente concentra essa trilha no Console: cada run_id permite inspecionar os turnos, as tool calls, os resultados retornados, a latência e o cost_usd da execução.

Isso ajuda a distinguir três falhas diferentes:

coleta incompleta: o crawler não entregou as páginas esperadas;
contrato quebrado: uma ferramenta REST devolveu campos ausentes ou inválidos;
interpretação incorreta: o agente recebeu evidência válida, mas produziu uma explicação incompatível.

Com o runtime REST + SSE, seu produto controla a interface e a autenticação. A Catcher Agents assume o streaming, o escopo multi-tenant e a inspeção operacional das chamadas que produziram cada auditoria.

Teste precisão, custo e latência antes de liberar

Crie um conjunto de casos com resultado esperado

Não valide o auditor apenas em sites reais escolhidos na hora. Monte um conjunto versionado de páginas com falhas conhecidas. Inclua também casos válidos, porque um agente que marca tudo como erro pode ter alta cobertura e baixa utilidade.

Para cada caso, registre:

URL ou snapshot do HTML usado no teste;
falha inserida ou condição válida;
evidência esperada;
diagnóstico esperado;
severidade aceita;
ferramentas que podem ser chamadas;
condições que não devem gerar alerta.

Um conjunto inicial pode combinar casos como estes:

| Caso | Condição preparada | Resultado esperado | |---|---|---| | title_ausente | Página sem <title> | Um achado sobre título ausente, com evidência no HTML | | canonical_divergente | Canonical aponta para outra URL | Achado com a URL declarada e a URL auditada | | status_404 | Recurso retorna erro | Achado associado ao status coletado | | pagina_valida | Metadados e resposta dentro do padrão definido | Nenhum achado | | timeout_coleta | Ferramenta excede o tempo disponível | Estado de falha de ferramenta, sem inventar diagnóstico | | html_incompleto | Coleta retorna conteúdo truncado | Limitação explícita, sem tratar ausência como evidência conclusiva |

Mantenha snapshots quando o conteúdo externo puder mudar. Caso contrário, uma alteração no site pode parecer regressão do agente.

Meça o que muda a decisão de liberar

Execute todos os casos e registre métricas por versão. Não existe uma meta universal de precisão, latência ou custo. Defina os limites conforme o risco do diagnóstico, o budget por execução e o tempo de resposta aceito pelo seu produto.

Acompanhe pelo menos:

Acertos: falhas conhecidas detectadas com a evidência correta.
Falsos positivos: alertas emitidos para condições válidas.
Falhas de ferramenta: timeout, resposta inválida, erro de autenticação ou saída fora do contrato.
Latência: duração total da execução e tempo gasto em cada ferramenta.
Custo por execução: cost_usd total e custo por tipo de caso.
Chamadas desnecessárias: ferramentas repetidas sem mudança de entrada ou sem contribuição para o diagnóstico.
Saídas sem suporte: achados que não apontam a evidência coletada.

Separe os resultados por categoria. Uma média única pode esconder que o auditor funciona em metadados, mas falha em status HTTP ou canonical.

Compare versões sobre os mesmos casos

Crie uma versão identificável para cada combinação de prompt, modelo e ferramentas. Rode todas sobre o mesmo conjunto, com as mesmas entradas e o mesmo limite de execução.

| Versão | Prompt | Modelo | Ferramentas | Acertos | Falsos positivos | Falhas de ferramenta | Latência | cost_usd | |---|---|---|---|---:|---:|---:|---:|---:| | A | prompt_v1 | modelo_1 | tools_v1 | resultado medido | resultado medido | resultado medido | resultado medido | resultado medido | | B | prompt_v2 | modelo_1 | tools_v1 | resultado medido | resultado medido | resultado medido | resultado medido | resultado medido | | C | prompt_v2 | modelo_2 | tools_v1 | resultado medido | resultado medido | resultado medido | resultado medido | resultado medido |

Altere uma variável por comparação sempre que possível. Se você trocar prompt, modelo e contrato das ferramentas ao mesmo tempo, não saberá qual mudança causou a melhora ou a regressão.

Além do resultado agregado, preserve a diferença por caso:

qual achado apareceu ou desapareceu;
qual evidência sustentou a resposta;
quais ferramentas foram acionadas;
quantas chamadas cada ferramenta recebeu;
quanto cada execução custou;
onde a latência aumentou.

Investigue regressões pelo `run_id`

Cada execução de benchmark precisa gerar um run_id. Use esse identificador para reconstruir o turno completo, em vez de comparar apenas a resposta final.

Ao encontrar uma regressão, inspecione:

a entrada recebida pelo pipeline e pelo agente;
a sequência de tool calls;
os argumentos enviados a cada ferramenta;
as respostas retornadas;
tentativas repetidas e erros de contrato;
a evidência e o resultado do validador usados no diagnóstico;
a latência de cada etapa;
o cost_usd acumulado.

Esse rastreamento separa três problemas diferentes: coleta incorreta, pipeline ineficiente e explicação sem suporte. Também revela chamadas desnecessárias, como buscar o mesmo HTML duas vezes ou repetir uma inspeção depois de já obter evidência suficiente.

No Console da Catcher Agents, a gente usa run_id, reconstrução de turnos, tool calls, latência e cost_usd para comparar execuções e localizar esse tipo de desvio. A liberação deve depender de critérios registrados para o seu produto: qualidade mínima por categoria, limite de falsos positivos, comportamento diante de falhas, latência aceitável e budget máximo por execução.

Corrija os pontos que mais travam a operação

Reduza o contexto antes de chamar o modelo

Enviar o HTML completo de cada página aumenta tokens, latência e ruído. Scripts, estilos, SVGs, comentários e dados de hidratação raramente ajudam o agente a explicar um problema de SEO.

Faça a coleta transformar o documento em um payload estruturado:

URL solicitada e URL final;
status da coleta;
título, meta description e canonical;
headings na ordem encontrada;
links internos e externos;
diretivas de indexação;
dados estruturados;
tamanho e tipo do conteúdo;
trechos do DOM relacionados ao achado.

Quando o diagnóstico exigir evidência visual ou estrutural, envie apenas o seletor, o trecho relevante e seu contexto imediato. Mantenha o HTML bruto no armazenamento da execução, não no prompt principal.

Limite crawls, ferramentas e custo por execução

O agente não deve decidir sozinho quantas páginas visitar ou quantas vezes repetir uma ferramenta. Defina limites server-side antes de iniciar o run_id:

número máximo de URLs;
profundidade máxima do crawl;
quantidade de chamadas por ferramenta;
tempo total da execução;
volume máximo de contexto;
budget de custo.

Use cache por URL normalizada, modo de renderização e configuração da coleta. Se duas etapas pedirem o mesmo recurso com os mesmos parâmetros, devolva o resultado armazenado.

Mantenha também uma fila de URLs visitadas. Normalize protocolo, host, barra final, fragmentos e parâmetros conhecidos antes de inserir um novo item. Isso evita loops provocados por calendários, filtros, paginação circular e URLs que apontam umas para as outras.

Na Catcher Agents, o budget limita a execução, enquanto o Console permite inspecionar tool calls, latência e cost_usd. O agente pode priorizar os achados e solicitar uma coleta adicional prevista, mas não deve ampliar o próprio limite.

Transforme falhas de coleta em estados explícitos

Uma página inacessível não equivale a uma página sem conteúdo. O auditor precisa separar ausência real, falha de coleta e evidência inconclusiva.

| Situação | Tratamento operacional | O que o agente pode concluir | |---|---|---| | Conteúdo renderizado por JavaScript | Compare a resposta inicial com a versão renderizada e registre qual modo gerou a evidência | Só explique um diagnóstico validado após a renderização necessária | | Bloqueio de acesso | Registre status, etapa da falha e origem do bloqueio; não repita indefinidamente | Informe que a página não pôde ser verificada | | Loop de URL | Interrompa a expansão ao reencontrar uma URL normalizada ou ultrapassar a profundidade definida | Explique o padrão identificado pelo pipeline e as URLs envolvidas | | Conteúdo duplicado | Calcule uma assinatura do conteúdo normalizado e agrupe páginas equivalentes | Mostre o grupo, a página representativa e as diferenças relevantes | | Resposta incompleta | Valide o retorno contra o schema da ferramenta e marque os campos ausentes | Produza resultado parcial, sem preencher lacunas por inferência |

O retorno de cada ferramenta deve distinguir estados como success, partial, blocked, timeout, invalid_response e cancelled. Um campo vazio sem estado força o modelo a adivinhar se o dado não existe ou se a coleta falhou.

Não trate memória como fotografia atual do site

A memória pode guardar preferências do usuário, escopo recorrente e decisões anteriores. Ela não deve afirmar que uma URL continua com o mesmo título, status ou canonical.

Para cada auditoria, use a coleta atual como fonte de verdade. Associe toda evidência a:

URL verificada;
data e hora da coleta;
modo estático ou renderizado;
status da ferramenta;
trecho ou campo observado;
identificador da execução.

Se a memória disser que um problema existia e o crawl atual não o encontrar, registre a divergência. Não recupere o diagnóstico antigo como se fosse uma observação nova.

Projete a execução para falhar sem perder todo o trabalho

Implemente retry apenas para falhas transitórias. Defina número máximo de tentativas, intervalo progressivo e condições que não admitem repetição. Um bloqueio persistente ou uma resposta inválida não pode consumir todo o budget.

O runtime também precisa oferecer:

cache: reaproveita coletas idênticas dentro da validade definida;
cancelamento: interrompe fila, renderização e tool calls pendentes;
checkpoint: preserva páginas já processadas;
resultado parcial: separa URLs concluídas, ignoradas, bloqueadas e pendentes;
motivo de encerramento: identifica cancelamento, timeout, budget esgotado ou falha de ferramenta.

Ao cancelar uma auditoria, não devolva apenas failed. Entregue os achados já sustentados por evidências e marque o restante como não verificado.

Encaminhe diagnósticos ambíguos para revisão humana

Crie uma fila de revisão quando houver sinais conflitantes, coleta parcial ou interpretação dependente de contexto. Cada item deve trazer a URL, o achado proposto, as evidências, o resultado do validador, as ferramentas usadas e o motivo da ambiguidade.

Exija revisão, por exemplo, quando:

a versão estática e a renderizada apresentam diretivas diferentes;
duas URLs duplicadas apontam sinais conflitantes de consolidação;
o agente não consegue distinguir bloqueio intencional de erro operacional;
a correção sugerida pode alterar renderização, navegação ou indexação de várias páginas;
faltam campos obrigatórios para sustentar o diagnóstico.

Nesses casos, o agente deve responder “revisão necessária”, não completar a explicação com uma hipótese apresentada como fato.

Conclusão

Um auditor de SEO técnico confiável separa fatos, validação e interpretação. O crawler coleta dados determinísticos, os validadores aplicam critérios documentados e o agente prioriza, relaciona e explica as evidências. Se faltar um dado, ele só solicita outra coleta quando uma política explícita autorizar. Essa divisão torna cada diagnóstico reproduzível, testável e útil para quem precisa transformar um achado em correção.

O próximo passo é montar um benchmark com URLs representativas do seu produto, resultados esperados e casos de falha. Execute o agente nesse conjunto, compare falsos positivos e falsos negativos e registre run_id, latência, tool calls e custo por auditoria antes de liberar o acesso aos usuários.

Na Catcher Agents, você pode embutir esse fluxo no seu SaaS por REST + SSE em três chamadas, sem acoplar um SDK proprietário. O Console permite reconstruir cada execução e acompanhar cost_usd, latência e chamadas de ferramentas, enquanto o runtime aplica o budget e as políticas definidas para cada auditoria.