Automação de Navegador com agent-browser

O que Automação de Navegador com agent-browser faz?

Fluxo de Trabalho Principal

Toda automação de navegador segue este padrão:

1. Navegar: agent-browser open <url>
2. Instantâneo: agent-browser snapshot -i (obter referências de elementos como @e1, @e2)
3. Interagir: Usar as referências para clicar, preencher, selecionar
4. Novo Instantâneo: Após navegação ou mudanças no DOM, obter novas referências

agent-browser open https://example.com/form
agent-browser snapshot -i
# Saída: @e1 [input type="email"], @e2 [input type="password"], @e3 [button] "Submit"

agent-browser fill @e1 "[email protected]"
agent-browser fill @e2 "password123"
agent-browser click @e3
agent-browser wait --load networkidle
agent-browser snapshot -i  # Verificar resultado

Encadeamento de Comandos

Comandos podem ser encadeados com && em uma única invocação do shell. O navegador persiste entre os comandos através de um daemon em segundo plano, então o encadeamento é seguro e mais eficiente do que chamadas separadas.

# Encadear open + wait + snapshot em uma chamada
agent-browser open https://example.com && agent-browser wait --load networkidle && agent-browser snapshot -i

# Encadear múltiplas interações
agent-browser fill @e1 "[email protected]" && agent-browser fill @e2 "password123" && agent-browser click @e3

# Navegar e capturar
agent-browser open https://example.com && agent-browser wait --load networkidle && agent-browser screenshot page.png

Quando encadear: Use && quando você não precisa ler a saída de um comando intermediário antes de prosseguir (ex.: open + wait + screenshot). Execute comandos separadamente quando precisar analisar a saída primeiro (ex.: instantâneo para descobrir referências, depois interagir usando essas referências).

Comandos Essenciais

# Navegação
agent-browser open <url>              # Navegar (aliases: goto, navigate)
agent-browser close                   # Fechar navegador

# Instantâneo (Snapshot)
agent-browser snapshot -i             # Elementos interativos com referências (recomendado)
agent-browser snapshot -i -C          # Incluir elementos interativos com cursor (divs com onclick, cursor:pointer)
agent-browser snapshot -s "#selector" # Escopo para um seletor CSS

# Interação (use @refs do instantâneo)
agent-browser click @e1               # Clicar no elemento
agent-browser click @e1 --new-tab     # Clicar e abrir em nova aba
agent-browser fill @e2 "texto"        # Limpar e digitar texto
agent-browser type @e2 "texto"        # Digitar sem limpar
agent-browser select @e1 "opção"      # Selecionar opção de dropdown
agent-browser check @e1               # Marcar checkbox
agent-browser press Enter             # Pressionar tecla
agent-browser scroll down 500         # Rolar página

# Obter informações
agent-browser get text @e1            # Obter texto do elemento
agent-browser get url                 # Obter URL atual
agent-browser get title               # Obter título da página

# Esperar (Wait)
agent-browser wait @e1                # Esperar por elemento
agent-browser wait --load networkidle # Esperar por rede ociosa
agent-browser wait --url "**/pagina"  # Esperar por padrão de URL
agent-browser wait 2000               # Esperar milissegundos

# Captura
agent-browser screenshot              # Screenshot para diretório temporário
agent-browser screenshot --full       # Screenshot da página inteira
agent-browser screenshot --annotate   # Screenshot anotado com rótulos numerados nos elementos
agent-browser pdf output.pdf          # Salvar como PDF

# Comparação (Diffing)
agent-browser diff snapshot                          # Comparar atual com último instantâneo
agent-browser diff snapshot --baseline before.txt    # Comparar atual com arquivo salvo
agent-browser diff screenshot --baseline before.png  # Diferença visual de pixels
agent-browser diff url <url1> <url2>                 # Comparar duas páginas
agent-browser diff url <url1> <url2> --wait-until networkidle  # Estratégia de espera personalizada
agent-browser diff url <url1> <url2> --selector "#main"  # Escopo para um elemento

