Agentes de IA em formulários paginados

Formulários paginados não têm memória entre etapas. Veja como usar mapa de campos, checkpoints e identificadores estáveis para o agente não perder o que já preencheu.

Formulários longos divididos em etapas quebram a maioria dos agentes de IA porque cada página é um documento independente: o navegador não guarda nada do que foi digitado até você clicar em “Continuar”, e o servidor só devolve a próxima tela. Um agente que opera navegador precisa anotar o que já preencheu, onde parou e o que ainda falta, para não recomeçar do zero quando algo dá errado na terceira de dez etapas.

A solução prática combina quatro hábitos: mapear o formulário inteiro antes de começar, salvar um checkpoint a cada etapa, verificar depois de cada avanço que as respostas anteriores sobreviveram e usar identificadores estáveis em vez de posição na tela. Quando a etapa envolve upload de arquivo, captcha ou validação que devolve o usuário para trás, o agente precisa de um plano explícito.

Resumo rápido

Cada página de um formulário paginado é independente: o estado só existe no servidor depois do envio, e isso derruba agentes que não guardam nada.

Mapeie o formulário inteiro antes de preencher: nome do campo, tipo, obrigatoriedade e valor esperado.

Salve um checkpoint a cada etapa e valide, após avançar, que os campos anteriores continuaram preenchidos.

Ancore o agente em labels e atributos name estáveis, nunca em posição na tela ou índice do seletor.

Upload de arquivo e captcha viram pontos de parada para humano, não obstáculos a driblar.

Se existe API ou importação em lote, ela costuma ser mais robusta e barata que operar o navegador.

O problema: a página não guarda nada até você enviar

Um formulário paginado não é uma página longa escondida atrás de abas. São telas separadas, servidas por requisições separadas. Quando o agente preenche um campo, aquele valor existe apenas dentro do DOM do navegador, como estado local. Nada foi enviado ao servidor. Se o agente navegar embora, a página recarregar ou a sessão expirar, o valor se perde.

Isso confunde quem está começando: preencher parece ter dado certo, porque o campo mostra o texto e o botão “Continuar” fica habilitado. Mas o sucesso só é real depois do envio da etapa, o único momento em que o servidor toma conhecimento do que foi digitado.

O que sobrevive e o que não sobrevive

Nem tudo se perde igualmente. Vale distinguir três camadas:

Estado na página: o que está digitado agora, no DOM. Some ao navegar, recarregar ou fechar.
Estado no servidor: o que foi aceito no último envio de etapa. Sobrevive a recarregamentos, desde que a sessão continue válida.
Estado no agente: o que o próprio agente anotou do lado dele. É a única camada que ele controla totalmente.

Um agente frágil confia em todas as três sem clareza de qual é qual. Um agente robusto trata a terceira como fonte da verdade e usa a segunda para conferir.

Por que agentes que operam navegador quebram nisso

Agentes que controlam navegador decidem a cada passo a partir do que veem na tela. Funciona bem em páginas únicas e mal em fluxos paginados, por uma combinação de motivos.

O histórico do agente não é o estado do formulário

O modelo lembra do histórico da conversa, não do formulário. Se o agente “acha” que preencheu o CPF porque registrou isso três passos atrás, ele segue adiante. Mas a página atual não tem esse CPF: o que importa é se a etapa anterior foi aceita pelo servidor.

Cada recarregamento é uma tela nova

Ao avançar, o DOM é substituído e referências de elementos capturadas antes deixam de valer. Um agente que guarda “o terceiro campo da página” perde o fio quando a nova página tem outra quantidade de campos ou muda a ordem.

Erros silenciosos de validação

Quando uma etapa tem um campo mal preenchido, o servidor pode devolver a mesma página com mensagem de erro e o restante em branco. O agente, que esperava a etapa seguinte, vê uma tela parecida com a que acabou de enviar e pode reenviar os mesmos dados ou perder o que já tinha.

Sessão, timeout e expiração

Formulários longos costumam ter sessões com prazo. Um agente que demora porque o modelo pensa a cada passo pode chegar à etapa oito e descobrir que a sessão expirou, com tudo perdido. Vale também para cookies que expiram ou tokens de CSRF relidos em cada página.

Passo 1: mapear o formulário antes de preencher

A primeira ação não é preencher nada. É percorrer o formulário e produzir um mapa: o contrato entre você e o agente, que descreve o que existe, em que ordem e com quais regras.

Para cada campo, registre o rótulo, o atributo name (ou outro identificador estável), o tipo do controle e se é obrigatório. Registre também o valor esperado, porque isso permite checar depois se o servidor aceitou o que foi combinado.

Etapa	Campo (rótulo)	name	Tipo	Obrigatório	Valor esperado
1	Nome completo	nome	texto	sim	Nome do solicitante
1	CPF	cpf	texto mascarado	sim	11 dígitos, sem pontos
2	Endereço	endereco	texto	sim	Rua, número, bairro
2	CEP	cep	texto	sim	8 dígitos
3	Comprovante	arquivo	upload	sim	PDF de 1 página
4	Termos de uso	aceite	checkbox	sim	marcado

