Automatización de navegador con agent-browser
La CLI usa Chrome/Chromium directamente mediante CDP. Instálala con npm i -g agent-browser, brew install agent-browser, o cargo install agent-browser. Ejecuta agent-browser install para descargar Chrome.
Flujo de trabajo principal
Cada automatización de navegador sigue este patrón:
- Navegar:
agent-browser open <url> - Capturar estado:
agent-browser snapshot -i(obtiene referencias de elementos como@e1,@e2) - Interactuar: Usa las referencias para hacer clic, llenar, seleccionar
- Re-capturar: Después de la navegación o cambios en el DOM, obtén referencias frescas
agent-browser open https://example.com/form
agent-browser snapshot -i
# Salida: @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
Encadenamiento de comandos
Los comandos se pueden encadenar con && en una sola invocación de shell. El navegador persiste entre comandos mediante un demonio en segundo plano, por lo que el encadenamiento es seguro y más eficiente que llamadas separadas.
# Encadenar open + wait + snapshot en una sola llamada
agent-browser open https://example.com && agent-browser wait --load networkidle && agent-browser snapshot -i
# Encadenar múltiples interacciones
agent-browser fill @e1 "[email protected]" && agent-browser fill @e2 "password123" && agent-browser click @e3
# Navegar y capturar
agent-browser open https://example.com && agent-browser wait --load networkidle && agent-browser screenshot page.png
Cuándo encadenar: Usa && cuando no necesites leer la salida de un comando intermedio antes de continuar (por ejemplo, open + wait + screenshot). Ejecuta comandos por separado cuando necesites analizar la salida primero (por ejemplo, snapshot para descubrir referencias, luego interactuar usando esas referencias).
Manejo de autenticación
Al automatizar un sitio que requiere inicio de sesión, elige el enfoque que se adapte:
Opción 1: Importar autenticación desde el navegador del usuario (más rápido para tareas únicas)
# Conectarse al Chrome en ejecución del usuario (ya ha iniciado sesión)
agent-browser --auto-connect state save ./auth.json
# Usar ese estado de autenticación
agent-browser --state ./auth.json open https://app.example.com/dashboard
Los archivos de estado contienen tokens de sesión en texto plano: agrégalos a .gitignore y elimínalos cuando ya no sean necesarios. Establece AGENT_BROWSER_ENCRYPTION_KEY para cifrado en reposo.
Opción 2: Perfil persistente (más simple para tareas recurrentes)
# Primera ejecución: iniciar sesión manualmente o mediante automatización
agent-browser --profile ~/.myapp open https://app.example.com/login
# ... llenar credenciales, enviar ...
# Todas las ejecuciones futuras: ya autenticado
agent-browser --profile ~/.myapp open https://app.example.com/dashboard
Opción 3: Nombre de sesión (guardar/restaurar automáticamente cookies + localStorage)
agent-browser --session-name myapp open https://app.example.com/login
# ... flujo de inicio de sesión ...
agent-browser close # Estado guardado automáticamente
# Próxima vez: estado restaurado automáticamente
agent-browser --session-name myapp open https://app.example.com/dashboard
Opción 4: Bóveda de autenticación (credenciales almacenadas cifradas, inicio de sesión por nombre)
echo "$PASSWORD" | agent-browser auth save myapp --url https://app.example.com/login --username user --password-stdin
agent-browser auth login myapp
Opción 5: Archivo de estado (guardar/cargar manualmente)
# Después de iniciar sesión:
agent-browser state save ./auth.json
# En una sesión futura:
agent-browser state load ./auth.json
agent-browser open https://app.example.com/dashboard
Consulta references/authentication.md para patrones de OAuth, 2FA, autenticación basada en cookies y renovación de tokens.
Comandos esenciales
# Navegación
agent-browser open <url> # Navegar (alias: goto, navigate)
agent-browser close # Cerrar navegador
# Captura de estado (snapshot)
agent-browser snapshot -i # Elementos interactivos con referencias (recomendado)
agent-browser snapshot -i -C # Incluir elementos interactivos con cursor (divs con onclick, cursor:pointer)
agent-browser snapshot -s "#selector" # Limitar a selector CSS
# Interacción (usar @refs del snapshot)
agent-browser click @e1 # Hacer clic en elemento
agent-browser click @e1 --new-tab # Hacer clic y abrir en nueva pestaña
agent-browser fill @e2 "texto" # Limpiar y escribir texto
agent-browser type @e2 "texto" # Escribir sin limpiar
agent-browser select @e1 "opción" # Seleccionar opción de menú desplegable
agent-browser check @e1 # Marcar casilla de verificación
agent-browser press Enter # Presionar tecla
agent-browser keyboard type "texto" # Escribir en el elemento enfocado (sin selector)
agent-browser keyboard inserttext "texto" # Insertar sin eventos de teclado
agent-browser scroll down 500 # Desplazar página
agent-browser scroll down 500 --selector "div.content" # Desplazar dentro de un contenedor específico
# Obtener información
agent-browser get text @e1 # Obtener texto de elemento
agent-browser get url # Obtener URL actual
agent-browser get title # Obtener título de página
agent-browser get cdp-url # Obtener URL del WebSocket CDP
# Espera
agent-browser wait @e1 # Esperar elemento
agent-browser wait --load networkidle # Esperar red inactiva
agent-browser wait --url "**/page" # Esperar patrón de URL
agent-browser wait 2000 # Esperar milisegundos
agent-browser wait --text "Bienvenido" # Esperar que aparezca texto (coincidencia de subcadena)
agent-browser wait --fn "!document.body.innerText.includes('Cargando...')" # Esperar que desaparezca texto
agent-browser wait "#spinner" --state hidden # Esperar que el elemento desaparezca
# Descargas
agent-browser download @e1 ./file.pdf # Hacer clic en elemento para iniciar descarga
agent-browser wait --download ./output.zip # Esperar que cualquier descarga se complete
agent-browser --download-path ./downloads open <url> # Establecer directorio predeterminado de descargas
# Viewport y emulación de dispositivos
agent-browser set viewport 1920 1080 # Establecer tamaño viewport (predeterminado: 1280x720)
agent-browser set viewport 1920 1080 2 # 2x retina (mismo tamaño CSS, capturas de mayor resolución)
agent-browser set device "iPhone 14" # Emular dispositivo (viewport + user agent)
# Captura
agent-browser screenshot # Captura de pantalla en directorio temporal
agent-browser screenshot --full # Captura de pantalla de página completa
agent-browser screenshot --annotate # Captura anotada con etiquetas numeradas de elementos
agent-browser screenshot --screenshot-dir ./shots # Guardar en directorio personalizado
agent-browser screenshot --screenshot-format jpeg --screenshot-quality 80
agent-browser pdf output.pdf # Guardar como PDF
# Portapapeles
agent-browser clipboard read # Leer texto del portapapeles
agent-browser clipboard write "¡Hola, Mundo!" # Escribir texto en el portapapeles
agent-browser clipboard copy # Copiar selección actual
agent-browser clipboard paste # Pegar desde el portapapeles
# Diferencia (comparar estados de página)
agent-browser diff snapshot # Comparar snapshot actual vs último
agent-browser diff snapshot --baseline before.txt # Comparar actual vs archivo guardado
agent-browser diff screenshot --baseline before.png # Diferencia visual de píxeles
agent-browser diff url <url1> <url2> # Comparar dos páginas
agent-browser diff url <url1> <url2> --wait-until networkidle # Estrategia de espera personalizada
agent-browser diff url <url1> <url2> --selector "#main" # Limitar a elemento
Patrones comunes
Envío de formularios
agent-browser open https://example.com/signup
agent-browser snapshot -i
agent-browser fill @e1 "María García"
agent-browser fill @e2 "[email protected]"
agent-browser select @e3 "California"
agent-browser check @e4
agent-browser click @e5
agent-browser wait --load networkidle
Autenticación con bóveda de autenticación (Recomendado)
# Guardar credenciales una vez (cifradas con AGENT_BROWSER_ENCRYPTION_KEY)
# Recomendado: pasar contraseña por stdin para evitar exposición en historial de shell
echo "pass" | agent-browser auth save github --url https://github.com/login --username user --password-stdin
# Iniciar sesión usando perfil guardado (el LLM nunca ve la contraseña)
agent-browser auth login github
# Listar/mostrar/eliminar perfiles
agent-browser auth list
agent-browser auth show github
agent-browser auth delete github
Autenticación con persistencia de estado
# Iniciar sesión una vez y guardar 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 en sesiones futuras
agent-browser state load auth.json
agent-browser open https://app.example.com/dashboard
Persistencia de sesión
# Guardar/restaurar automáticamente cookies y localStorage al reiniciar el navegador
agent-browser --session-name myapp open https://app.example.com/login
# ... flujo de inicio de sesión ...
agent-browser close # Estado guardado en ~/.agent-browser/sessions/
# La próxima vez, el estado se carga automáticamente
agent-browser --session-name myapp open https://app.example.com/dashboard
# Cifrar estado en reposo
export AGENT_BROWSER_ENCRYPTION_KEY=$(openssl rand -hex 32)
agent-browser --session-name secure open https://app.example.com
# Gestionar estados guardados
agent-browser state list
agent-browser state show myapp-default.json
agent-browser state clear myapp
agent-browser state clean --older-than 7
Extracción de datos
agent-browser open https://example.com/products
agent-browser snapshot -i
agent-browser get text @e5 # Obtener texto de elemento específico
agent-browser get text body > page.txt # Obtener todo el texto de la página
# Salida JSON para análisis
agent-browser snapshot -i --json
agent-browser get text @e1 --json
Sesiones 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
Conectarse a Chrome existente
# Descubrir automáticamente Chrome en ejecución con depuración remota habilitada
agent-browser --auto-connect open https://example.com
agent-browser --auto-connect snapshot
# O con puerto CDP explícito
agent-browser --cdp 9222 snapshot
Esquema de colores (Modo oscuro)
# Modo oscuro persistente mediante bandera (aplica a todas las páginas y nuevas pestañas)
agent-browser --color-scheme dark open https://example.com
# O mediante variable de entorno
AGENT_BROWSER_COLOR_SCHEME=dark agent-browser open https://example.com
# O establecer durante la sesión (persiste para comandos posteriores)
agent-browser set media dark
Viewport y pruebas responsivas
# Establecer un tamaño de viewport personalizado (predeterminado es 1280x720)
agent-browser set viewport 1920 1080
agent-browser screenshot desktop.png
# Probar diseño de ancho móvil
agent-browser set viewport 375 812
agent-browser screenshot mobile.png
# Retina/HiDPI: mismo diseño CSS con densidad de píxeles 2x
# Las capturas de pantalla mantienen el tamaño lógico del viewport, pero el contenido se renderiza a mayor DPI
agent-browser set viewport 1920 1080 2
agent-browser screenshot retina.png
# Emulación de dispositivo (establece viewport + user agent en un solo paso)
agent-browser set device "iPhone 14"
agent-browser screenshot device.png
El parámetro scale (3er argumento) establece window.devicePixelRatio sin cambiar el diseño CSS. Úsalo al probar renderizado retina o capturar capturas de pantalla de mayor resolución.
Navegador visual (Depuración)
agent-browser --headed open https://example.com
agent-browser highlight @e1 # Resaltar elemento
agent-browser inspect # Abrir Chrome DevTools para la página activa
agent-browser record start demo.webm # Grabar sesión
agent-browser profiler start # Iniciar perfilado de Chrome DevTools
agent-browser profiler stop trace.json # Detener y guardar perfil (ruta opcional)
Usa AGENT_BROWSER_HEADED=1 para habilitar el modo con navegador visible mediante variable de entorno. Las extensiones del navegador funcionan tanto en modo con navegador visible como sin interfaz gráfica.
Archivos locales (PDFs, HTML)
# Abrir archivos locales con URLs file://
agent-browser --allow-file-access open file:///ruta/al/documento.pdf
agent-browser --allow-file-access open file:///ruta/a/pagina.html
agent-browser screenshot output.png
Simulador de iOS (Mobile Safari)
# Listar simuladores iOS disponibles
agent-browser device list
# Iniciar Safari en un dispositivo específico
agent-browser -p ios --device "iPhone 16 Pro" open https://example.com
# Mismo flujo de trabajo que en escritorio: snapshot, interactuar, re-snapshot
agent-browser -p ios snapshot -i
agent-browser -p ios tap @e1 # Tocar (alias de click)
agent-browser -p ios fill @e2 "texto"
agent-browser -p ios swipe up # Gesto específico de móvil
# Tomar captura de pantalla
agent-browser -p ios screenshot mobile.png
# Cerrar sesión (apaga el simulador)
agent-browser -p ios close
Requisitos: macOS con Xcode, Appium (npm install -g appium && appium driver install xcuitest)
Dispositivos reales: Funciona con dispositivos iOS físicos si están preconfigurados. Usa --device "<UDID>" donde UDID proviene de xcrun xctrace list devices.
Seguridad
Todas las características de seguridad son optativas. Por defecto, agent-browser no impone restricciones en navegación, acciones o salida.
Límites de contenido (Recomendado para agentes de IA)
Habilita --content-boundaries para envolver la salida proveniente de la página en marcadores que ayuden a los LLM a distinguir la salida de la herramienta del contenido no confiable de la página:
export AGENT_BROWSER_CONTENT_BOUNDARIES=1
agent-browser snapshot
# Salida:
# --- AGENT_BROWSER_PAGE_CONTENT nonce=<hex> origin=https://example.com ---
# [árbol de accesibilidad]
# --- END_AGENT_BROWSER_PAGE_CONTENT nonce=<hex> ---
Lista de dominios permitidos
Restringe la navegación a dominios de confianza. Los comodines como *.example.com también coinciden con el dominio base example.com. Las solicitudes de subrecursos, conexiones WebSocket y EventSource a dominios no permitidos también se bloquean. Incluye los dominios CDN de los que dependen tus páginas objetivo:
export AGENT_BROWSER_ALLOWED_DOMAINS="*.example.com,*.api.example.com,cdn.example.com"
agent-browser open https://app.example.com/dashboard
# Navegación bloqueada si intenta ir a https://malicious-site.com
Ayuda de comandos
agent-browser --help # Ayuda general
agent-browser open --help # Ayuda de subcomando specifico
Referencias
- Autenticación - OAuth, 2FA, cookies, renovación de tokens
- API de JavaScript - Usar agent-browser como librería
- API de servidor MCP - Integración con protocolo Model Context Protocol
- Extensión de VSCode - Usar agent-browser en VSCode
- Solución de problemas - Problemas comunes y soluciones
Nota: agent-browser está diseñado para ser eficiente manteniendo el navegador abierto entre invocaciones de comandos, evitando reinicios costosos. Siempre que sea posible, encadena comandos cuando no necesites leer la salida de un comando intermedio.