Padrões Comuns

Envio de Formulário

agent-browser open https://example.com/cadastro
agent-browser snapshot -i
agent-browser fill @e1 "Maria Silva"
agent-browser fill @e2 "[email protected]"
agent-browser select @e3 "São Paulo"
agent-browser check @e4
agent-browser click @e5
agent-browser wait --load networkidle

Autenticação com Persistência de Estado

# Fazer login uma vez e salvar o estado
agent-browser open https://app.example.com/login
agent-browser snapshot -i
agent-browser fill @e1 "$USUARIO"
agent-browser fill @e2 "$SENHA"
agent-browser click @e3
agent-browser wait --url "**/dashboard"
agent-browser state save auth.json

# Reutilizar em sessões futuras
agent-browser state load auth.json
agent-browser open https://app.example.com/dashboard

Persistência de Sessão

# Salvar/restaurar cookies e localStorage automaticamente entre reinícios do navegador
agent-browser --session-name minhaapp open https://app.example.com/login
# ... fluxo de login ...
agent-browser close  # Estado salvo automaticamente em ~/.agent-browser/sessions/

# Da próxima vez, o estado é carregado automaticamente
agent-browser --session-name minhaapp open https://app.example.com/dashboard

# Criptografar estado em repouso
export AGENT_BROWSER_ENCRYPTION_KEY=$(openssl rand -hex 32)
agent-browser --session-name segura open https://app.example.com

# Gerenciar estados salvos
agent-browser state list
agent-browser state show minhaapp-default.json
agent-browser state clear minhaapp
agent-browser state clean --older-than 7

Extração de Dados

agent-browser open https://example.com/produtos
agent-browser snapshot -i
agent-browser get text @e5           # Obter texto de elemento específico
agent-browser get text body > pagina.txt  # Obter texto de toda a página

# Saída JSON para análise
agent-browser snapshot -i --json
agent-browser get text @e1 --json

Sessões Paralelas

agent-browser --session site1 open https://site-a.com
agent-browser --session site2 open https://site-b.com

agent-browser --session site1 snapshot -i
agent-browser --session site2 snapshot -i

agent-browser session list

Conectar ao Chrome Existente

# Descobrir automaticamente o Chrome em execução com depuração remota habilitada
agent-browser --auto-connect open https://example.com
agent-browser --auto-connect snapshot

# Ou com porta CDP explícita
agent-browser --cdp 9222 snapshot

Navegador Visual (Depuração)

agent-browser --headed open https://example.com
agent-browser highlight @e1          # Destacar elemento
agent-browser record start demo.webm # Gravar sessão
agent-browser profiler start         # Iniciar perfil do Chrome DevTools
agent-browser profiler stop trace.json # Parar e salvar perfil (caminho opcional)

Arquivos Locais (PDFs, HTML)

# Abrir arquivos locais com URLs file://
agent-browser --allow-file-access open file:///caminho/para/documento.pdf
agent-browser --allow-file-access open file:///caminho/para/pagina.html
agent-browser screenshot output.png

Simulador iOS (Safari Móvel)

# Listar simuladores iOS disponíveis
agent-browser device list

# Iniciar Safari em um dispositivo específico
agent-browser -p ios --device "iPhone 16 Pro" open https://example.com

# Mesmo fluxo de trabalho que no desktop - instantâneo, interagir, novo instantâneo
agent-browser -p ios snapshot -i
agent-browser -p ios tap @e1          # Toque (alias para click)
agent-browser -p ios fill @e2 "texto"
agent-browser -p ios swipe up         # Gesto específico para dispositivos móveis

# Tirar screenshot
agent-browser -p ios screenshot mobile.png

# Fechar sessão (desliga o simulador)
agent-browser -p ios close

Requisitos: macOS com Xcode, Appium (npm install -g appium && appium driver install xcuitest)

Dispositivos reais: Funciona com dispositivos iOS físicos se pré-configurados. Use --device "<UDID>" onde UDID é obtido de xcrun xctrace list devices.

