agent-browser

Overview

What is agent-browser?

agent-browser es una herramienta de automatización de navegador en línea de comandos diseñada para agentes de IA y flujos basados en shell. Se conecta directamente a Chrome o Chromium mediante el Chrome DevTools Protocol (CDP), de modo que puedes scriptar interacciones reales de navegador desde el terminal o desde el runtime de un agente.

Con agent-browser puedes:

• Abrir y navegar por páginas web (agent-browser open <url>)
• Descubrir elementos interactivos mediante snapshots estructurados
• Hacer clic en botones, seguir enlaces e interactuar con formularios
• Rellenar inputs, escribir texto y pulsar teclas
• Tomar snapshots para entender la estructura de la página y las acciones disponibles
• Gestionar sesiones y conservar el estado autenticado
• Completar flujos de autenticación (incluyendo OAuth y 2FA con ayuda humana)
• Usar proxies para pruebas geolocalizadas o entornos corporativos
• Registrar trazas de rendimiento para profiling
• Grabar video de sesiones de navegador para depuración o documentación

Who is agent-browser for?

agent-browser encaja bien si:

• Ejecutas un agente de IA o un framework de automatización que necesita controlar un navegador real
• Quieres una forma "CLI-first" de automatizar flujos de Chrome/Chromium
• Necesitas un sistema robusto de selección de elementos amigable para LLMs (mediante @refs compactos)
• Automatizas flujos de login, envío de formularios o recorridos de apps web de varios pasos
• Quieres capturar pruebas reproducibles, demos o sesiones de depuración como video o trazas

Es especialmente útil en estos casos:

• Automatización de navegador: navegación scriptada, clics y rellenado de formularios
• Automatización de flujos: secuencias de extremo a extremo como "iniciar sesión → navegar → exportar informe"
• Automatización de tests: smoke tests, comprobaciones de regresión y profiling de rendimiento de aplicaciones web

When agent-browser is and is not a good fit

Usa agent-browser cuando:

• Puedes ejecutar una CLI local y tienes acceso a Chrome o Chromium
• Quieres un comportamiento de navegador determinista y scriptable expuesto a un agente de IA
• Necesitas control detallado sobre sesiones, cookies y autenticación

Puede no ser la mejor opción cuando:

• No puedes instalar ni ejecutar Chrome/Chromium en el host
• Solo necesitas HTML en bruto o peticiones HTTP sencillas (un cliente HTTP o scraper puro puede ser más simple)
• Requieres control de navegador headless en lenguajes o runtimes muy acoplados a otras librerías de automatización de navegador

How to Use

Installation options

agent-browser admite varios métodos de instalación. Elige el que mejor se adapte a tu entorno:

• npm (Node.js)

  npm i -g agent-browser
  

• Homebrew (macOS/Linux)

  brew install agent-browser
  

• Rust / Cargo

  cargo install agent-browser
  

Después de instalar la CLI, ejecuta la configuración integrada de Chrome:

agent-browser install

Esto descarga y conecta una versión compatible de Chrome/Chromium. Cuando haya una nueva versión disponible, actualiza con:

agent-browser upgrade

Si usas agent-browser como skill dentro de una plataforma de agentes, también puedes añadirlo con:

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

Consulta el archivo SKILL.md en el repositorio para ver los detalles más recientes sobre la integración específica del skill.

Core browser automation workflow

Cada flujo de trabajo de agent-browser sigue un bucle sencillo: open → snapshot → interact → re-snapshot.

1. Navigate to a page

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

2. Take a snapshot to discover elements
   Usa el modo interactivo de snapshot para obtener una lista compacta de elementos clicables y rellenables con @refs:

   agent-browser snapshot -i
   

   Ejemplo de salida (simplificada):

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

3. Interact using refs

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

4. Wait and re-snapshot

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

Este patrón permite que un agente de IA razone sobre una vista estructural compacta en lugar del DOM completo, lo que reduce significativamente el uso de contexto.

Command reference basics

agent-browser expone un conjunto amplio de comandos (ver references/commands.md), entre ellos:

• Navigation

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

• Snapshot and refs

  agent-browser snapshot          # árbol completo
  agent-browser snapshot -i       # solo elementos interactivos (recomendado)
  agent-browser snapshot -c       # salida compacta
  agent-browser snapshot -d 3     # limitar profundidad
  agent-browser snapshot -s "#main"  # limitado a un selector CSS
  

• 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
  

Usa references/snapshot-refs.md para una guía más profunda sobre cómo se generan los @refs y cuánto tiempo permanecen válidos.

Working with sessions and authentication

agent-browser ofrece herramientas integradas para navegación autenticada y multi-sesión. Esto es útil para flujos de login, pruebas multi-cuenta o aislamiento de roles de usuario.

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

  # Session "auth": flujo de login
  agent-browser --session auth open https://app.example.com/login
  
  # Session "public": navegación separada
  agent-browser --session public open https://example.com
  

  Cada sesión tiene cookies, almacenamiento, caché e historial aislados.

• Session state persistence:

  # Guardar cookies y almacenamiento
  agent-browser state save ./auth-state.json
  
  # Restaurar más adelante
  agent-browser state load ./auth-state.json
  agent-browser open https://app.example.com/dashboard
  

