Visual Browser Agent

Ein lokales Browser-Automatisierungstool, das KI-Agenten „Augen und Hände“ für die Web-Interaktion gibt. Visual Browser Agent ist Playwright plus eine Agenten-Kontrollebene: Playwright übernimmt die Browserarbeit, während dieses Projekt MCP-Tools, visuelle Beweise, Genehmigungen, Chrome-Identitätsverwaltung, Sicherheitskontrollen und Workflows für Coding-Agenten und alltägliche Browseraufgaben hinzufügt.

Was nach der Installation passiert

Sie müssen weder Chromium, CDP, Remote-Debugging noch die internen Profilnamen von Chrome verstehen.

Ein technischer Installer registriert Visual Browser Agent bei dem von Ihnen verwendeten Coding-Agenten und installiert die Playwright-Browserlaufzeit. Danach läuft Ihr normaler Workflow im Chat des Coding-Agenten ab. Sie können sagen:

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

Der Agent prüft zuerst, ob eine vorhandene Chrome-Sitzung verfügbar ist. Wenn er eine findet, verwendet er diese Sitzung; andernfalls startet er eine saubere, von Playwright verwaltete Chromium-Sitzung. Sie können auch in normaler Sprache explizit sein:

Use my Work Chrome account and check the dashboard.

Der Agent erkennt benutzerfreundliche Chrome-Identitäten wie „Arbeit — work@example.com“ und „Privat — personal@example.com“. Wenn mehr als eine mögliche Identität vorhanden ist, fragt er Sie im Gespräch, welche Sie wählen möchten. Sie führen keinen Profilbefehl aus und wählen nicht Profil 3.

Visual Browser Agent enthält außerdem ein optionales lokales Kontrollpanel. Ein technischer Benutzer kann es mit npx visual-browser-agent dashboard starten, aber das Kontrollpanel ist für den normalen Gebrauch nicht erforderlich. Es zeigt Verbindungsstatus, den aktiven Tab, verfügbare Chrome-Identitäten und aktuelle Beweise unter http://127.0.0.1:8787/ an.

Bevor der Agent sich anmeldet, eine Nachricht sendet, veröffentlicht, kauft, löscht, übermittelt oder externe Daten ändert, pausiert er und bittet um Genehmigung. Schreibgeschützte Inspektion, Screenshots, visuelle Audits und Beweiserfassung können automatisch fortgesetzt werden.

Related MCP server: websight

So funktioniert es

Es gibt zwei Browser und zwei Verbindungsmethoden:

Installation

Option 1: Bitten Sie Ihren Coding-Agenten, es zu installieren

In Claude Code, Cursor, Copilot, Codex, Gemini, Windsurf, Cline, Roo, Kiro, Goose, OpenCode, Antigravity oder einem anderen MCP-fähigen Coding-Agenten fragen Sie:

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.

Der Agent sollte den Einrichtungsstatus prüfen, vor der Installation von Playwright Chromium um Bestätigung bitten, den MCP-Server registrieren und über fehlende Berechtigungen oder Erweiterungsschritte berichten. Dann können Sie einfach sagen: „Verwende den Browser, um …“.

Option 2: Von GitHub (Empfohlen zum Testen)

# 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

Oder direkt mit npx verwenden:

npx github:Akakaui/visual-browser-agent init

Option 3: Von npm (nach der Veröffentlichung)

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

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

Option 4: Lokale Entwicklung

# 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

Schnellstart

1. Initialisieren

npx visual-browser-agent init

Dies wird:

• Chromium (Playwright-Browser) installieren

• MCP-Konfiguration einrichten

• Agent Skills installieren

• Ihren Coding-Agenten automatisch erkennen und den Wrapper installieren

2. Verwendung starten

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

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

3. In Ihrem KI-Agenten verwenden

Fragen Sie Ihren Agenten: „Recherchiere das Design dieser Website“

Der Agent verwendet Visual Browser Agent, um den Browser zu steuern.

Verwenden Ihres vorhandenen Chrome (Erweiterung)

Für die vollständige Anleitung für normale Benutzer mit Profilwechsel, Verifizierung und Fehlerbehebung siehe EXTENSION_INSTALLATION.md.

Wenn Sie möchten, dass Ihr Agent Ihr vorhandenes Chrome verwendet (mit Ihren Anmeldungen, Cookies, Sitzungen):

1. Die Erweiterung installieren

1. Öffnen Sie Chrome → chrome://extensions/

2. Aktivieren Sie Entwicklermodus

