Série Aceleradora TrueFoundry: Desenvolvendo Automação Web Resiliente Quando Não Há APIs

‍

A Lacuna da API

É um cenário familiar às 10h para as equipes de operações: um fluxo de trabalho crítico precisa ser automatizado — verificar o inventário de fornecedores, realizar análises de preços competitivos ou garantir reservas — mas a plataforma de destino não oferece acesso programático.

Embora vivamos em uma era de conectividade, muitas plataformas de alto valor bloqueiam seus dados por trás de "fossos digitais". Elas carecem de APIs públicas, forçando os desenvolvedores a depender do web scraping como alternativa. No entanto, o scraping tradicional é notoriamente frágil. Ele depende de "seletores frágeis" — caminhos CSS ou XPaths codificados (por exemplo, div.btn-primary) que se quebram no momento em que um desenvolvedor frontend muda um nome de classe para btn-submit.

Para resolver isso, construímos o Acelerador de Automação de Reservas de Restaurantes. É uma implementação de referência para uma nova classe de automação: agentes resilientes que não apenas "raspam" a web, mas a operam.

A Transição: De Seletores para Intenção Semântica

A inovação central neste acelerador é o afastamento do Document Object Model (DOM) para o Modelo de Objeto de Acessibilidade (AOM).

Em um script tradicional, se um botão se move de uma barra lateral para um cabeçalho, a automação falha. Neste sistema agêntico, fornecemos ao motor de inferência um instantâneo da Árvore de Acessibilidade. Esta é uma representação semântica da página projetada para leitores de tela, removendo divs de estilo para revelar a utilidade central da interface.

Isso permite que o sistema raciocine com base na intenção, e não nas coordenadas: Vejo um widget de calendário; clicarei na data '15' porque isso corresponde à solicitação do usuário. Se o site passar por uma reformulação, mas o papel semântico do botão permanecer "Confirmar Reserva", o agente se auto-repara e o fluxo de trabalho é bem-sucedido.

Arquitetura: O Padrão Controlador-Trabalhador

Estruturamos a aplicação usando um Controlador/Trabalhador padrão. Em vez de um script monolítico, temos agentes distintos utilizando Playwright para execução e LLMs para tomada de decisões.

Figura 1: Arquitetura de Alto Nível

Conforme mostrado no diagrama de arquitetura, o Controlador de Fluxo de Trabalho gerencia o estado, delegando tarefas a dois componentes especializados:

1. O Agente de Busca (Descoberta): Este agente gerencia a fase não linear de "compras".
   
   • Construção Dinâmica de URL: Em vez de clicar em cinco páginas de destino, ele constrói parâmetros de consulta (por exemplo, ?cuisine=italian&party_size=4) para navegar diretamente aos resultados.
   • Extração Contextual: Ele identifica "cartões" na interface do usuário para extrair classificações, preços e horários sem a necessidade de tags HTML específicas.
   • Navegação Adaptativa: Ele trata pop-ups e banners de cookies como "obstáculos" a serem ignorados, em vez de erros que travam o script.
2. O Agente de Reserva (Transação): Uma vez selecionado um alvo, este agente lida com a interação com estado e de alta precisão.
   
   • Mapeamento Semântico de Formulários: Mapeia dados do usuário para campos de entrada com base em rótulos (Primeiro Nome), em vez de IDs arbitrários (input#user_fname).
   • Raciocínio Temporal: Navega por seletores de horário e lida com estados de "esgotado", sendo capaz de aplicar lógica como selecionar um horário das 19:15 se o solicitado das 19:00 estiver indisponível.

Infraestrutura: TrueFoundry & O Protocolo de Contexto de Modelo (MCP)

A execução desses agentes em produção requer um plano de controle robusto. Utilizamos a Plataforma TrueFoundry para gerenciar a infraestrutura e o Protocolo de Contexto de Modelo (MCP) para padronizar a integração do navegador.

Figura 2: Como a TrueFoundry suporta o ciclo de vida da aplicação

• TrueFoundry AI Gateway: Isso fornece o gerenciamento unificado e a observabilidade necessários. Podemos monitorar centralizadamente cada "pensamento" que o agente tem, registrando snapshots AOM e árvores de decisão. Fundamentalmente, ele impõe limitação de taxa, garantindo que nossos agentes atuem como bons cidadãos e não sobrecarreguem os servidores de destino.
• MCP e Isolamento: O MCP abstrai as capacidades do navegador em ferramentas padronizadas. A plataforma garante que cada sessão de usuário seja executada em um contêiner isolado. Isso significa que os cookies de sessão e o armazenamento local do Usuário A são fisicamente separados dos do Usuário B, eliminando o risco de contaminação cruzada de dados.

Experiência do Usuário: Autonomia Supervisionada

Para fluxos de trabalho transacionais, implementamos um padrão "Verificar-e-Executar" . O agente realiza o trabalho pesado de descoberta, mas requer confirmação humana antes da execução final.

Passo 1: Intenção e Descoberta

O sistema aceita entradas em linguagem natural e as normaliza em JSON estruturado (Localização, Hora, Tamanho do Grupo) para o Agente de Busca.

Passo 2: O Portão de Confirmação

Ao encontrar um horário disponível, o Agente de Reserva pausa. Ele apresenta os detalhes ao usuário e entra em um estado de ESPERA, prosseguindo apenas após receber um sinal claro.

Engenharia para Casos Limite: O Problema do WAF

O teste mais crítico para um agente web é a sua capacidade de lidar com cenários de "Human-in-the-Loop" (HITL). Sites modernos frequentemente utilizam Web Application Firewalls (WAFs) que acionam CAPTCHAs ou códigos de verificação por e-mail quando detectam automação.

Um script padrão falha aqui. Nosso sistema utiliza um Máquina de Estados de Pausa e Retomada.

Figura 3: Lógica de Estado para Tratamento de Exceções

Conforme detalhado no diagrama acima (Passos 7-11), quando o agente detecta um prompt de desafio:

1. Ele interrompe a execução e notifica o usuário através da interface de chat.
2. A sessão do navegador permanece ativa (mantida dentro do TTL do contêiner).
3. Assim que o usuário fornece o código, o agente retoma a sessão de forma contínua para concluir a reserva.

Conclusão: Operação Web

Estamos migrando de "Web Scraping" para "Web Operating". Ao utilizar o Playwright como as "mãos" e a inferência semântica para os "olhos", podemos tratar a web voltada para humanos como uma interface programática.

Este acelerador demonstra que com a arquitetura certa — interpretação semântica, orquestração com estado e infraestrutura segura como TrueFoundry— podemos construir automações resilientes que preenchem a lacuna da API.

Explore os Aceleradores TrueFoundry