agent-browser

Overview

What is agent-browser?

agent-browser é uma ferramenta de automação de navegador em linha de comando, criada para agentes de IA e fluxos baseados em shell. Ela se conecta diretamente ao Chrome ou Chromium via Chrome DevTools Protocol (CDP), permitindo scriptar interações reais de navegador a partir do terminal ou de um runtime de agente.

Com o agent-browser você pode:

• Abrir e navegar por páginas web (agent-browser open <url>)
• Descobrir elementos interativos via snapshots estruturados
• Clicar em botões, seguir links e interagir com formulários
• Preencher campos, digitar texto e pressionar teclas
• Tirar snapshots para entender a estrutura da página e as ações disponíveis
• Gerenciar sessões e preservar o estado autenticado
• Conduzir fluxos de autenticação (incluindo OAuth e 2FA com ajuda humana)
• Usar proxies para testes de geolocalização ou ambientes corporativos
• Gravar traces de performance para profiling
• Capturar vídeo de sessões de navegador para debug ou documentação

Who is agent-browser for?

agent-browser é uma boa opção se você:

• Executa um agente de IA ou framework de automação que precisa controlar um navegador real
• Quer uma abordagem CLI-first para automatizar fluxos no Chrome/Chromium
• Precisa de um targeting robusto de elementos, amigável a LLMs (usando @refs compactos)
• Automatiza fluxos de login, envio de formulários ou fluxos de apps web de múltiplas etapas
• Captura testes, demos ou sessões de debug reproduzíveis como vídeo ou traces

Ele é especialmente útil nos cenários:

• Automação de navegador: navegação scriptada, cliques e preenchimento de formulários
• Automação de workflow: sequências ponta a ponta como "fazer login → navegar → exportar relatório"
• Automação de testes: smoke tests, checagens de regressão e profiling de performance de apps web

When agent-browser is and is not a good fit

Use agent-browser quando:

• Você pode rodar uma CLI localmente e tem acesso ao Chrome ou Chromium
• Quer um comportamento de navegador determinístico e scriptável, exposto a um agente de IA
• Precisa de controle detalhado sobre sessões, cookies e autenticação

Pode não ser uma boa escolha quando:

• Você não pode instalar ou rodar Chrome/Chromium na máquina host
• Só precisa de HTML bruto ou requisições HTTP simples (um cliente HTTP ou scraper puro pode ser mais simples)
• Precisa de controle de navegador headless em linguagens ou runtimes fortemente acoplados a outras bibliotecas de automação de navegador

How to Use

Installation options

agent-browser oferece múltiplos métodos de instalação. Escolha o que melhor se encaixa no seu ambiente:

• npm (Node.js)

  npm i -g agent-browser
  

• Homebrew (macOS/Linux)

  brew install agent-browser
  

• Rust / Cargo

  cargo install agent-browser
  

Depois de instalar a CLI, execute o setup integrado do Chrome:

agent-browser install

Isso faz o download e configura uma versão compatível do Chrome/Chromium. Quando houver uma nova versão disponível, atualize com:

agent-browser upgrade

Se você estiver usando o agent-browser como uma skill em uma plataforma de agentes, também pode adicioná-lo com:

npx skills add https://github.com/vercel-labs/agent-browser --skill agent-browser

Consulte o arquivo SKILL.md no repositório para ver os detalhes mais recentes de integração específicos da skill.

Core browser automation workflow

Todo fluxo com agent-browser segue um loop simples: open → snapshot → interact → re-snapshot.

1. Navegar até uma página

   agent-browser open https://example.com/form
   

2. Tirar um snapshot para descobrir elementos
   Use o modo de snapshot interativo para obter uma lista compacta de elementos clicáveis e preenchíveis com @refs:

   agent-browser snapshot -i
   

   Exemplo de saída (simplificada):

   @e1 [input type="email"]
   @e2 [input type="password"]
   @e3 [button] "Submit"
   