3. Klicken Sie auf Entpackte Erweiterung laden

4. Wählen Sie: node_modules/visual-browser-agent/browser-extension

2. Den Agenten starten

npx visual-browser-agent mcp --extension

3. In Ihrem KI-Agenten verwenden

Fragen Sie Ihren Agenten: „Melde dich bei meinem Gmail an und fasse meine E-Mails zusammen“

Der Agent verbindet sich mit Ihrem Chrome mit allen Ihren Anmeldungen intakt.

Integration mit KI-Agenten

Automatische Erkennung (Empfohlen)

Wenn Sie npx visual-browser-agent init ausführen, erkennt es automatisch:

• Welchen Coding-Agenten Sie verwenden

• Installiert den entsprechenden Wrapper

• Richtet die MCP-Konfiguration ein

Manuelle Installation

Wenn die automatische Erkennung nicht funktioniert, können Sie manuell installieren:

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

Unterstützte Agenten:

• claude-code

• cursor

• gemini

• opencode

• antigravity

• windsurf

• cline

• roo

• kiro

• copilot

• codex

• goose

Claude Code

Fügen Sie zu .claude/settings.json hinzu:

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

Cursor

Fügen Sie zu .cursor/mcp.json hinzu:

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

Für den Chrome-Erweiterungsmodus

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

Wie KI-Agenten dies verwenden

Szenario 1: Eine öffentliche Website recherchieren

Agent denkt: „Dies ist eine öffentliche Website, keine Anmeldung erforderlich.“

Agent tut: Verwendet Chromium (Standard)

npx visual-browser-agent mcp

Szenario 2: Auf private Daten des Benutzers zugreifen

Agent denkt: „Dies erfordert die Anmeldung des Benutzers.“

Agent tut: Verwendet Chrome über die Erweiterung

npx visual-browser-agent mcp --extension

Szenario 3: Benutzer gibt Browser an

Benutzer sagt: „Verwende mein angemeldetes Arbeits-Chrome-Konto“

Agent tut:

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

Befehlsreferenz

Kontrollpanel für normale Benutzer

Für einen nicht-technischen Benutzer sollte der Browser-Agent einmal von einem Administrator oder durch die Coding-Agenten-Einrichtung installiert und registriert werden. Der Benutzer arbeitet dann über den Coding-Agenten, indem er sagt: „Verwende den Browser, um diese Website zu öffnen“, „Verwende mein Arbeitskonto“ oder „Prüfe die Seite und zeige mir Screenshots“. Der Agent übernimmt Verbindung, Identitätserkennung, Beweise und Genehmigungen über MCP.

Das optionale lokale Kontrollpanel ist für Verbindungssichtbarkeit und Wiederherstellung verfügbar. Ein technischer Benutzer kann es mit npx visual-browser-agent dashboard starten; es öffnet sich unter http://127.0.0.1:8787/ und zeigt Verbindungsstatus, benutzerfreundliche Chrome-Identitäten, den aktiven Tab und aktuelle Beweise. Das Panel ist nur lokal und ersetzt nicht das Gespräch mit dem Coding-Agenten.

Playwright-2.0-Kompatibilitätsoberfläche

Visual Browser Agent stellt eine Playwright-gestützte MCP-Oberfläche für Agenten-Workflows bereit. Zusätzlich zu Navigation, Formularen, Uploads, Downloads, Screenshots, Aufzeichnung, responsiven Audits und visuellen Studien können Agenten Tabs/Seiten, Verlauf, Drag-and-Drop, Locator-Referenzen, Web-First-Assertions, Frame-Inspektion, Dialogrichtlinie, Cookies, genehmigten Storage-State-Export, aktuelle Konsolenmeldungen, aktuelle Netzwerkanfragen, URL-Routing-Mocks, Tracing, Medienemulation, PDF-Beweise und bestätigungsgesteuerte Seitenauswertung verwenden.

Die Kompatibilitätsschicht hält sensible Operationen absichtlich explizit. Das Löschen von Cookies erfordert confirm=true; Seitenauswertung erfordert confirmDangerous=true; öffentliche Übermittlungen und Artefaktlöschungen bleiben dem Genehmigungsdienst unterstellt. Netzwerk-Mocks und Speicherartefakte sind auf die aktive Agentensitzung und genehmigte Verzeichnisse beschränkt.

Profile

Wenn Sie mehrere Chrome-Profile haben, wählen Sie das angemeldete Konto, das Sie mit der Erweiterung verwenden möchten:

# 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"

Fehlerbehebung

Chromium funktioniert nicht

