Visual Browser Agent

Una herramienta de automatización de navegador local-first que da a los agentes de IA "ojos y manos" para la interacción web. Visual Browser Agent es Playwright más un plano de control de agente: Playwright realiza el trabajo del navegador, mientras que este proyecto añade herramientas MCP, evidencia visual, aprobaciones, manejo de identidad de Chrome, controles de seguridad y flujos de trabajo para agentes de codificación y tareas cotidianas del navegador.

Qué ocurre después de la instalación

No necesitas entender Chromium, CDP, depuración remota ni los nombres internos de los perfiles de Chrome.

Un instalador técnico registra Visual Browser Agent con el agente de codificación que uses e instala el runtime de Playwright. Después, tu flujo de trabajo normal ocurre en el chat del agente de codificación. Puedes decir:

Use the browser to open this website and check the layout.

El agente primero comprueba si hay una sesión de Chrome existente disponible. Si encuentra una, usa esa sesión; de lo contrario, lanza una sesión limpia de Chromium gestionada por Playwright. También puedes ser explícito en lenguaje ordinario:

Use my Work Chrome account and check the dashboard.

El agente descubre identidades amigables de Chrome como "Trabajo — work@example.com" y "Personal — personal@example.com". Si hay más de una identidad posible, te pide que elijas en la conversación. No ejecutas un comando de perfil ni seleccionas Profile 3.

Visual Browser Agent también incluye un panel de control local opcional. Un usuario técnico puede iniciarlo con npx visual-browser-agent dashboard, pero el panel de control no es necesario para el uso normal. Muestra el estado de la conexión, la pestaña activa, las identidades de Chrome disponibles y la evidencia reciente en http://127.0.0.1:8787/.

Antes de que el agente inicie sesión, envíe un mensaje, publique, compre, elimine, envíe o cambie datos externos, se detiene y pide aprobación. La inspección de solo lectura, las capturas de pantalla, las auditorías visuales y la captura de evidencia pueden proceder automáticamente.

Related MCP server: websight

Cómo funciona

Hay dos navegadores y dos métodos de conexión:

Instalación

Opción 1: Pide a tu agente de codificación que lo instale

En Claude Code, Cursor, Copilot, Codex, Gemini, Windsurf, Cline, Roo, Kiro, Goose, OpenCode, Antigravity u otro agente de codificación compatible con MCP, pregunta:

Install Visual Browser Agent, set it up for this coding agent, and check that the browser runtime is ready. Ask me before installing software or changing browser settings.

El agente debe comprobar el estado de la configuración, pedir confirmación antes de instalar Playwright Chromium, registrar el servidor MCP e informar de cualquier paso de permiso o extensión que falte. Luego puedes simplemente decir "usa el navegador para …".

Opción 2: Desde GitHub (Recomendado para pruebas)

# Clone the repo
git clone https://github.com/Akakaui/visual-browser-agent.git
cd visual-browser-agent

# Install dependencies
npm install

# Build
npm run build

# Initialize (installs Chromium + MCP + skills)
npx visual-browser-agent init

O úsalo directamente con npx:

npx github:Akakaui/visual-browser-agent init

Opción 3: Desde npm (Después de publicar)

# Install globally
npm install -g visual-browser-agent

# Or use directly with npx
npx visual-browser-agent init

Opción 4: Desarrollo local

# Clone the repo
git clone https://github.com/Akakaui/visual-browser-agent.git
cd visual-browser-agent

# Install in development mode
npm install

# Build
npm run build

# Link for global use
npm link

# Now you can use it anywhere
visual-browser-agent init

Inicio rápido

1. Inicializar

npx visual-browser-agent init

Esto hará lo siguiente:

• Instalar Chromium (navegador de Playwright)

• Configurar MCP

• Instalar habilidades de agente

• Detectar automáticamente tu agente de codificación e instalar el wrapper

2. Empezar a usar

# Start MCP server with Chromium (default)
npx visual-browser-agent mcp

# Or start with Chrome extension
npx visual-browser-agent mcp --extension

3. Usar en tu agente de IA

Pregunta a tu agente: "Investiga el diseño de este sitio web"

El agente usará Visual Browser Agent para controlar el navegador.

Usar tu Chrome existente (Extensión)

Para el tutorial completo de usuario normal con cambio de perfil, verificación y solución de problemas, consulta EXTENSION_INSTALLATION.md.