Comparação (Diffing) - Verificando Mudanças

Use diff snapshot após realizar uma ação para verificar se ela teve o efeito desejado. Isso compara a árvore de acessibilidade atual com o último instantâneo tirado na sessão.

# Fluxo de trabalho típico: instantâneo -> ação -> diff
agent-browser snapshot -i          # Tirar instantâneo de referência
agent-browser click @e2            # Realizar ação
agent-browser diff snapshot        # Ver o que mudou (compara automaticamente com o último instantâneo)

Para testes de regressão visual ou monitoramento:

# Salvar um screenshot de referência e comparar depois
agent-browser screenshot baseline.png
# ... tempo passa ou mudanças são feitas ...
agent-browser diff screenshot --baseline baseline.png

# Comparar staging vs produção
agent-browser diff url https://staging.example.com https://prod.example.com --screenshot

A saída de diff snapshot usa + para adições e - para remoções, semelhante ao git diff. diff screenshot produz uma imagem de diff com pixels alterados destacados em vermelho, além de uma porcentagem de diferença.

Timeouts e Páginas Lentas

O timeout padrão do Playwright é de 60 segundos para navegadores locais. Para sites lentos ou páginas grandes, use esperas explícitas em vez de depender do timeout padrão:

# Esperar a atividade de rede se acalmar (melhor para páginas lentas)
agent-browser wait --load networkidle

# Esperar um elemento específico aparecer
agent-browser wait "#content"
agent-browser wait @e1

# Esperar um padrão de URL específico (útil após redirecionamentos)
agent-browser wait --url "**/dashboard"

# Esperar uma condição JavaScript
agent-browser wait --fn "document.readyState === 'complete'"

# Esperar uma duração fixa (milissegundos) como último recurso
agent-browser wait 5000

Ao lidar com sites consistentemente lentos, use wait --load networkidle após open para garantir que a página esteja totalmente carregada antes de tirar um instantâneo. Se um elemento específico estiver lento para renderizar, espere por ele diretamente com wait <selector> ou wait @ref.

Gerenciamento e Limpeza de Sessão

Ao executar vários agentes ou automações simultaneamente, sempre use sessões nomeadas para evitar conflitos:

# Cada agente obtém sua própria sessão isolada
agent-browser --session agente1 open site-a.com
agent-browser --session agente2 open site-b.com

# Verificar sessões ativas
agent-browser session list

Sempre feche sua sessão do navegador quando terminar para evitar processos vazados:

agent-browser close                    # Fechar sessão padrão
agent-browser --session agente1 close   # Fechar sessão específica

Se uma sessão anterior não foi fechada corretamente, o daemon ainda pode estar em execução. Use agent-browser close para limpá-lo antes de iniciar um novo trabalho.

Ciclo de Vida das Referências (Importante)

As referências (@e1, @e2, etc.) são invalidadas quando a página muda. Sempre tire um novo instantâneo após:

• Clicar em links ou botões que navegam
• Envio de formulários
• Carregamento de conteúdo dinâmico (dropdowns, modais)

agent-browser click @e5              # Navega para nova página
agent-browser snapshot -i            # DEVE tirar novo instantâneo
agent-browser click @e1              # Usar novas referências

Screenshots Anotados (Modo Visão)

Use --annotate para tirar um screenshot com rótulos numerados sobrepostos nos elementos interativos. Cada rótulo [N] mapeia para a referência @eN. Isso também armazena em cache as referências, permitindo que você interaja com os elementos imediatamente sem um instantâneo separado.

agent-browser screenshot --annotate
# A saída inclui o caminho da imagem e uma legenda:
#   [1] @e1 button "Enviar"
#   [2] @e2 link "Início"
#   [3] @e3 textbox "Email"
agent-browser click @e2              # Clicar usando referência do screenshot anotado

Use screenshots anotados quando:

• A página tem botões de ícone sem rótulo ou elementos puramente visuais
• Você precisa verificar layout visual ou estilo
• Elementos canvas ou gráficos estão presentes (invisíveis em instantâneos de texto)
• Você precisa de raciocínio espacial sobre posições de elementos

Localizadores Semânticos (Alternativa às Referências)

Quando as referências não estão disponíveis ou são confiáveis, use localizadores semânticos:

agent-browser find text "Entrar" click
agent-browser find label "Email" fill "[email protected]"
agent-browser find role button click --name "Enviar"
agent-browser find placeholder "Pesquisar" type "consulta"
agent-browser find testid "btn-enviar" click

Avaliação de JavaScript (eval)

Use eval para executar JavaScript no contexto do navegador. A citação do shell pode corromper expressões complexas -- use --stdin ou -b para evitar problemas.

# Expressões simples funcionam com citação regular
agent-browser eval 'document.title'
agent-browser eval 'document.querySelectorAll("img").length'

# JS complexo: use --stdin com heredoc (RECOMENDADO)
agent-browser eval --stdin <<'EVALEOF'
JSON.stringify(
  Array.from(document.querySelectorAll("img"))
    .filter(i => !i.alt)
    .map(i => ({ src: i.src.split("/").pop(), width: i.width }))
)
EVALEOF

# Alternativa: codificação base64 (evita todos os problemas de escape do shell)
agent-browser eval -b "$(echo -n 'Array.from(document.querySelectorAll("a")).map(a => a.href)' | base64)"

Por que isso importa: Quando o shell processa seu comando, aspas duplas internas, caracteres ! (expansão de histórico), crases e $() podem corromper o JavaScript antes de chegar ao agent-browser. As flags --stdin e -b ignoram completamente a interpretação do shell.

Regras práticas:

• Linha única, sem aspas aninhadas -> eval 'expression' regular com aspas simples é suficiente
• Aspas aninhadas, arrow functions, template literals ou multilinha -> use eval --stdin <<'EVALEOF'
• Scripts programáticos/gerados -> use eval -b com base64

Arquivo de Configuração

Crie agent-browser.json na raiz do projeto para configurações persistentes:

{
  "headed": true,
  "proxy": "http://localhost:8080",
  "profile": "./browser-data"
}

Prioridade (da menor para a maior): ~/.agent-browser/config.json < ./agent-browser.json < variáveis de ambiente < flags de CLI. Use --config <caminho> ou a variável de ambiente AGENT_BROWSER_CONFIG para um arquivo de configuração personalizado (sai com erro se estiver faltando ou for inválido). Todas as opções de CLI mapeiam para chaves camelCase (ex.: --executable-path -> "executablePath"). Flags booleanas aceitam valores true/false (ex.: --headed false substitui a configuração). Extensões de configurações de usuário e projeto são mescladas, não substituídas.

Documentação Aprofundada

Referência	Quando Usar
references/commands.md	Referência completa de comandos com todas as opções
references/configuration.md	Opções de configuração, perfis e variáveis de ambiente
references/sessions.md	Gerenciamento de sessões, estado e criptografia
references/diffing.md	Referência detalhada de diffing para testes visuais e estruturais
references/ios-simulator.md	Automação de Safari móvel com simulador iOS
references/semantic-locators.md	Estratégias de localização baseadas em texto, papel e atributos

Boas Práticas

1. Prefira instantâneos de texto quando possível - são mais rápidos e fornecem referências estruturadas
2. Use screenshots anotados para páginas complexas e com muitos elementos visuais
3. Sempre feche suas sessões de navegador quando terminar
4. Use sessões nomeadas para múltiplos agentes ou automações concorrentes
5. Encadeie comandos para tarefas simples, execute separadamente quando precisar analisar saídas
6. Use wait --load networkidle para páginas lentas em vez de aumentar timeouts
7. Sempre tire novo instantâneo após navegação ou mudanças no DOM
8. Prefira eval --stdin ou -b para expressões JavaScript complexas