npx playwright install chromium

Chrome-Erweiterung verbindet nicht

1. Stellen Sie sicher, dass Chrome geöffnet ist

2. Prüfen Sie, ob das Erweiterungssymbol „EIN“ anzeigt

3. Versuchen Sie: npx visual-browser-agent doctor

MCP-Server startet nicht

# Check environment
npx visual-browser-agent doctor

# Reinstall
npx visual-browser-agent init

Architektur

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

Lizenz

MIT

Tägliche Nutzung für nicht-technische Benutzer

Visual Browser Agent kann in zwei einfachen Modi verwendet werden:

Ein nicht-technischer Benutzer sollte MCP nicht verstehen müssen. Nach einer Einrichtung kann er seinem Coding-Agenten in normaler Sprache sagen, was er möchte, zum Beispiel: „Öffne das Arbeits-Chrome-Profil, prüfe die Checkout-Seite unter dieser URL und speichere Screenshots“ oder „Verwende eine saubere Chromium-Sitzung, um diese Website auf Desktop und Mobilgerät zu vergleichen.“ Der Wrapper weist den Coding-Agenten an, die Browserverbindung zu prüfen, den geeigneten Modus zu wählen, vor Authentifizierung oder folgenschweren Aktionen zu fragen und prägnante Ergebnisse mit Beweisen zurückzugeben.

Chrome-Profile: Erweiterung versus Remote-Debugging

Chrome-Erweiterungen werden pro Chrome-Profil installiert, nicht einmal für jedes Browserfenster. Wenn eine Person drei separate Chrome-Profile über den Erweiterungsmodus verwenden möchte, sollte sie jedes Profil öffnen, zu chrome://extensions/ gehen, den Entwicklermodus aktivieren und das entpackte Verzeichnis browser-extension/ einmal in jedem Profil laden. Dieselbe Erweiterungsquelle kann in jedes Profil geladen werden, aber jedes Profil muss seine eigenen Berechtigungen erteilen und geöffnet bleiben, wenn dieses Profil ausgewählt wird.

Remote-Debugging ist anders. Es verbindet sich mit einer Chrome-Instanz, die mit einem bestimmten --profile-directory und Debugging-Port gestartet wurde. Die meisten Menschen sollten visual-browser-agent mcp --choose-profile ausführen; das Tool liest benutzerfreundliche Kontolabels aus Chrome und lässt den Benutzer eines per Nummer auswählen. Die technische --profile-Option bleibt für Skripte und fortgeschrittene Einrichtungen verfügbar. Ein Profil, das bereits von einem anderen Chrome-Prozess verwendet wird, kann einen zweiten Start verweigern; schließen Sie zuerst dieses Profil oder verwenden Sie ein separates Debugging-Profil und einen separaten Port.

Für einen Benutzer, der vorhandene Anmelde-Cookies benötigt, ist der Erweiterungsweg normalerweise am einfachsten. Für einen Benutzer, der einen wiederholbaren sauberen Browser möchte, ist Chromium sicherer. Remote-Debugging sollte als fortgeschrittene Option behandelt werden, da es die ausgewählte Browsersitzung dem lokalen Agentenprozess aussetzt.

Auswahl des Browser-Agenten durch Aufforderung

Der Benutzer wählt normalerweise die Aufgabe aus, nicht einen Browsermodus oder ein Spezialistenmodell. Sage „use the browser to …“ in Claude, Cursor, Copilot, Codex, Gemini, Windsurf, Cline, Roo, Kiro, Goose, OpenCode, Antigravity oder einem anderen MCP-fähigen Coding-Agenten. Der Wrapper weist den Agenten an, die automatische Browserauswahl zu verwenden, bei Bedarf sichtbare Chrome-Identitäten zu erkennen und auf verwaltetes Chromium zurückzugreifen, wenn keine bestehende Sitzung verfügbar ist. Der Coding-Agent wählt die Visual Browser Agent MCP-Tools aus, nachdem die Integration installiert wurde. Prompts sollten die Sitzungsanforderung benennen, wenn sie relevant ist:

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.

Wenn ein Team einen benannten Browser-Spezialisten möchte, führe visual-browser-agent host <agent-name> für den Coding-Client aus und behalte die generierte MCP-Konfiguration sowie den Wrapper in diesem Projekt. Das Paket enthält Adapter für Claude Code, Cursor, Gemini, Windsurf, Cline, Roo, Kiro, Copilot, Codex, Goose, OpenCode und Antigravity und verwendet einen universellen Wrapper für Hosts ohne dedizierten Wrapper. Neue Hosts können dieselbe Standard-MCP-Konfiguration verwenden: Starte den Befehl visual-browser-agent mcp --managed und registriere ihn als MCP-Server mit dem Namen visual-browser.