O mapa tem um valor extra: ele permite calcular quantas etapas faltam e detectar quando o formulário mudou. Se o agente encontra um campo obrigatório que não está no mapa, é sinal de que a versão do formulário é diferente da que foi mapeada, e o certo é parar em vez de adivinhar.

Passo 2: checkpoints e retomada

Depois de cada etapa aceita, o agente deve gravar um checkpoint: um registro persistente, fora do navegador, com o identificador da execução, a última etapa aceita, os valores exatos enviados, a evidência de que o servidor aceitou (como a chegada da etapa seguinte) e o carimbo de tempo com o estado da sessão.

Com isso, uma falha na etapa cinco não obriga a refazer as quatro anteriores. O agente lê o último checkpoint, verifica se a sessão ainda é válida e retoma do ponto certo. Se a sessão morreu, ele precisa relogar e reconsiderar a etapa em andamento.

Um cuidado importante: gravar o checkpoint antes de confirmar o avanço é erro sutil. Se o agente anota a etapa três como concluída só porque preencheu os campos, e o envio falha, o checkpoint mente. O registro só deve ser gravado depois da confirmação da etapa seguinte.

Passo 3: validar o avanço a cada etapa

O checkpoint diz o que o agente acha que aconteceu; a validação diz o que de fato aconteceu. Uma rotina simples funciona em três verificações: confirmar que a etapa avançou (o título da nova página corresponde ao esperado no mapa, ou a URL mudou); reler os campos anteriores, comparando com o checkpoint se a nova etapa mostra um resumo; e procurar sinais de erro, como mensagens de validação, campos em vermelho ou aviso de sessão expirada. Registre o resultado de cada validação no log, com a etapa e o resultado, para auditoria posterior.

Passo 4: quando a validação devolve para trás

Nem todo envio avança. Um erro na etapa quatro pode devolver o usuário para a etapa dois, com mensagem indicando o campo problemático, e o agente precisa reconhecer isso em vez de tratar como página nova. São três movimentos: identificar que a página corresponde a uma etapa anterior (já é possível com o mapa); ler a mensagem de erro e associá-la a um campo específico, não ao formulário inteiro; e atualizar o checkpoint, porque a etapa anterior não está mais concluída.

Quando o retorno se repete muitas vezes, é sinal de problema sistemático: o dado pode não passar na validação do servidor, pode existir regra de negócio desconhecida ou o mapa pode estar incompleto. Nesse ponto, o agente deve parar e escalar para um humano, com padrões como os descritos no guia de human in the loop em agentes de IA.

Passo 5: identificadores estáveis, não posição na tela

A maior fonte de fragilidade em agentes de navegador é a localização de elementos. “Clicar no terceiro campo desta página” funciona até a página mudar. “Preencher o campo com name="cpf"” funciona enquanto o formulário for o mesmo.

Estratégia	Como funciona	Robustez	Quando quebra
Posição na tela	Clica no n-ésimo elemento ou em coordenadas X/Y	Muito baixa	Qualquer mudança de layout, campo novo, tela menor
Índice do seletor	Pega o 3º input da página	Baixa	Campo adicionado, removido ou reordenado
Rótulo do campo	Encontra o input pelo texto do label visível	Boa	Mudança de redação do rótulo ou idioma
Atributo name / id estável	Incorpora o `name`, `id` ou `data-*` do campo	Alta	Raramente, quase só em refatoração do formulário

Combine as duas estratégias razoáveis: use o atributo estável como âncora principal e o rótulo visível como confirmação. Se as duas concordarem, o agente preenche; se divergirem, algo mudou, e o certo é parar e registrar a divergência. O Playwright documenta estratégias de localização por rótulo, papel e atributos de teste que servem bem a esse propósito. O guia sobre memória em agentes de IA explica como essa anotação persistente se encaixa no desenho geral do agente.

Upload de arquivo e captcha

Upload de arquivo

O campo de arquivo é alimentado por um caminho local, não por texto digitado. Se o agente operar em máquina diferente da que contém o arquivo, o caminho não existe. Além disso, o envio pode ser assíncrono: a página mostra “enviando” e só depois considera o arquivo anexado, então um agente que avança imediatamente envia a etapa com o arquivo ainda em trânsito. Coloque o arquivo em um caminho acessível ao processo, aguarde o indicador de conclusão e confirme que o nome aparece na página antes de continuar.

Captcha

Captcha é sinal de que o formulário quer confirmar presença humana, e tentar resolvê-lo sozinho é exatamente o que o captcha existe para impedir. O comportamento aceitável é parar, avisar o humano e aguardar; depois da resolução, o agente retoma a partir do checkpoint. Essa parada não é falha: é uma etapa de aprovação humana.

Quando não usar agente de navegador