3. Interagir usando refs

   agent-browser fill @e1 "user@example.com"
   agent-browser fill @e2 "password123"
   agent-browser click @e3
   

4. Esperar e tirar novo snapshot

   agent-browser wait --load networkidle
   agent-browser snapshot -i
   

Esse padrão permite que um agente de IA raciocine sobre uma visão estrutural compacta em vez do DOM completo, o que reduz significativamente o uso de contexto.

Command reference basics

agent-browser expõe um conjunto abrangente de comandos (veja references/commands.md), incluindo:

• Navigation

  agent-browser open <url>
  agent-browser back
  agent-browser forward
  agent-browser reload
  agent-browser close
  

• Snapshot and refs

  agent-browser snapshot          # full tree
  agent-browser snapshot -i       # interactive elements only (recommended)
  agent-browser snapshot -c       # compact output
  agent-browser snapshot -d 3     # limit depth
  agent-browser snapshot -s "#main"  # scoped to CSS selector
  

• Interactions

  agent-browser click @e1
  agent-browser dblclick @e1
  agent-browser hover @e1
  agent-browser focus @e1
  agent-browser fill @e2 "text"
  agent-browser type @e2 "text"
  agent-browser press Enter
  

Use references/snapshot-refs.md para uma explicação mais detalhada de como os @refs são gerados e por quanto tempo permanecem válidos.

Working with sessions and authentication

agent-browser oferece ferramentas integradas para navegação autenticada e multi-sessão. Isso é útil para fluxos de login, testes com múltiplas contas ou isolamento de papéis de usuário.

• Named sessions (veja references/session-management.md):

  # Session "auth": login flow
  agent-browser --session auth open https://app.example.com/login
  
  # Session "public": separate browsing
  agent-browser --session public open https://example.com
  

  Cada sessão tem cookies, storage, cache e histórico isolados.

• Persistência de estado de sessão:

  # Save cookies and storage
  agent-browser state save ./auth-state.json
  
  # Restore later
  agent-browser state load ./auth-state.json
  agent-browser open https://app.example.com/dashboard
  

• Padrões de autenticação (veja references/authentication.md):

  • Importar cookies de uma instância do Chrome com debug habilitado em que você já esteja logado
  • Passar por formulários de login padrão usando snapshots e fill/click
  • Lidar com autenticação baseada em cookies, HTTP basic auth e refresh de tokens

Para fluxos complexos de OAuth ou 2FA, ainda pode ser necessário envolver um humano na configuração inicial; depois disso, o agent-browser pode reutilizar o estado autenticado salvo.

Proxy support and network configuration

Se você precisar rotear o tráfego por um proxy (para testes de geolocalização, limitação de taxa ou ambientes corporativos), use as opções documentadas em references/proxy-support.md:

• Proxy HTTP/HTTPS via flag da CLI

  agent-browser --proxy "http://proxy.example.com:8080" open https://example.com
  

• Configuração por variável de ambiente

  export HTTP_PROXY="http://proxy.example.com:8080"
  export HTTPS_PROXY="https://proxy.example.com:8080"
  agent-browser open https://example.com
  

• SOCKS proxy

  export ALL_PROXY="socks5://proxy.example.com:1080"
  agent-browser open https://example.com
  

Profiling and performance tracing

Para automação de testes e investigação de performance, o agent-browser pode capturar traces de performance do Chrome (veja references/profiling.md):

# Start profiling
agent-browser profiler start

# Run your scenario
agent-browser open https://example.com
agent-browser click @e1
agent-browser wait 1000

# Stop and save trace
agent-browser profiler stop ./trace.json

Você pode abrir o trace.json resultante no Chrome DevTools (aba Performance) ou em visualizadores compatíveis para analisar execução de JavaScript, renderização e eventos de user timing.

Video recording for debugging and documentation

agent-browser pode gravar um vídeo da sessão de navegador, o que é útil para depurar automações com falha ou criar tutoriais passo a passo (veja references/video-recording.md):

# Start recording
agent-browser record start ./demo.webm