Si necesitas que tu agente use tu Chrome existente (con tus inicios de sesión, cookies y sesiones):

1. Instalar la extensión

1. Abre Chrome → chrome://extensions/

2. Activa el modo de desarrollador

3. Haz clic en Cargar descomprimida

4. Selecciona: node_modules/visual-browser-agent/browser-extension

2. Iniciar el agente

npx visual-browser-agent mcp --extension

3. Usar en tu agente de IA

Pregunta a tu agente: "Inicia sesión en mi Gmail y resume mis correos"

El agente se conecta a tu Chrome con todos tus inicios de sesión intactos.

Integración con agentes de IA

Detección automática (Recomendada)

Cuando ejecutas npx visual-browser-agent init, automáticamente:

• Detecta qué agente de codificación estás usando

• Instala el wrapper adecuado

• Configura MCP

Instalación manual

Si la detección automática no funciona, puedes instalar manualmente:

# Install for specific agent
npx visual-browser-agent host <agent-name>

Agentes compatibles:

• claude-code

• cursor

• gemini

• opencode

• antigravity

• windsurf

• cline

• roo

• kiro

• copilot

• codex

• goose

Claude Code

Añade a .claude/settings.json:

{
  "mcpServers": {
    "visual-browser": {
      "command": "npx",
      "args": ["visual-browser-agent", "mcp"]
    }
  }
}

Cursor

Añade a .cursor/mcp.json:

{
  "mcpServers": {
    "visual-browser": {
      "command": "npx",
      "args": ["visual-browser-agent", "mcp"]
    }
  }
}

Para el modo de extensión de Chrome

{
  "mcpServers": {
    "visual-browser": {
      "command": "npx",
      "args": ["visual-browser-agent", "mcp", "--extension"]
    }
  }
}

Cómo usan esto los agentes de IA

Escenario 1: Investigar un sitio web público

El agente piensa: "Este es un sitio web público, no necesita inicio de sesión."

El agente hace: Usa Chromium (por defecto)

npx visual-browser-agent mcp

Escenario 2: Acceder a datos privados del usuario

El agente piensa: "Esto necesita el inicio de sesión del usuario."

El agente hace: Usa Chrome mediante la extensión

npx visual-browser-agent mcp --extension

Escenario 3: El usuario especifica el navegador

El usuario dice: "Usa mi cuenta de Chrome de Trabajo con sesión iniciada"

El agente hace:

npx visual-browser-agent mcp --choose-profile

Referencia de comandos

Panel de control para usuarios normales

Para un usuario no técnico, el agente de navegador debe instalarse y registrarse una vez por un administrador o mediante la configuración del agente de codificación. Luego, el usuario trabaja desde el agente de codificación diciendo "usa el navegador para abrir este sitio web", "usa mi cuenta de Trabajo" o "revisa la página y muéstrame capturas de pantalla". El agente gestiona la conexión, el descubrimiento de identidad, la evidencia y las aprobaciones a través de MCP.

El panel de control local opcional está disponible para la visibilidad y recuperación de la conexión. Un usuario técnico puede iniciarlo con npx visual-browser-agent dashboard; se abre en http://127.0.0.1:8787/ y muestra el estado de la conexión, identidades amigables de Chrome, la pestaña activa y evidencia reciente. El panel es solo local y no reemplaza la conversación con el agente de codificación.

Superficie de compatibilidad con Playwright 2.0

Visual Browser Agent expone una superficie MCP respaldada por Playwright para flujos de trabajo de agentes. Además de navegación, formularios, subidas, descargas, capturas de pantalla, grabación, auditorías responsivas y estudios visuales, los agentes pueden usar pestañas/páginas, historial, arrastrar y soltar, referencias de localizadores, aserciones web-first, inspección de marcos, política de diálogos, cookies, exportación aprobada del estado de almacenamiento, mensajes recientes de consola, solicitudes de red recientes, mocks de enrutamiento de URL, trazado, emulación de medios, evidencia en PDF y evaluación de página con confirmación.

La capa de compatibilidad mantiene intencionalmente explícitas las operaciones sensibles. Borrar cookies requiere confirm=true; la evaluación de página requiere confirmDangerous=true; los envíos públicos y la eliminación de artefactos siguen gobernados por el servicio de aprobación. Los mocks de red y los artefactos de almacenamiento están restringidos a la sesión activa del agente y a los directorios aprobados.

