Automação de Navegador com agent-browser
A CLI usa Chrome/Chromium via CDP diretamente. Instale com npm i -g agent-browser, brew install agent-browser ou cargo install agent-browser. Execute agent-browser install para baixar o Chrome. Execute agent-browser upgrade para atualizar para a versão mais recente.
Fluxo de Trabalho Principal
Toda automação de navegador segue este padrão:
- Navegar:
agent-browser open <url> - Snapshot:
agent-browser snapshot -i(obter referências de elementos como@e1,@e2) - Interagir: Usar referências para clicar, preencher, selecionar
- Re-snapshot: Após navegação ou alterações 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 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 precisar 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.: snapshot para descobrir referências, depois interagir usando essas referências).
Tratamento de Autenticação
Ao automatizar um site que exige login, escolha a abordagem que se encaixa:
Opção 1: Importar autenticação do navegador do usuário (mais rápido para tarefas pontuais)
# Conectar ao Chrome em execução do usuário (já logado)
agent-browser --auto-connect state save ./auth.json
# Usar o estado de autenticação
agent-browser --state ./auth.json open https://app.example.com/dashboard
Arquivos de estado contêm tokens de sessão em texto simples — adicione ao .gitignore e exclua quando não for mais necessário. Defina AGENT_BROWSER_ENCRYPTION_KEY para criptografia em repouso.
Opção 2: Perfil persistente (mais simples para tarefas recorrentes)
# Primeira execução: login manual ou automatizado
agent-browser --profile ~/.myapp open https://app.example.com/login
# ... preencher credenciais, enviar ...
# Todas as execuções futuras: já autenticado
agent-browser --profile ~/.myapp open https://app.example.com/dashboard
Opção 3: Nome de sessão (salvar/restaurar cookies + localStorage automaticamente)
agent-browser --session-name myapp open https://app.example.com/login
# ... fluxo de login ...
agent-browser close # Estado salvo automaticamente
# Próxima vez: estado restaurado automaticamente
agent-browser --session-name myapp open https://app.example.com/dashboard
Opção 4: Cofre de autenticação (credenciais armazenadas criptografadas, login por nome)
echo "$PASSWORD" | agent-browser auth save myapp --url https://app.example.com/login --username user --password-stdin
agent-browser auth login myapp
auth login navega com load e depois aguarda os seletores do formulário de login aparecerem antes de preencher/clicar, o que é mais confiável em telas de login SPA atrasadas.
Opção 5: Arquivo de estado (salvar/carregar manualmente)
# Após fazer login:
agent-browser state save ./auth.json
# Em uma sessão futura:
agent-browser state load ./auth.json
agent-browser open https://app.example.com/dashboard
Consulte references/authentication.md para padrões de OAuth, 2FA, autenticação baseada em cookies e atualização de tokens.
Comandos Essenciais
# Navegação
agent-browser open <url> # Navegar (aliases: goto, navigate)
agent-browser close # Fechar navegador
agent-browser close --all # Fechar todas as sessões ativas
# Snapshot
agent-browser snapshot -i # Elementos interativos com referências (recomendado)
agent-browser snapshot -s "#selector" # Escopo para seletor CSS
# Interação (use @refs do snapshot)
agent-browser click @e1 # Clicar no elemento
agent-browser click @e1 --new-tab # Clicar e abrir em nova aba
agent-browser fill @e2 "text" # Limpar e digitar texto
agent-browser type @e2 "text" # Digitar sem limpar
agent-browser select @e1 "option" # Selecionar opção de dropdown
agent-browser check @e1 # Marcar checkbox
agent-browser press Enter # Pressionar tecla
agent-browser keyboard type "text" # Digitar no foco atual (sem seletor)
agent-browser keyboard inserttext "text" # Inserir sem eventos de tecla
agent-browser scroll down 500 # Rolar página
agent-browser scroll down 500 --selector "div.content" # Rolar dentro de um contêiner específico
# 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
agent-browser get cdp-url # Obter URL do WebSocket CDP
# Aguardar
agent-browser wait @e1 # Aguardar elemento
agent-browser wait --load networkidle # Aguardar rede ociosa
agent-browser wait --url "**/page" # Aguardar padrão de URL
agent-browser wait 2000 # Aguardar milissegundos
agent-browser wait --text "Welcome" # Aguardar texto aparecer (correspondência de substring)
agent-browser wait --fn "!document.body.innerText.includes('Carregando...')" # Aguardar texto desaparecer
agent-browser wait "#spinner" --state hidden # Aguardar elemento desaparecer
# Downloads
agent-browser download @e1 ./file.pdf # Clicar no elemento para acionar download
agent-browser wait --download ./output.zip # Aguardar qualquer download ser concluído
agent-browser --download-path ./downloads open <url> # Definir diretório de download padrão
# Rede
agent-browser network requests # Inspecionar requisições rastreadas
agent-browser network requests --type xhr,fetch # Filtrar por tipo de recurso
agent-browser network requests --method POST # Filtrar por método HTTP
agent-browser network requests --status 2xx # Filtrar por status (200, 2xx, 400-499)
agent-browser network request <requestId> # Ver detalhes completos da requisição/resposta
agent-browser network route "**/api/*" --abort # Bloquear requisições correspondentes
agent-browser network har start # Iniciar gravação HAR
agent-browser network har stop ./capture.har # Parar e salvar arquivo HAR
# Viewport e Emulação de Dispositivo
agent-browser set viewport 1920 1080 # Definir tamanho do viewport (padrão: 1280x720)
agent-browser set viewport 1920 1080 2 # Retina 2x (mesmo tamanho CSS, screenshots de maior resolução)
agent-browser set device "iPhone 14" # Emular dispositivo (viewport + user agent)
# 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 de elementos numerados
agent-browser screenshot --screenshot-dir ./shots # Salvar em diretório personalizado
agent-browser screenshot --screenshot-format jpeg --screenshot-quality 80
agent-browser pdf output.pdf # Salvar como PDF
# Pré-visualização ao vivo / streaming
agent-browser stream enable # Iniciar streaming WebSocket em tempo real em uma porta auto-selecionada
agent-browser stream enable --port 9223 # Vincular uma porta localhost específica
agent-browser stream status # Inspecionar estado ativado, porta, conexão e screencasting
agent-browser stream disable # Parar streaming em tempo real e remover o arquivo de metadados .stream
# Área de transferência
agent-browser clipboard read # Ler texto da área de transferência
agent-browser clipboard write "Olá, Mundo!" # Escrever texto na área de transferência
agent-browser clipboard copy # Copiar seleção atual
agent-browser clipboard paste # Colar da área de transferência
# Diálogos (alert, confirm, prompt, beforeunload)
# Por padrão, diálogos alert e beforeunload são aceitos automaticamente para nunca bloquear o agente.
# Diálogos confirm e prompt ainda exigem manipulação explícita.
# Use --no-auto-dialog para desabilitar o tratamento automático.
agent-browser dialog accept # Aceitar diálogo
agent-browser dialog accept "minha entrada" # Aceitar diálogo prompt com texto
agent-browser dialog dismiss # Dispensar/cancelar diálogo
agent-browser dialog status # Verificar se um diálogo está atualmente aberto
# Diff (comparar estados de página)
agent-browser diff snapshot # Comparar snapshot atual com o último
agent-browser diff snapshot --baseline before.txt # Comparar snapshot atual com arquivo salvo
agent-browser diff screenshot --baseline before.png # Diff 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 elemento
Streaming
Toda sessão inicia automaticamente um servidor WebSocket de streaming em uma porta atribuída pelo SO. Use agent-browser stream status para ver a porta vinculada e o estado da conexão. Use stream disable para desativá-lo e stream enable --port <port> para reativá-lo em uma porta específica.
Execução em Lote
Execute múltiplos comandos em uma única invocação canalizando um array JSON de arrays de strings para batch. Isso evita a sobrecarga de inicialização de processo por comando ao executar fluxos de trabalho de várias etapas.
echo '[
["open", "https://example.com"],
["snapshot", "-i"],
["click", "@e1"],
["screenshot", "result.png"]
]' | agent-browser batch --json
# Parar no primeiro erro
agent-browser batch --bail < commands.json
Use batch quando você tiver uma sequência conhecida de comandos que não dependem de saída intermediária. Use comandos separados ou encadeamento com && quando precisar analisar a saída entre as etapas (ex.: snapshot para descobrir referências, depois interagir).
Padrões Comuns
Envio de Formulário
agent-browser open https://example.com/signup
agent-browser snapshot -i
agent-browser fill @e1 "João 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 Cofre de Senhas (Recomendado)
# Salvar credenciais uma vez (criptografado com AGENT_BROWSER_ENCRYPTION_KEY)
# Recomendado: canalizar senha via stdin para evitar exposição no histórico do shell
echo "senha" | agent-browser auth save github --url https://github.com/login --username usuario --password-stdin
# Logar usando perfil salvo (LLM nunca vê a senha)
agent-browser auth login github
# Listar/mostrar/excluir perfis
agent-browser auth list
agent-browser auth show github
agent-browser auth delete github
auth login aguarda os seletores de usuário/senha/enviar antes de interagir, com um tempo limite vinculado ao tempo limite de ação padrão.
Autenticação com Persistência de Estado
# Logar uma vez e salvar estado
agent-browser open https://app.example.com/login
agent-browser snapshot -i
agent-browser fill @e1 "$USERNAME"
agent-browser fill @e2 "$PASSWORD"
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 reinicializações do navegador
agent-browser --session-name myapp open https://app.example.com/login
# ... fluxo de login ...
agent-browser close # Estado salvo automaticamente em ~/.agent-browser/sessions/
# Próxima vez, o estado é carregado automaticamente
agent-browser --session-name myapp open https://app.example.com/dashboard
# Criptografar estado em repouso
export AGENT_BROWSER_ENCRYPTION_KEY=$(openssl rand -hex 32)
agent-browser --session-name secure open https://app.example.com
# Gerenciar estados salvos
agent-browser state list
agent-browser state show myapp-default.json
agent-browser state clear myapp
agent-browser state clean --older-than 7
Trabalhando com Iframes
O conteúdo de iframes é automaticamente incluído em snapshots. As referências dentro de iframes carregam contexto do frame, então você pode interagir com elas diretamente.
agent-browser open https://example.com/checkout
agent-browser snapshot -i
# @e1 [heading] "Checkout"
# @e2 [Iframe] "payment-frame"
# @e3 [input] "Número do cartão"
# @e4 [input] "Validade"
# @e5 [button] "Pagar"
# Interagir diretamente — sem necessidade de alternar frame
agent-browser fill @e3 "4111111111111111"
agent-browser fill @e4 "12/28"
agent-browser click @e5
# Para escopar um snapshot a um iframe:
agent-browser frame @e2
agent-browser snapshot -i # Apenas conteúdo do iframe
agent-browser frame main # Retornar ao frame principal
Extração de Dados
agent-browser open https://example.com/products
agent-browser snapshot -i
agent-browser get text @e5 # Obter texto de elemento específico
agent-browser get text body > page.txt # Obter todo o texto da 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 Chrome em execução com depuração remota ativada
agent-browser --auto-connect open https://example.com
agent-browser --auto-connect snapshot
# Ou com porta CDP explícita
agent-browser --cdp 9222 snapshot
Auto-conexão descobre o Chrome via DevToolsActivePort, portas de depuração comuns (9222, 9229), e recai para uma conexão WebSocket direta se a descoberta CDP baseada em HTTP falhar.