Automação de Navegador com agent-browser
A CLI usa Chrome/Chromium diretamente via CDP. Instale via npm i -g agent-browser, brew install agent-browser, ou cargo install agent-browser. Execute agent-browser install para baixar o Chrome. Instalações existentes do Chrome, Brave, Playwright e Puppeteer são detectadas automaticamente. 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 as referências para clicar, preencher, selecionar
- Novo Snapshot: 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 2000
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 via um daemon em segundo plano, então o encadeamento é seguro e mais eficiente do que chamadas separadas.
# Encadear abertura + snapshot em uma chamada (open já aguarda o carregamento da página)
agent-browser open https://example.com && 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 screenshot
Quando encadear: Use && quando você não precisar ler a saída de um comando intermediário antes de prosseguir (por exemplo, abrir + aguardar + capturar tela). Execute comandos separadamente quando precisar analisar a saída primeiro (por exemplo, snapshot para descobrir referências, depois interagir usando essas referências).
Lidando com Autenticação
Ao automatizar um site que requer login, escolha a abordagem mais adequada:
Opção 1: Importar autenticação do navegador do usuário (mais rápido para tarefas únicas)
# Conectar ao Chrome em execução do usuário (já está logado)
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 forem mais necessários. Defina AGENT_BROWSER_ENCRYPTION_KEY para criptografia em repouso.
Opção 2: Reutilização de perfil do Chrome (zero configuração)
# Listar perfis do Chrome disponíveis
agent-browser profiles
# Reutilizar o estado de login existente do usuário
agent-browser --profile Default open https://gmail.com
Opção 3: Perfil persistente (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 4: Nome de sessão (auto-salvar/restaurar cookies + localStorage)
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 5: Vault 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 então aguarda os seletores do formulário de login aparecerem antes de preencher/clicar, o que é mais confiável em telas de login SPA com atraso.
Opção 6: 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 renovação de tokens.
Comandos Essenciais
# Lote: SEMPRE use lote para 2+ comandos sequenciais. Os comandos executam em ordem.
agent-browser batch "open https://example.com" "snapshot -i"
agent-browser batch "open https://example.com" "screenshot"
agent-browser batch "click @e1" "wait 1000" "screenshot"
# Navegação
agent-browser open <url> # Navegar (atalhos: 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 -i --urls # Incluir URLs de href para links
agent-browser snapshot -s "#selector" # Escopo para seletor CSS
# Interação (use @refs do snapshot)
agent-browser click @e1 # Clicar 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 # Rolagem de página
agent-browser scroll down 500 --selector "div.content" # Rolagem 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 WebSocket do CDP
# Aguardar
agent-browser wait @e1 # Aguardar elemento
agent-browser wait 2000 # Aguardar milissegundos
agent-browser wait --url "**/pagina" # Aguardar padrão de URL
agent-browser wait --text "Bem-vindo" # Aguardar texto aparecer (correspondência de substring)
agent-browser wait --load networkidle # Aguardar ociosidade da rede (cuidado: veja Armadilhas)
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 ./arquivo.pdf # Clicar no elemento para disparar download
agent-browser wait --download ./saida.zip # Aguardar qualquer download ser concluído
agent-browser --download-path ./downloads open <url> # Definir diretório de download padrão
# Gerenciamento de abas
agent-browser tab list # Listar todas as abas abertas
agent-browser tab new # Abrir nova aba em branco
agent-browser tab new https://example.com # Abrir URL em nova aba
agent-browser tab 2 # Mudar para aba por índice (base 0)
agent-browser tab close # Fechar aba atual
agent-browser tab close 2 # Fechar aba por índice
# 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 ./captura.har # Parar e salvar arquivo HAR
# Viewport & 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 no diretório temporário
agent-browser screenshot --full # Screenshot de página inteira
agent-browser screenshot --annotate # Screenshot anotado com rótulos numerados 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
# Visualização ao vivo / streaming
agent-browser stream enable # Iniciar streaming WebSocket em tempo de execução em porta auto-selecionada
agent-browser stream enable --port 9223 # Vincular a uma porta localhost específica
agent-browser stream status # Inspecionar estado habilitado, porta, conexão e screencasting
agent-browser stream disable # Parar streaming em tempo de execução e remover o arquivo .stream de metadados
# Á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 tratamento explícito.
# Use --no-auto-dialog (ou AGENT_BROWSER_NO_AUTO_DIALOG=1) 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á 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 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
# Chat (controle por linguagem natural com IA)
agent-browser chat "abra google.com e pesquise por gatos" # Instrução única
agent-browser chat # Modo REPL interativo
agent-browser -q chat "resuma esta página" # Silencioso (apenas texto, sem chamadas de ferramenta)
agent-browser -v chat "preencha o formulário de login" # Verboso (mostrar saída do comando)
agent-browser --model openai/gpt-4o chat "tire um screenshot" # Substituir modelo
Streaming
Toda sessão inicia automaticamente um servidor de stream WebSocket 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 derrubá-lo e stream enable --port <porta> para reativar em uma porta específica.
Execução em Lote
SEMPRE use batch ao executar 2+ comandos em sequência. Lote executa comandos em ordem, portanto comandos dependentes (como navegar e depois capturar tela) funcionam corretamente. Cada argumento entre aspas é um comando separado.
# Navegar e tirar um snapshot
agent-browser batch "open https://example.com" "snapshot -i"
# Navegar, snapshot e screenshot em uma chamada
agent-browser batch "open https://example.com" "snapshot -i" "screenshot"
# Clicar, aguardar e capturar tela
agent-browser batch "click @e1" "wait 1000" "screenshot"
# Com --bail para parar no primeiro erro
agent-browser batch --bail "open https://example.com" "click @e1" "screenshot"
Use um único comando (não lote) apenas quando precisar ler a saída antes de decidir o próximo comando. Por exemplo, você deve executar snapshot -i como um único comando quando precisar ler as referências para decidir em que clicar. Após ler o snapshot, coloque em lote as etapas restantes.
O modo stdin também é suportado para uso programático:
echo '[["open","https://example.com"],["screenshot"]]' | agent-browser batch --json
agent-browser batch --bail < commands.json
Estratégias de Eficiência
Estes padrões minimizam chamadas de ferramenta e uso de tokens.
Use --urls para evitar re-navegação. Quando precisar visitar links de uma página, use snapshot -i --urls para obter todas as URLs de href antecipadamente. Em seguida, open cada URL diretamente em vez de clicar em referências e navegar de volta.
Snapshot uma vez, aja muitas vezes. Nunca refaça snapshot da mesma página. Extraia todas as informações necessárias (refs, URLs, texto) de um único snapshot e coloque em lote as ações restantes.
Fluxo de trabalho de múltiplas páginas (por exemplo, "visite N sites e capture tela de cada um"):
# 1. Obter todas as URLs em uma chamada
agent-browser batch "open https://news.ycombinator.com" "snapshot -i --urls"
# Ler a saída para extrair URLs, depois visitar cada uma diretamente:
# 2. Um lote por site alvo
agent-browser batch "open https://github.com/example/repo" "screenshot"
agent-browser batch "open https://example.com/artigo" "screenshot"
agent-browser batch "open https://outro.com/pagina" "screenshot"
Esta abordagem usa 4 chamadas de ferramenta em vez de 14+. Nunca volte para a página de listagem entre as visitas.
Padrões Comuns
Submissão de Formulário
# Navegar e obter a estrutura do formulário
agent-browser batch "open https://example.com/cadastro" "snapshot -i"
# Ler a saída do snapshot para identificar referências do formulário, depois preencher e enviar
agent-browser batch "fill @e1 \"João Silva\"" "fill @e2 \"[email protected]\"" "select @e3 \"São Paulo\"" "check @e4" "click @e5" "wait 2000"
Autenticação com Vault de Autenticação (Recomendado)
# Salvar credenciais uma vez (criptografadas com AGENT_BROWSER_ENCRYPTION_KEY)
# Recomendado: passar 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
Coleta de Dados (Scraping)
# Navegar para a página e obter a estrutura
agent-browser batch "open https://exemplo.com/produtos" "snapshot -i"
# Extrair texto de elementos específicos
agent-browser get text @e1
agent-browser get text @e5
agent-browser get text @e12
# Rolagem para carregar mais conteúdo
agent-browser batch "scroll down 800" "wait 1000" "snapshot -i"
# Agora extrair novos elementos
Download de Arquivo
agent-browser open https://exemplo.com/download
# Usar seletor de link de download conhecido
agent-browser download @e1 ./meu-arquivo.zip
# Ou aguardar qualquer download ser concluído
agent-browser wait --download ./saida.zip
Teste de Aplicação Web
# Navegar para a app
agent-browser open https://meuapp.test/login
# Inserir credenciais e enviar
agent-browser batch "fill @e1 admin" "fill @e2 senha123" "click @e3"
# Aguardar resposta do servidor
agent-browser wait 2000
# Verificar resultado
agent-browser snapshot -i --urls
# Navegar para recursos protegidos
agent-browser open https://meuapp.test/dashboard
# Verificar elementos na página
agent-browser get text @e4
Notas Importantes
- A ferramenta presume que você sabe o que está fazendo — ela não previne ações perigosas. Sempre revise comandos antes de executar.
- Para tarefas sensíveis (como login bancário), prefira perfis persistentes ou opções de sessão nomeada. Credenciais no vault são armazenadas criptografadas se
AGENT_BROWSER_ENCRYPTION_KEYestiver definida. - Snapshot com
-iretorna apenas elementos interativos (inputs, botões, links, etc.). Use-apara todos os elementos quando necessário. - O navegador se fecha automaticamente quando o processo CLI termina. Use perfis ou sessões nomeadas para persistir estado.