Perfiles

Si tienes varios perfiles de Chrome, elige la cuenta con sesión iniciada que quieras usar con la extensión:

# Choose an account interactively
npx visual-browser-agent mcp --choose-profile

# Advanced: use a known technical profile name
npx visual-browser-agent mcp --profile "Profile 3"

Solución de problemas

Chromium no funciona

npx playwright install chromium

La extensión de Chrome no se conecta

1. Asegúrate de que Chrome esté abierto

2. Comprueba que el icono de la extensión muestre "ON"

3. Prueba: npx visual-browser-agent doctor

El servidor MCP no se inicia

# Check environment
npx visual-browser-agent doctor

# Reinstall
npx visual-browser-agent init

Arquitectura

User's AI Agent (Claude Code, Cursor, etc.)
                    |
                    | MCP Protocol
                    |
        Visual Browser Agent MCP Server
                    |
        +-----------+-----------+
        |                       |
    Chromium                  Chrome
    (Playwright)            (Extension)
        |                       |
        v                       v
  Agent controls           Agent connects
  fresh browser            to existing browser

Licencia

MIT

Uso diario para usuarios no técnicos

Visual Browser Agent se puede usar en dos modos simples:

Un usuario no técnico no debería necesitar entender MCP. Después de una configuración, puede decirle a su agente de codificación lo que quiere en lenguaje ordinario, por ejemplo: "Abre el perfil de Chrome de Trabajo, inspecciona la página de pago en esta URL y guarda capturas de pantalla", o "Usa una sesión limpia de Chromium para comparar este sitio web en escritorio y móvil". El wrapper instruye al agente de codificación para que compruebe la conexión del navegador, elija el modo adecuado, pregunte antes de la autenticación o acciones importantes, y devuelva hallazgos concisos con evidencia.

Perfiles de Chrome: extensión versus depuración remota

Las extensiones de Chrome se instalan por perfil de Chrome, no una vez para cada ventana del navegador. Si una persona quiere usar tres perfiles de Chrome separados mediante el modo de extensión, debe abrir cada perfil, ir a chrome://extensions/, activar el modo de desarrollador y cargar el directorio browser-extension/ descomprimido una vez en cada perfil. La misma fuente de extensión se puede cargar en cada perfil, pero cada perfil debe otorgar sus propios permisos y permanecer abierto cuando se seleccione ese perfil.

La depuración remota es diferente. Se conecta a una instancia de Chrome lanzada con un --profile-directory y un puerto de depuración específicos. La mayoría de las personas deberían ejecutar visual-browser-agent mcp --choose-profile; la herramienta lee etiquetas de cuenta amigables de Chrome y permite al usuario seleccionar una por número. La opción técnica --profile sigue disponible para scripts y configuraciones avanzadas. Un perfil ya en uso por otro proceso de Chrome puede rechazar un segundo lanzamiento; cierra ese perfil primero o usa un perfil y puerto de depuración separados.

Para un usuario que necesita cookies de inicio de sesión existentes, la ruta de la extensión suele ser la más simple. Para un usuario que quiere un navegador limpio y repetible, Chromium es más seguro. La depuración remota debe tratarse como una opción avanzada porque expone la sesión del navegador seleccionada al proceso del agente local.

Seleccionar el agente de navegador mediante indicaciones

El usuario normalmente selecciona la tarea, no un modo de navegador o un modelo especialista. Diga «usa el navegador para …» en Claude, Cursor, Copilot, Codex, Gemini, Windsurf, Cline, Roo, Kiro, Goose, OpenCode, Antigravity u otro agente de codificación compatible con MCP. El wrapper indica al agente que use la selección automática de navegador, que descubra las identidades de Chrome visibles cuando sea necesario y que recurra a Chromium gestionado cuando no haya ninguna sesión existente disponible. El agente de codificación elige las herramientas MCP de Visual Browser Agent después de que se instale la integración. Los prompts deben indicar el requisito de sesión cuando sea relevante:

Use a clean Chromium browser. Audit this public website at desktop and mobile widths and save visual evidence.

Use the Work account I choose from Chrome. Open the internal dashboard, inspect the layout, and ask me before making any changes.

Use the current browser session. Do not submit forms, publish, purchase, delete, or send messages without asking for approval first.