Antes de construir um agente que clica em formulário, verifique se há alternativa programática. Se o sistema aceita API, enviar por ela dispensa o navegador e deixa tudo em requisições auditáveis. Se existe importação em lote, planilhas ou arquivos CSV são o caminho preferido em volume alto. Se o formulário é seu, um endpoint próprio é mais simples que um agente navegando pelo próprio site. E se o formulário muda com frequência, cada mudança de layout vira um quebra-cabeça, enquanto a API mantém o contrato.

Agente de navegador faz sentido quando o sistema não oferece API, quando a autenticação é interativa ou quando a tarefa é pontual e de baixo volume.

Comparando as abordagens

Abordagem	Robustez	Custo	Facilidade de auditoria
Agente de navegador	Baixa a média: sensível a mudanças de layout, sessão e timing	Variável, com chamadas de modelo a cada passo	Média: exige logs de cada ação e captura de tela
RPA / automação clássica	Média: estável para fluxos fixos, quebra com mudanças de interface	Menor por execução, com custo de manutenção	Alta: cada passo é explícito e reproduzível
API / importação em lote	Alta: contrato estável, erros retornados de forma estruturada	Mais baixo, sem custo por passo de modelo	Alta: requisições e respostas registradas

A leitura da tabela não é que uma abordagem é sempre melhor. É que o agente de navegador é a opção de maior fragilidade, justificada só quando não há alternativa programática. Modelos como o GPT, da OpenAI, expõem function calling, que permite ao agente chamar APIs em vez de clicar em telas, como explorado no guia da integração com o OpenAI ChatGPT.

Exemplo: transportadora de médio porte em Goiânia

Considere uma transportadora de médio porte em Goiânia que cadastra motoristas parceiros em um portal de terceiro. O formulário tem cinco etapas: dados pessoais, endereço, documentos, veículo e aceite dos termos. Os dados chegam por e-mail e por planilha, e alguém da operação os redigita no portal todos os dias.

Um agente bem desenhado para esse caso leria primeiro o mapa das cinco etapas, com os name de cada campo. Preencheria a etapa um e confirmaria a chegada da etapa dois. Se o portal devolvesse a etapa um com mensagem de CPF inválido, o agente não recomeçaria tudo: leria a mensagem, corrigiria o campo, reenviaria e atualizaria o checkpoint. Na etapa três, com upload da CNH, colocaria o arquivo em uma pasta acessível, aguardaria a confirmação e só então avançaria. Se aparecesse captcha, pararia e chamaria a pessoa da operação.

Ao final, sobraria um registro por cadastro: etapas concluídas, dados enviados e intervenções humanas necessárias. Como o processo envolve documentos pessoais, a operação precisa observar a LGPD, com base legal definida e permissões mínimas, o que vale também para o acesso do agente ao portal.

Erros comuns

Preencher antes de mapear. Sem mapa, o agente não sabe o que esperar na etapa seguinte nem distingue avanço de erro.
Guardar o estado só no histórico do modelo. O estado precisa estar em um checkpoint persistente, fora do navegador.
Gravar checkpoint antes da confirmação. Registrar a etapa como concluída antes do envio ser aceito faz o agente retomar de um ponto falso.
Localizar campos por posição ou coordenadas. A primeira mudança de layout derruba o agente.
Ignorar a mensagem de validação. Marcar a página inteira como inválida e reenviar tudo apaga a chance de corrigir só o campo com problema.
Tentar resolver captcha sozinho. Além de ser o que o captcha existe para impedir, expõe a operação a bloqueio.
Construir agente de navegador onde existe API. Trocar um contrato estável por cliques em tela é escolher a opção de maior manutenção.

Perguntas frequentes

Por que o agente perde os dados ao mudar de página?

Porque cada página é independente e o valor digitado fica apenas no navegador até o envio da etapa. O servidor só conhece os dados depois que aquela etapa é aceita.

Preciso de um checkpoint a cada etapa, ou basta um no meio?

O ideal é um por etapa concluída. Checkpoints menos frequentes obrigam a refazer mais trabalho quando algo falha, e refazer significa redigitar dados que já estavam certos.

Como o agente deve tratar a mensagem de erro que o devolve para uma etapa anterior?

Ele deve reconhecer a página como etapa anterior pelo mapa, ler a mensagem e associá-la ao campo específico, corrigir e reenviar. Se o retorno se repetir muitas vezes, o certo é parar e escalar para um humano.

E quando aparece captcha?

O agente deve parar e pedir intervenção humana. Captcha existe para confirmar presença humana, e tentar resolvê-lo automaticamente é o comportamento que se quer evitar.

Quando vale mais a pena usar API em vez de agente de navegador?

Sempre que a API existir e entregar os mesmos campos. Ela remove a fragilidade de layout e de timing, custa menos por execução e deixa cada requisição auditável. O navegador fica para os casos em que não há alternativa programática.

Como testar um agente desses antes de colocar em produção?

Rode com formulários de teste que reproduzam cada etapa, incluindo erros de validação, sessão expirada e upload. Meça quantas vezes o agente retoma de checkpoint e quantas para para intervenção humana. O guia de como testar agente de IA detalha o conjunto mínimo de casos.

Agentes de IA em formulários paginados: como manter o contexto entre etapas