• Authentication patterns (ver references/authentication.md):

  • Importar cookies desde una instancia de Chrome con depuración activada en la que ya hayas iniciado sesión
  • Recorrer formularios de login estándar usando snapshots y fill/click
  • Manejar autenticación basada en cookies, auth básica HTTP y refresh de tokens

En flujos complejos de OAuth o 2FA, puede seguir siendo necesario que una persona intervenga en la configuración inicial; después, agent-browser puede reutilizar el estado autenticado guardado.

Proxy support and network configuration

Si necesitas enrutar el tráfico a través de un proxy (para pruebas por ubicación, limitación de tasa o entornos corporativos), usa las opciones documentadas en references/proxy-support.md:

• HTTP/HTTPS proxy via CLI flag

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

• Environment variable configuration

  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 automatización de tests e investigación de rendimiento, agent-browser puede capturar trazas de rendimiento de Chrome (ver 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

Puedes abrir el trace.json resultante en Chrome DevTools (pestaña Performance) o en visores compatibles para analizar la ejecución de JavaScript, el renderizado y eventos de temporización de usuario.

Video recording for debugging and documentation

agent-browser puede grabar un video de la sesión de navegador, lo que es útil para depurar automatizaciones que fallan o crear guías paso a paso (ver 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

Puedes incrustar estos archivos .webm en documentación, compartirlos con tu equipo o adjuntarlos a informes de bugs.

Using templates for common workflows

El repositorio incluye plantillas de scripts de shell en el directorio templates/ para ayudarte a construir flujos de trabajo repetibles:

• templates/form-automation.sh – patrón estructurado para rellenar y enviar formularios
• templates/authenticated-session.sh – ejemplo para iniciar sesión y persistir el estado de la sesión
• templates/capture-workflow.sh – patrón para hacer snapshots o grabar un flujo de varios pasos

Puedes copiar y adaptar estos scripts a tu propio entorno, jobs de CI o pipelines de agentes.

FAQ

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

agent-browser controla una instancia real de Chrome/Chromium mediante CDP. Esto significa que puede manejar:

• Renderizado del lado del cliente y JavaScript complejo
• Single-page apps que dependen de APIs del navegador
• Interacciones reales de usuario como clics, escritura y pulsación de teclas
• Tiempos visuales, comportamiento de renderizado y trazas de rendimiento

Si solo necesitas HTML o JSON en bruto de endpoints básicos, un cliente HTTP puede ser suficiente. Para cualquier cosa que deba comportarse como un usuario real en un navegador, agent-browser es más adecuado.

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

Después de instalar la CLI con npm, Homebrew o Cargo, ejecuta:

agent-browser install

Esto descarga y configura una versión compatible de Chrome/Chromium que agent-browser puede controlar vía CDP. Cuando se publique una nueva versión, actualiza con:

agent-browser upgrade

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

Sí. references/authentication.md explica cómo iniciar Chrome con --remote-debugging-port e importar cookies desde una sesión en la que ya hayas iniciado sesión. Una vez importado, puedes guardar ese estado autenticado con agent-browser state save y restaurarlo más tarde sin repetir todo el flujo de login.

Is agent-browser suitable for CI and automated testing?

Sí. agent-browser es una herramienta de línea de comandos que funciona bien en entornos automatizados siempre que Chrome/Chromium esté disponible. Puedes:

• Ejecutar flujos end-to-end como parte de tus suites de tests
• Capturar trazas de rendimiento durante los builds
• Grabar videos de escenarios que fallen

Para CI, usa el método de instalación que coincida con tu imagen de build (npm, Homebrew o Cargo) y luego scripta tus flujos usando scripts de shell o tu framework de agentes.

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

En lugar de volcar el DOM completo, agent-browser proporciona snapshots compactos con @refs estables para los elementos importantes (enlaces, botones, inputs, etc.). Esto reduce drásticamente el uso de tokens y facilita que un agente de IA pueda:

• Entender la estructura de la página
• Seleccionar el elemento correcto por ref
• Enviar comandos precisos de click, fill y press

references/snapshot-refs.md explica cómo se generan los refs, cuándo refrescarlos y las mejores prácticas para una automatización robusta.

Does agent-browser support proxies and corporate networks?

Sí. Puedes configurar proxies HTTP, HTTPS y SOCKS tanto mediante flags de CLI (--proxy) como a través de variables de entorno (HTTP_PROXY, HTTPS_PROXY, ALL_PROXY). references/proxy-support.md cubre la configuración básica, proxies con autenticación, reglas de bypass y consejos de resolución de problemas.

Where should I start in the repository to learn more?

Para profundizar de forma práctica en agent-browser:

• Empieza por SKILL.md para una visión general y un quick start
• Lee references/commands.md para ver la lista completa de comandos y opciones
• Revisa references/authentication.md, references/session-management.md, references/snapshot-refs.md, references/profiling.md y references/video-recording.md para temas específicos
• Explora el directorio templates/ para scripts de flujo de trabajo listos para usar que puedas adaptar a tus propios casos de uso