Si un equipo quiere un especialista de navegador con nombre, ejecute visual-browser-agent host <agent-name> para el cliente de codificación y conserve la configuración MCP generada junto con el wrapper en ese proyecto. El paquete incluye adaptadores para Claude Code, Cursor, Gemini, Windsurf, Cline, Roo, Kiro, Copilot, Codex, Goose, OpenCode y Antigravity, y usa un wrapper universal para los hosts que no tienen un wrapper dedicado. Los hosts nuevos pueden usar la misma configuración MCP estándar: inicie el comando visual-browser-agent mcp --managed y regístrelo como servidor MCP llamado visual-browser.

Configuración recomendada para la primera vez

npm install
npm run build
npx visual-browser-agent init --mode chromium
npx visual-browser-agent host <your-coding-agent>

A continuación, reinicie el agente de codificación y pídale que use las herramientas de navegador visual. Para un flujo de trabajo diario limpio con Chromium, use visual-browser-agent mcp --managed. Para una identidad de Chrome existente, use visual-browser-agent mcp --choose-profile después de cargar la extensión en el perfil deseado. Use --profile solo para scripts avanzados.

El agente debe usar siempre la inspección de solo lectura y las capturas de pantalla automáticamente al revisar un sitio web. Debe solicitar aprobación explícita antes de publicar, editar, comprar, eliminar, enviar o modificar datos externos. La autenticación y la información personal privada deben ser proporcionadas por el usuario directamente en el navegador, no incluidas en prompts ni en archivos de configuración.

Artefactos del agente, paneles de artefactos, preguntas y aprobaciones

Para el flujo de trabajo completo de usuario normal y técnico, lea la Guía de usuario de Visual Browser Agent 1.0. La versión breve es que un agente de codificación interactúa con Visual Browser Agent a través de MCP: descubre las herramientas de navegador disponibles, selecciona las herramientas que coinciden con la solicitud del usuario y recibe texto, JSON estructurado, capturas de pantalla y metadatos de evidencia.

Visual Browser Agent está diseñado tanto para agentes de codificación basados en interfaz de usuario como para agentes basados en CLI. Un host con interfaz de usuario, como Claude Code o Antigravity, puede colocar el contenido de capturas de pantalla/imágenes y un informe de evidencia HTML o Markdown generado en su panel de artefactos. Un host CLI o un cliente MCP genérico puede usar el mismo resultado a través del bloque de imagen incrustado, los metadatos estructurados, la ruta de evidencia local o el panel local en http://127.0.0.1:8787/. El agente nunca debe asumir que un host puede abrir una ruta de sandbox arbitraria; debe devolver un resultado portable y un respaldo.

Un buen resultado de agente de navegador contiene el objetivo de la tarea, la URL y el origen, la identidad de navegador seleccionada, las acciones realizadas, las aserciones, las capturas de pantalla, los hallazgos de consola/red, el ID de ejecución, la marca de tiempo y el siguiente paso. Esto permite que una persona verifique el trabajo visualmente en lugar de leer los registros de herramientas sin procesar. Solicite esto explícitamente a su agente cuando sea necesario:

Create a host-renderable visual report with screenshots, assertions, console errors, and a concise conclusion. Also provide a local fallback.

Hay tres tipos de interacción humana. Una pregunta resuelve información que falta, como qué identidad o pestaña de Chrome usar. Una toma de control humana pide al usuario que opere el navegador directamente cuando aparece una contraseña, un aviso de MFA, un CAPTCHA o un código de un solo uso. Una aprobación autoriza una acción de consecuencias, como enviar, publicar, comprar, eliminar o presentar. Están separadas a propósito: una pregunta no es permiso para actuar, y una captura de pantalla no es prueba de que una transacción haya tenido éxito.

La herramienta de respaldo ask_human admite preguntas y opciones estructuradas simples. Las herramientas request_approval y submit_public_action están reservadas para la autorización explícita. El agente debe mostrar el sitio, el objetivo, la acción y los datos relevantes exactos antes de solicitar aprobación, y debe tratar la denegación como una decisión final del usuario en lugar de reintentar en silencio. Nunca pegue contraseñas, claves de API, tokens de acceso, datos de pago ni códigos de un solo uso en la conversación del agente. Consulte docs/user-guide-1.0.md para conocer el modelo de seguridad completo y EXTENSION_INSTALLATION.md para la configuración de la extensión de Chrome por perfil.