Automação de Navegador com agent-browser
A CLI usa Chrome/Chromium via CDP diretamente. Instale via npm i -g agent-browser, brew install agent-browser ou cargo install agent-browser. Execute agent-browser install para baixar o Chrome.
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: Use as referências para clicar, preencher, selecionar
- Re-snapshot: Após navegação ou mudanças no DOM, obtenha 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 (por exemplo, open + wait + screenshot). Execute comandos separadamente quando precisar analisar a saída primeiro (por exemplo, snapshot para descobrir referências, depois interagir usando essas referências).
Gerenciamento de Autenticação
Ao automatizar um site que requer login, escolha a abordagem que se adequa:
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 (eles já estão logados)
agent-browser --auto-connect state save ./auth.json
# Usar esse 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 via automação
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
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 autenticação OAuth, 2FA, baseada em cookies e renovação de token.
Comandos Essenciais
# Navegação
agent-browser open <url> # Navegar (aliases: goto, navigate)
agent-browser close # Fechar navegador
# 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 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 "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 keyboard type "texto" # Digitar no foco atual (sem seletor)
agent-browser keyboard inserttext "texto" # 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 "Bem-vindo" # Aguardar texto aparecer (correspondência de substring)
agent-browser wait --fn "!document.body.innerText.includes('Carregando...')" # Aguardar texto sumir
agent-browser wait "#spinner" --state hidden # Aguardar elemento desaparecer
# Downloads
agent-browser download @e1 ./arquivo.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
# Viewport e Emulação de Dispositivos
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, capturas de tela de maior resolução)
agent-browser set device "iPhone 14" # Emular dispositivo (viewport + user agent)
# Captura
agent-browser screenshot # Captura de tela para diretório temporário
agent-browser screenshot --full # Captura de tela de página inteira
agent-browser screenshot --annotate # Captura de tela anotada com rótulos numéricos de elementos
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
# Á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
# Diferença (comparar estados da página)
agent-browser diff snapshot # Comparar snapshot atual com o último
agent-browser diff snapshot --baseline antes.txt # Comparar snapshot atual com arquivo salvo
agent-browser diff screenshot --baseline antes.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 elemento
Padrões Comuns
Envio de Formulário
agent-browser open https://example.com/cadastro
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 (Recomendado)
# Salvar credenciais uma vez (criptografadas com AGENT_BROWSER_ENCRYPTION_KEY)
# Recomendado: enviar 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
# Login 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
Autenticação com Persistência de Estado
# Login 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
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 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
Esquema de Cores (Modo Escuro)
# Modo escuro persistente via flag (aplica-se a todas as páginas e novas abas)
agent-browser --color-scheme dark open https://example.com
# Ou via variável de ambiente
AGENT_BROWSER_COLOR_SCHEME=dark agent-browser open https://example.com
# Ou definir durante a sessão (persiste para comandos subsequentes)
agent-browser set media dark
Viewport e Teste Responsivo
# Definir um tamanho de viewport personalizado (padrão é 1280x720)
agent-browser set viewport 1920 1080
agent-browser screenshot desktop.png
# Testar layout de largura de celular
agent-browser set viewport 375 812
agent-browser screenshot mobile.png
# Retina/HiDPI: mesmo layout CSS com densidade de pixel 2x
# As capturas de tela permanecem no tamanho lógico do viewport, mas o conteúdo renderiza com DPI mais alto
agent-browser set viewport 1920 1080 2
agent-browser screenshot retina.png
# Emulação de dispositivo (define viewport + user agent em uma etapa)
agent-browser set device "iPhone 14"
agent-browser screenshot device.png
O parâmetro scale (3º argumento) define window.devicePixelRatio sem alterar o layout CSS. Use-o ao testar renderização retina ou capturar capturas de tela de maior resolução.
Navegador Visual (Depuração)
agent-browser --headed open https://example.com
agent-browser highlight @e1 # Destacar elemento
agent-browser inspect # Abrir Chrome DevTools para a página ativa
agent-browser record start demo.webm # Gravar sessão
agent-browser profiler start # Iniciar perfilamento do Chrome DevTools
agent-browser profiler stop trace.json # Parar e salvar perfil (caminho opcional)
Use AGENT_BROWSER_HEADED=1 para ativar o modo com cabeçalho via variável de ambiente. As extensões do navegador funcionam tanto no modo com cabeçalho quanto no modo headless.
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 Mobile)
# 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 do desktop - snapshot, interagir, re-snapshot
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 mobile
# Tirar captura de tela
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 vem de xcrun xctrace list devices.
Segurança
Todos os recursos de segurança são opcionais. Por padrão, o agent-browser não impõe restrições à navegação, ações ou saídas.
Limites de Conteúdo (Recomendado para Agentes de IA)
Ative --content-boundaries para envolver a saída originada da página em marcadores que ajudam os LLMs a distinguir a saída da ferramenta do conteúdo não confiável da página:
export AGENT_BROWSER_CONTENT_BOUNDARIES=1
agent-browser snapshot
# Saída:
# --- AGENT_BROWSER_PAGE_CONTENT nonce=<hex> origin=https://example.com ---
# [árvore de acessibilidade]
# --- END_AGENT_BROWSER_PAGE_CONTENT nonce=<hex> ---
Lista de Permissão de Domínios
Restrinja a navegação a domínios confiáveis. Curingas como *.example.com também correspondem ao domínio base example.com. Solicitações de sub-recursos, WebSocket e conexões EventSource para domínios não permitidos também são bloqueadas. Inclua domínios CDN dos quais suas páginas de destino dependem:
export AGENT_BROWSER_ALLOW="*.app.example.com,*.cdn.example.com"
Modo de Confinamento (Sandbox)
Execute ações com privilégios reduzidos para limitar a exposição ao conteúdo da página:
# Não executar JavaScript na página
export AGENT_BROWSER_SCRIPT_CONTROL=block
# Usar apenas acessibilidade (sem CDP bruto)
export AGENT_BROWSER_MODE=accessibility
# Impedir navegação para domínios não confiáveis
export AGENT_BROWSER_ALLOW="*.app.example.com"
Integração com Modelo de IA
Cada comando do agent-browser é uma ferramenta individual. Headers e prompts do sistema gerenciam estado de forma transparente. Consulte prompts/system.md para prompt de modelo padrão e prompt de ferramenta para cada comando.
Comandos Utilitários
agent-browser --help # Ajuda geral da CLI
agent-browser install # Instalar Chrome
agent-browser doctor # Verificar estado da instalação e depuração
agent-browser reset # Redefinir estado interno (útil se o navegador travar)
agent-browser session list # Listar sessões ativas
agent-browser version # Exibir versão
Variáveis de Ambiente
| Ambiente | Padrão | Descrição |
|---|---|---|
AGENT_BROWSER_COLOR_SCHEME | - | Esquema de cores (light ou dark) |
AGENT_BROWSER_HEADED | - | Modo com cabeçalho para depuração |
AGENT_BROWSER_AUTO_CONNECT | - | Conectar automaticamente ao Chrome em execução |
AGENT_BROWSER_ENCRYPTION_KEY | - | Chave de criptografia para estados de sessão e arquivos de estado |
AGENT_BROWSER_CONTENT_BOUNDARIES | - | Envolver saída de página em marcadores |
AGENT_BROWSER_CHROME_PATH | - | Caminho para executável do Chrome/Chromium |
AGENT_BROWSER_ALLOW | - | Padrões de URL de lista de permissão de domínios (separados por vírgula) |
AGENT_BROWSER_SCRIPT_CONTROL | - | Controle de execução de script: block, allow |
AGENT_BROWSER_MODE | - | Modo de interação: accessibility, dom |
AGENT_BROWSER_EXIT_ON_KEY | - | Tecla para sair (ex: q, Control+C) |
AGENT_BROWSER_DOWNLOAD_PATH | - | Diretório de download padrão |
AGENT_BROWSER_SHOW_COOKIES | - | Exibir cookies em saída de snapshot |
AGENT_BROWSER_VERBOSE | - | Log detalhado |
AGENT_BROWSER_SESSION_NAME | - | Nome de sessão para auto-salvar/restaurar |
AGENT_BROWSER_USER_DATA_DIR | - | Diretório de dados do usuário do Chrome |
DEBUG | - | Log de depuração do agent-browser |
CDP_WS_URL | - | URL do WebSocket CDP para conectar a navegador existente |