Empfohlene Ersteinrichtung

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

Starte dann den Coding-Agenten neu und bitte ihn, die visuellen Browser-Tools zu verwenden. Für einen sauberen täglichen Chromium-Workflow verwende visual-browser-agent mcp --managed. Für eine bestehende Chrome-Identität verwende visual-browser-agent mcp --choose-profile, nachdem die Erweiterung in das gewünschte Profil geladen wurde. Verwende --profile nur für fortgeschrittene Skripte.

Der Agent sollte beim Überprüfen einer Website immer automatisch schreibgeschützte Inspektionen und Screenshots verwenden. Er sollte vor dem Posten, Veröffentlichen, Kaufen, Löschen, Absenden oder Ändern externer Daten eine ausdrückliche Genehmigung anfordern. Authentifizierung und private persönliche Informationen sollten vom Benutzer direkt im Browser bereitgestellt werden, nicht in Prompts oder Konfigurationsdateien.

Agent-Artefakte, Artefakt-Panels, Fragen und Genehmigungen

Für den vollständigen normalen Benutzer- und technischen Workflow lies den Visual Browser Agent 1.0 User Guide. Die Kurzfassung: Ein Coding-Agent interagiert über MCP mit Visual Browser Agent: Er entdeckt die verfügbaren Browser-Tools, wählt die Tools aus, die zur Anfrage des Benutzers passen, und erhält Text, strukturiertes JSON, Screenshots und Evidenz-Metadaten.

Visual Browser Agent ist sowohl für UI-basierte Coding-Agenten als auch für CLI-basierte Agenten konzipiert. Ein UI-Host wie Claude Code oder Antigravity kann Screenshot-/Bildinhalte und einen generierten HTML- oder Markdown-Evidenzbericht in seinem Artefakt-Panel platzieren. Ein CLI-Host oder ein generischer MCP-Client kann dasselbe Ergebnis über den eingebetteten Bildblock, strukturierte Metadaten, den lokalen Evidenzpfad oder das lokale Dashboard unter http://127.0.0.1:8787/ verwenden. Der Agent sollte niemals annehmen, dass ein Host einen beliebigen Sandbox-Pfad öffnen kann; er sollte ein portables Ergebnis und einen Fallback zurückgeben.

Ein gutes Browser-Agent-Ergebnis enthält das Aufgabenobjektiv, URL und Ursprung, ausgewählte Browser-Identität, durchgeführte Aktionen, Assertions, Screenshots, Konsolen-/Netzwerkbefunde, Run-ID, Zeitstempel und den nächsten Schritt. So kann eine Person die Arbeit visuell überprüfen, anstatt rohe Tool-Logs zu lesen. Bitte deinen Agenten bei Bedarf ausdrücklich darum:

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

Es gibt drei Arten menschlicher Interaktion. Eine Frage klärt fehlende Informationen, z. B. welche Chrome-Identität oder welcher Tab verwendet werden soll. Eine menschliche Übernahme bittet den Benutzer, den Browser direkt zu bedienen, wenn ein Passwort, eine MFA-Aufforderung, ein CAPTCHA oder ein Einmalcode erscheint. Eine Genehmigung autorisiert eine folgenreiche Aktion wie Senden, Veröffentlichen, Kaufen, Löschen oder Absenden. Sie sind bewusst getrennt: Eine Frage ist keine Erlaubnis zu handeln, und ein Screenshot ist kein Beweis dafür, dass eine Transaktion erfolgreich war.

Das Fallback-Tool ask_human unterstützt Fragen und einfache strukturierte Auswahlmöglichkeiten. Die Tools request_approval und submit_public_action sind für die ausdrückliche Autorisierung reserviert. Der Agent sollte vor der Genehmigungsanfrage die genaue Website, das Ziel, die Aktion und die relevanten Daten anzeigen und eine Ablehnung als endgültige Benutzerentscheidung behandeln, anstatt stillschweigend erneut zu versuchen. Füge niemals Passwörter, API-Schlüssel, Zugriffstokens, Zahlungsdaten oder Einmalcodes in die Agenten-Konversation ein. Siehe docs/user-guide-1.0.md für das vollständige Sicherheitsmodell und EXTENSION_INSTALLATION.md für die Chrome-Erweiterungseinrichtung pro Profil.