# Perform actions
agent-browser open https://example.com
agent-browser snapshot -i
agent-browser click @e1

# Stop recording
agent-browser record stop

Você pode incorporar esses arquivos .webm na documentação, compartilhá-los com o time ou anexá-los a relatórios de bug.

Using templates for common workflows

O repositório inclui templates de scripts de shell no diretório templates/ para ajudar você a construir fluxos de trabalho reproduzíveis:

• templates/form-automation.sh – padrão estruturado para preencher e enviar formulários
• templates/authenticated-session.sh – exemplo de login e persistência de estado de sessão
• templates/capture-workflow.sh – padrão para tirar snapshots ou gravar um fluxo de múltiplas etapas

Você pode copiar e adaptar esses scripts ao seu ambiente, jobs de CI ou pipelines de agentes.

FAQ

What problems does agent-browser solve compared to simple HTTP clients?

agent-browser controla uma instância real do Chrome/Chromium via CDP. Isso significa que ele consegue lidar com:

• Renderização client-side e JavaScript complexo
• Single-page apps que dependem de APIs do navegador
• Interações reais de usuário, como cliques, digitação e pressionar teclas
• Tempo visual, comportamento de renderização e traces de performance

Se você só precisa de HTML ou JSON bruto de endpoints básicos, um cliente HTTP pode ser suficiente. Para qualquer coisa que precise se comportar como um usuário real em um navegador, o agent-browser é mais apropriado.

How do I install Chrome or Chromium for agent-browser?

Depois de instalar a CLI com npm, Homebrew ou Cargo, execute:

agent-browser install

Isso baixa e configura uma versão compatível do Chrome/Chromium que o agent-browser consegue controlar via CDP. Quando uma nova versão for lançada, atualize com:

agent-browser upgrade

Can agent-browser reuse my existing logged-in browser session?

Sim. references/authentication.md explica como iniciar o Chrome com --remote-debugging-port e importar cookies de uma sessão em que você já esteja logado. Depois de importar, você pode salvar esse estado autenticado com agent-browser state save e restaurá-lo mais tarde sem repetir todo o fluxo de login.

Is agent-browser suitable for CI and automated testing?

Sim. agent-browser é uma ferramenta de linha de comando que funciona bem em ambientes automatizados, desde que o Chrome/Chromium esteja disponível. Você pode:

• Executar fluxos ponta a ponta como parte de suites de teste
• Capturar traces de performance durante o build
• Gravar vídeos de cenários com falha

Para CI, use o método de instalação que corresponde à imagem de build (npm, Homebrew ou Cargo) e então faça o script dos fluxos usando shell scripts ou o seu framework de agentes.

How does agent-browser help AI agents work with complex pages?

Em vez de despejar o DOM completo, o agent-browser fornece snapshots compactos com @refs estáveis para elementos importantes (links, botões, inputs etc.). Isso reduz drasticamente o uso de tokens e facilita para um agente de IA:

• Entender a estrutura da página
• Escolher o elemento certo pelo ref
• Emitir comandos click, fill e press de forma precisa

references/snapshot-refs.md explica como os refs são gerados, quando atualizá-los e boas práticas para automação robusta.

Does agent-browser support proxies and corporate networks?

Sim. Você pode configurar proxies HTTP, HTTPS e SOCKS tanto via flags da CLI (--proxy) quanto por variáveis de ambiente (HTTP_PROXY, HTTPS_PROXY, ALL_PROXY). references/proxy-support.md cobre configuração básica, proxies autenticados, regras de bypass e dicas de troubleshooting.

Where should I start in the repository to learn more?

Para um mergulho prático no agent-browser:

• Comece com SKILL.md para a visão geral e o quick start
• Leia references/commands.md para a lista completa de comandos e opções
• Consulte references/authentication.md, references/session-management.md, references/snapshot-refs.md, references/profiling.md e references/video-recording.md para tópicos específicos
• Explore o diretório templates/ em busca de scripts de workflow prontos que você pode adaptar aos seus próprios casos de uso