Automatización de navegador con agent-browser
El CLI usa Chrome/Chromium directamente a través de CDP. Instálalo con npm i -g agent-browser, brew install agent-browser o cargo install agent-browser. Ejecuta agent-browser install para descargar Chrome. Las instalaciones existentes de Chrome, Brave, Playwright y Puppeteer se detectan automáticamente. Ejecuta agent-browser upgrade para actualizar a la última versión.
Flujo de trabajo principal
Cada automatización de navegador sigue este patrón:
- Navegar:
agent-browser open <url> - Instantánea:
agent-browser snapshot -i(obtén referencias de elementos como@e1,@e2) - Interactuar: Usa las referencias para hacer clic, rellenar, seleccionar
- Re-instantánea: Después de navegar 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 2000
agent-browser snapshot -i # Verificar resultado
Encadenamiento de comandos
Los comandos se pueden encadenar con && en una sola invocación del shell. El navegador persiste entre comandos a través de un daemon en segundo plano, por lo que el encadenamiento es seguro y más eficiente que llamadas separadas.
# Encadenar open + snapshot en una llamada (open ya espera a que cargue la página)
agent-browser open https://example.com && 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 screenshot
Cuándo encadenar: Usa && cuando no necesites leer la salida de un comando intermedio antes de continuar (p. ej., open + wait + screenshot). Ejecuta los comandos por separado cuando necesites analizar primero la salida (p. ej., instantánea 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 puntuales)
# Conectarse al Chrome 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. Configura AGENT_BROWSER_ENCRYPTION_KEY para cifrado en reposo.
Opción 2: Reutilización de perfil de Chrome (sin configuración)
# Listar perfiles de Chrome disponibles
agent-browser profiles
# Reutilizar el estado de inicio de sesión existente del usuario
agent-browser --profile Default open https://gmail.com
Opción 3: Perfil persistente (para tareas recurrentes)
# Primera ejecución: iniciar sesión manualmente o mediante automatización
agent-browser --profile ~/.myapp open https://app.example.com/login
# ... rellenar credenciales, enviar ...
# Todas las ejecuciones futuras: ya autenticado
agent-browser --profile ~/.myapp open https://app.example.com/dashboard
Opción 4: 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 5: 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
auth login navega con load y luego espera a que aparezcan los selectores del formulario de inicio de sesión antes de rellenar/hacer clic, lo cual es más confiable en pantallas de inicio de sesión de SPA con retardo.
Opción 6: Archivo de estado (guardar/cargar manual)
# 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 actualización de tokens.
Comandos esenciales
# Lote: USA SIEMPRE batch para 2+ comandos secuenciales. Los comandos se ejecutan en orden.
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"
# Navegación
agent-browser open <url> # Navegar (alias: goto, navigate)
agent-browser close # Cerrar navegador
agent-browser close --all # Cerrar todas las sesiones activas
# Instantánea
agent-browser snapshot -i # Elementos interactivos con referencias (recomendado)
agent-browser snapshot -i --urls # Incluir URLs href para enlaces
agent-browser snapshot -s "#selector" # Limitar a selector CSS
# Interacción (usa @refs de la instantánea)
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 desplegable
agent-browser check @e1 # Marcar casilla de verificación
agent-browser press Enter # Pulsar tecla
agent-browser keyboard type "texto" # Escribir en el foco actual (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 del elemento
agent-browser get url # Obtener URL actual
agent-browser get title # Obtener título de la página
agent-browser get cdp-url # Obtener URL del WebSocket CDP
# Esperar
agent-browser wait @e1 # Esperar por elemento
agent-browser wait 2000 # Esperar milisegundos
agent-browser wait --url "**/page" # Esperar por patrón de URL
agent-browser wait --text "Bienvenido" # Esperar a que aparezca texto (coincidencia de subcadena)
agent-browser wait --load networkidle # Esperar a que la red esté inactiva (precaución: ver Errores comunes)
agent-browser wait --fn "!document.body.innerText.includes('Cargando...')" # Esperar a que desaparezca texto
agent-browser wait "#spinner" --state hidden # Esperar a 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 a que se complete cualquier descarga
agent-browser --download-path ./downloads open <url> # Establecer directorio de descarga predeterminado
# Gestión de pestañas
agent-browser tab list # Listar todas las pestañas abiertas
agent-browser tab new # Abrir una pestaña en blanco
agent-browser tab new https://example.com # Abrir URL en una nueva pestaña
agent-browser tab 2 # Cambiar a pestaña por índice (base 0)
agent-browser tab close # Cerrar la pestaña actual
agent-browser tab close 2 # Cerrar pestaña por índice
# Red
agent-browser network requests # Inspeccionar solicitudes 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 estado (200, 2xx, 400-499)
agent-browser network request <requestId> # Ver detalle completo de solicitud/respuesta
agent-browser network route "**/api/*" --abort # Bloquear solicitudes coincidentes
agent-browser network har start # Iniciar grabación HAR
agent-browser network har stop ./capture.har # Detener y guardar archivo HAR
# Viewport y emulación de dispositivos
agent-browser set viewport 1920 1080 # Establecer tamaño de 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 + agente de usuario)
# Captura
agent-browser screenshot # Captura de pantalla en directorio temporal
agent-browser screenshot --full # Captura de página completa
agent-browser screenshot --annotate # Captura anotada con etiquetas de elementos numeradas
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
# Vista previa en vivo / streaming
agent-browser stream enable # Iniciar streaming WebSocket en tiempo real en un puerto autoseleccionado
agent-browser stream enable --port 9223 # Vincular un puerto localhost específico
agent-browser stream status # Inspeccionar estado habilitado, puerto, conexión y screencasting
agent-browser stream disable # Detener streaming en tiempo real y eliminar el archivo de metadatos .stream
# 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
# Diálogos (alert, confirm, prompt, beforeunload)
# De forma predeterminada, los diálogos alert y beforeunload se aceptan automáticamente para que nunca bloqueen al agente.
# Los diálogos confirm y prompt aún requieren manejo explícito.
# Usa --no-auto-dialog (o AGENT_BROWSER_NO_AUTO_DIALOG=1) para deshabilitar el manejo automático.
agent-browser dialog accept # Aceptar diálogo
agent-browser dialog accept "mi entrada" # Aceptar diálogo prompt con texto
agent-browser dialog dismiss # Rechazar/cancelar diálogo
agent-browser dialog status # Verificar si hay un diálogo abierto actualmente
# Diff (comparar estados de página)
agent-browser diff snapshot # Comparar instantánea actual con la anterior
agent-browser diff snapshot --baseline before.txt # Comparar actual con 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
# Chat (control por lenguaje natural con IA)
agent-browser chat "abre google.com y busca gatos" # Instrucción única
agent-browser chat # Modo REPL interactivo
agent-browser -q chat "resume esta página" # Silencioso (solo texto, sin llamadas a herramientas)
agent-browser -v chat "rellena el formulario de inicio de sesión" # Verboso (muestra salida de comandos)
agent-browser --model openai/gpt-4o chat "toma una captura de pantalla" # Sobrescribir modelo
Streaming
Cada sesión inicia automáticamente un servidor de streaming WebSocket en un puerto asignado por el SO. Usa agent-browser stream status para ver el puerto enlazado y el estado de la conexión. Usa stream disable para detenerlo, y stream enable --port <puerto> para re-habilitarlo en un puerto específico.
Ejecución por lotes
Usa SIEMPRE batch cuando ejecutes 2+ comandos en secuencia. Batch ejecuta los comandos en orden, por lo que los comandos dependientes (como navegar y luego capturar) funcionan correctamente. Cada argumento entre comillas es un comando separado.
# Navegar y tomar una instantánea
agent-browser batch "open https://example.com" "snapshot -i"
# Navegar, instantánea y captura en una llamada
agent-browser batch "open https://example.com" "snapshot -i" "screenshot"
# Hacer clic, esperar y luego capturar
agent-browser batch "click @e1" "wait 1000" "screenshot"
# Con --bail para detenerse en el primer error
agent-browser batch --bail "open https://example.com" "click @e1" "screenshot"
Usa un solo comando (no batch) solo cuando necesites leer la salida antes de decidir el siguiente comando. Por ejemplo, debes ejecutar snapshot -i como un comando individual cuando necesites leer las referencias para decidir en qué hacer clic. Después de leer la instantánea, agrupa los pasos restantes.
El modo Stdin también es compatible para uso programático:
echo '[["open","https://example.com"],["screenshot"]]' | agent-browser batch --json
agent-browser batch --bail < commands.json
Estrategias de eficiencia
Estos patrones minimizan las llamadas a herramientas y el uso de tokens.
Usa --urls para evitar re-navegación. Cuando necesites visitar enlaces desde una página, usa snapshot -i --urls para obtener todas las URLs href de antemano. Luego abre cada URL directamente en lugar de hacer clic en referencias y navegar de vuelta.
Instantánea una vez, actúa muchas veces. Nunca vuelvas a tomar una instantánea de la misma página. Extrae toda la información necesaria (referencias, URLs, texto) de una sola instantánea y luego agrupa las acciones restantes.
Flujo de trabajo multipágina (p. ej., "visita N sitios y captura cada uno"):
# 1. Obtener todas las URLs en una llamada
agent-browser batch "open https://news.ycombinator.com" "snapshot -i --urls"
# Leer la salida para extraer URLs, luego visitar cada una directamente:
# 2. Un lote por sitio destino
agent-browser batch "open https://github.com/example/repo" "screenshot"
agent-browser batch "open https://example.com/articulo" "screenshot"
agent-browser batch "open https://other.com/pagina" "screenshot"
Este enfoque usa 4 llamadas a herramientas en lugar de 14+. Nunca vuelvas a la página de listado entre visitas.
Patrones comunes
Envío de formularios
# Navegar y obtener la estructura del formulario
agent-browser batch "open https://example.com/registro" "snapshot -i"
# Leer la salida de la instantánea para identificar referencias del formulario, luego rellenar y enviar
agent-browser batch "fill @e1 \"Juan Pérez\"" "fill @e2 \"[email protected]\"" "select @e3 \"California\"" "check @e4" "click @e5" "wait 2000"
Autenticación con bóveda de autenticación (recomendado)
# Guardar credenciales una vez (cifradas con AGENT_BROWSER_ENCRYPTION_KEY)
# Recomendado: pasar la contraseña por stdin para evitar exponerla en el historial del shell
echo "pass" | agent-browser auth save github --url https://github.com/login --username user --password-stdin
# Iniciar sesión usando el perfil guardado (el LLM nunca ve la contraseña)
agent-browser auth login github
# Listar/mostrar/eliminar perfiles
agent-browser auth list
a
...
[truncado para traducción]