Browser-Automatisierung mit agent-browser
Die CLI verwendet Chrome/Chromium direkt über CDP. Installieren mit npm i -g agent-browser, brew install agent-browser oder cargo install agent-browser. Führen Sie agent-browser install aus, um Chrome herunterzuladen.
Kern-Workflow
Jede Browser-Automatisierung folgt diesem Muster:
- Navigieren:
agent-browser open <url> - Snapshot:
agent-browser snapshot -i(Element-Referenzen wie@e1,@e2abrufen) - Interagieren: Referenzen zum Klicken, Ausfüllen, Auswählen verwenden
- Erneuter Snapshot: Nach Navigation oder DOM-Änderungen frische Referenzen holen
agent-browser open https://example.com/form
agent-browser snapshot -i
# Ausgabe: @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 # Ergebnis prüfen
Befehlsverkettung
Befehle können mit && in einem einzigen Shell-Aufruf verkettet werden. Der Browser bleibt zwischen den Befehlen über einen Hintergrund-Daemon bestehen, daher ist die Verkettung sicherer und effizienter als separate Aufrufe.
# Kette: öffnen + warten + Snapshot in einem Aufruf
agent-browser open https://example.com && agent-browser wait --load networkidle && agent-browser snapshot -i
# Kette: mehrere Interaktionen
agent-browser fill @e1 "[email protected]" && agent-browser fill @e2 "password123" && agent-browser click @e3
# Navigieren und erfassen
agent-browser open https://example.com && agent-browser wait --load networkidle && agent-browser screenshot page.png
Wann verkettet werden sollte: Verwenden Sie &&, wenn Sie die Ausgabe eines Zwischenbefehls nicht lesen müssen, bevor Sie fortfahren (z.B. öffnen + warten + Screenshot). Führen Sie Befehle separat aus, wenn Sie zuerst die Ausgabe parsen müssen (z.B. Snapshot zum Erkennen von Referenzen, dann Interaktion mit diesen Referenzen).
Authentifizierung handhaben
Wenn Sie eine Website automatisieren, die eine Anmeldung erfordert, wählen Sie den passenden Ansatz:
Option 1: Auth aus dem Browser des Benutzers importieren (am schnellsten für einmalige Aufgaben)
# Mit dem laufenden Chrome des Benutzers verbinden (dieser ist bereits angemeldet)
agent-browser --auto-connect state save ./auth.json
# Diesen Auth-Zustand verwenden
agent-browser --state ./auth.json open https://app.example.com/dashboard
Zustandsdateien enthalten Sitzungstoken im Klartext – zu .gitignore hinzufügen und löschen, wenn nicht mehr benötigt. Setzen Sie AGENT_BROWSER_ENCRYPTION_KEY für Verschlüsselung im Ruhezustand.
Option 2: Persistentes Profil (am einfachsten für wiederkehrende Aufgaben)
# Erster Lauf: manuell oder per Automatisierung anmelden
agent-browser --profile ~/.myapp open https://app.example.com/login
# ... Anmeldedaten eingeben, absenden ...
# Alle zukünftigen Läufe: bereits authentifiziert
agent-browser --profile ~/.myapp open https://app.example.com/dashboard
Option 3: Sitzungsname (automatisches Speichern/Wiederherstellen von Cookies + localStorage)
agent-browser --session-name myapp open https://app.example.com/login
# ... Anmeldeablauf ...
agent-browser close # Zustand automatisch gespeichert
# Nächstes Mal: Zustand automatisch wiederhergestellt
agent-browser --session-name myapp open https://app.example.com/dashboard
Option 4: Auth-Tresor (Anmeldedaten verschlüsselt gespeichert, Anmeldung nach Namen)
echo "$PASSWORD" | agent-browser auth save myapp --url https://app.example.com/login --username user --password-stdin
agent-browser auth login myapp
Option 5: Zustandsdatei (manuelles Speichern/Laden)
# Nach dem Anmelden:
agent-browser state save ./auth.json
# In einer zukünftigen Sitzung:
agent-browser state load ./auth.json
agent-browser open https://app.example.com/dashboard
Siehe references/authentication.md für OAuth, 2FA, cookie-basierte Authentifizierung und Token-Erneuerungsmuster.
Wesentliche Befehle
# Navigation
agent-browser open <url> # Navigieren (Aliase: goto, navigate)
agent-browser close # Browser schließen
# Snapshot
agent-browser snapshot -i # Interaktive Elemente mit Referenzen (empfohlen)
agent-browser snapshot -i -C # Cursor-interaktive Elemente einschließen (divs mit onclick, cursor:pointer)
agent-browser snapshot -s "#selector" # Auf CSS-Selektor beschränken
# Interaktion (@refs aus Snapshot verwenden)
agent-browser click @e1 # Element klicken
agent-browser click @e1 --new-tab # Klicken und in neuem Tab öffnen
agent-browser fill @e2 "text" # Text löschen und eingeben
agent-browser type @e2 "text" # Text eingeben ohne zu löschen
agent-browser select @e1 "option" # Dropdown-Option auswählen
agent-browser check @e1 # Checkbox aktivieren
agent-browser press Enter # Taste drücken
agent-browser keyboard type "text" # Am aktuellen Fokus eingeben (ohne Selektor)
agent-browser keyboard inserttext "text" # Einfügen ohne Tastaturereignisse
agent-browser scroll down 500 # Seite scrollen
agent-browser scroll down 500 --selector "div.content" # Innerhalb eines bestimmten Containers scrollen
# Informationen abrufen
agent-browser get text @e1 # Elementtext abrufen
agent-browser get url # Aktuelle URL abrufen
agent-browser get title # Seitentitel abrufen
agent-browser get cdp-url # CDP WebSocket-URL abrufen
# Warten
agent-browser wait @e1 # Auf Element warten
agent-browser wait --load networkidle # Auf Netzwerkinaktivität warten
agent-browser wait --url "**/page" # Auf URL-Muster warten
agent-browser wait 2000 # Millisekunden warten
agent-browser wait --text "Welcome" # Auf Erscheinen von Text warten (Teilzeichenfolgenübereinstimmung)
agent-browser wait --fn "!document.body.innerText.includes('Loading...')" # Auf Verschwinden von Text warten
agent-browser wait "#spinner" --state hidden # Auf Verschwinden eines Elements warten
# Downloads
agent-browser download @e1 ./file.pdf # Element klicken, um Download auszulösen
agent-browser wait --download ./output.zip # Auf Abschluss eines Downloads warten
agent-browser --download-path ./downloads open <url> # Standard-Download-Verzeichnis festlegen
# Ansichtsfenster & Geräteemulation
agent-browser set viewport 1920 1080 # Ansichtsfenstergröße festlegen (Standard: 1280x720)
agent-browser set viewport 1920 1080 2 # 2x Retina (gleiche CSS-Größe, höher aufgelöste Screenshots)
agent-browser set device "iPhone 14" # Gerät emulieren (Ansichtsfenster + User-Agent)
# Erfassen
agent-browser screenshot # Screenshot in temporäres Verzeichnis
agent-browser screenshot --full # Vollständiger Seiten-Screenshot
agent-browser screenshot --annotate # Annotierter Screenshot mit nummerierten Elementbezeichnungen
agent-browser screenshot --screenshot-dir ./shots # In benutzerdefiniertes Verzeichnis speichern
agent-browser screenshot --screenshot-format jpeg --screenshot-quality 80
agent-browser pdf output.pdf # Als PDF speichern
# Zwischenablage
agent-browser clipboard read # Text aus Zwischenablage lesen
agent-browser clipboard write "Hello, World!" # Text in Zwischenablage schreiben
agent-browser clipboard copy # Aktuelle Auswahl kopieren
agent-browser clipboard paste # Aus Zwischenablage einfügen
# Diff (Seitenzustände vergleichen)
agent-browser diff snapshot # Aktuellen mit letztem Snapshot vergleichen
agent-browser diff snapshot --baseline before.txt # Aktuellen mit gespeicherter Datei vergleichen
agent-browser diff screenshot --baseline before.png # Visuellen Pixel-Unterschied vergleichen
agent-browser diff url <url1> <url2> # Zwei Seiten vergleichen
agent-browser diff url <url1> <url2> --wait-until networkidle # Benutzerdefinierte Wartestrategie
agent-browser diff url <url1> <url2> --selector "#main" # Auf Element beschränken
Häufige Muster
Formularübermittlung
agent-browser open https://example.com/signup
agent-browser snapshot -i
agent-browser fill @e1 "Jane Doe"
agent-browser fill @e2 "[email protected]"
agent-browser select @e3 "California"
agent-browser check @e4
agent-browser click @e5
agent-browser wait --load networkidle
Authentifizierung mit Auth-Tresor (empfohlen)
# Anmeldedaten einmal speichern (verschlüsselt mit AGENT_BROWSER_ENCRYPTION_KEY)
# Empfohlen: Passwort über stdin pipen, um Shell-Verlauf zu vermeiden
echo "pass" | agent-browser auth save github --url https://github.com/login --username user --password-stdin
# Mit gespeichertem Profil anmelden (LLM sieht das Passwort nie)
agent-browser auth login github
# Profile auflisten/anzeigen/löschen
agent-browser auth list
agent-browser auth show github
agent-browser auth delete github
Authentifizierung mit Zustandspersistenz
# Einmal anmelden und Zustand speichern
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
# In zukünftigen Sitzungen wiederverwenden
agent-browser state load auth.json
agent-browser open https://app.example.com/dashboard
Sitzungspersistenz
# Cookies und localStorage automatisch über Browser-Neustarts hinweg speichern/wiederherstellen
agent-browser --session-name myapp open https://app.example.com/login
# ... Anmeldeablauf ...
agent-browser close # Zustand automatisch gespeichert unter ~/.agent-browser/sessions/
# Nächstes Mal wird der Zustand automatisch geladen
agent-browser --session-name myapp open https://app.example.com/dashboard
# Zustand im Ruhezustand verschlüsseln
export AGENT_BROWSER_ENCRYPTION_KEY=$(openssl rand -hex 32)
agent-browser --session-name secure open https://app.example.com
# Gespeicherte Zustände verwalten
agent-browser state list
agent-browser state show myapp-default.json
agent-browser state clear myapp
agent-browser state clean --older-than 7
Datenextraktion
agent-browser open https://example.com/products
agent-browser snapshot -i
agent-browser get text @e5 # Text eines bestimmten Elements abrufen
agent-browser get text body > page.txt # Gesamten Seitentext abrufen
# JSON-Ausgabe zum Parsen
agent-browser snapshot -i --json
agent-browser get text @e1 --json
Parallele Sitzungen
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
Mit vorhandenem Chrome verbinden
# Laufenden Chrome mit aktiviertem Remote-Debugging automatisch erkennen
agent-browser --auto-connect open https://example.com
agent-browser --auto-connect snapshot
# Oder mit explizitem CDP-Port
agent-browser --cdp 9222 snapshot
Farbschema (Dunkelmodus)
# Persistenter Dunkelmodus via Flag (gilt für alle Seiten und neuen Tabs)
agent-browser --color-scheme dark open https://example.com
# Oder via Umgebungsvariable
AGENT_BROWSER_COLOR_SCHEME=dark agent-browser open https://example.com
# Oder während der Sitzung festlegen (bleibt für nachfolgende Befehle bestehen)
agent-browser set media dark
Ansichtsfenster & Responsive-Tests
# Benutzerdefinierte Ansichtsfenstergröße festlegen (Standard ist 1280x720)
agent-browser set viewport 1920 1080
agent-browser screenshot desktop.png
# Mobile-Breite-Layout testen
agent-browser set viewport 375 812
agent-browser screenshot mobile.png
# Retina/HiDPI: gleiches CSS-Layout bei 2x Pixeldichte
# Screenshots bleiben bei logischer Ansichtsfenstergröße, aber Inhalt wird mit höherer DPI gerendert
agent-browser set viewport 1920 1080 2
agent-browser screenshot retina.png
# Geräteemulation (setzt Ansichtsfenster + User-Agent in einem Schritt)
agent-browser set device "iPhone 14"
agent-browser screenshot device.png
Der Parameter scale (3. Argument) setzt window.devicePixelRatio, ohne das CSS-Layout zu ändern. Verwenden Sie ihn beim Testen von Retina-Rendering oder zum Erfassen von Screenshots mit höherer Auflösung.
Visueller Browser (Debugging)
agent-browser --headed open https://example.com
agent-browser highlight @e1 # Element hervorheben
agent-browser inspect # Chrome DevTools für die aktive Seite öffnen
agent-browser record start demo.webm # Sitzung aufzeichnen
agent-browser profiler start # Chrome DevTools-Profiling starten
agent-browser profiler stop trace.json # Profiling stoppen und speichern (Pfad optional)
Verwenden Sie AGENT_BROWSER_HEADED=1, um den Headed-Modus über die Umgebungsvariable zu aktivieren. Browser-Erweiterungen funktionieren sowohl im Headed- als auch im Headless-Modus.
Lokale Dateien (PDFs, HTML)
# Lokale Dateien mit file:// URLs öffnen
agent-browser --allow-file-access open file:///pfad/zu/dokument.pdf
agent-browser --allow-file-access open file:///pfad/zu/seite.html
agent-browser screenshot output.png
iOS-Simulator (Mobile Safari)
# Verfügbare iOS-Simulatoren auflisten
agent-browser device list
# Safari auf einem bestimmten Gerät starten
agent-browser -p ios --device "iPhone 16 Pro" open https://example.com
# Gleicher Workflow wie Desktop – Snapshot, Interaktion, erneuter Snapshot
agent-browser -p ios snapshot -i
agent-browser -p ios tap @e1 # Tippen (Alias für click)
agent-browser -p ios fill @e2 "text"
agent-browser -p ios swipe up # Mobilgeräte-spezifische Geste
# Screenshot erstellen
agent-browser -p ios screenshot mobile.png
# Sitzung schließen (fährt Simulator herunter)
agent-browser -p ios close
Voraussetzungen: macOS mit Xcode, Appium (npm install -g appium && appium driver install xcuitest)
Physische Geräte: Funktioniert mit physischen iOS-Geräten, wenn diese vorkonfiguriert sind. Verwenden Sie --device "<UDID>", wobei UDID von xcrun xctrace list devices stammt.
Sicherheit
Alle Sicherheitsfunktionen sind optional (Opt-in). Standardmäßig erlegt agent-browser keine Einschränkungen für Navigation, Aktionen oder Ausgabe auf.
Inhaltsgrenzen (empfohlen für KI-Agenten)
Aktivieren Sie --content-boundaries, um Seitenausgaben mit Markierungen zu versehen, die LLMs helfen, Tool-Ausgaben von nicht vertrauenswürdigem Seiteninhalt zu unterscheiden:
export AGENT_BROWSER_CONTENT_BOUNDARIES=1
agent-browser snapshot
# Ausgabe:
# --- AGENT_BROWSER_PAGE_CONTENT nonce=<hex> origin=https://example.com ---
# [accessibility tree]
# --- END_AGENT_BROWSER_PAGE_CONTENT nonce=<hex> ---
Domain-Allowlist
Beschränken Sie die Navigation auf vertrauenswürdige Domains. Platzhalter wie *.example.com stimmen auch mit der nackten Domain example.com überein. Sub-Ressourcenanfragen, WebSocket- und EventSource-Verbindungen zu nicht erlaubten Domains werden ebenfalls blockiert. Fügen Sie CDN-Domains hinzu, von denen Ihre Zielseiten abhängen:
export AGENT_BROWSER_ALLOWED_DOMAINS=app.example.com,cdn.example.com
Navigation zu nicht aufgeführten Domains fehlschlägt mit:
Fehler: Domain example.com ist nicht in der Allowlist. Setzen Sie AGENT_BROWSER_ALLOWED_DOMAINS, um Domains zuzulassen.
Befehlssandboxing
Ein- und Ausgabe von Authentifizierungsdaten und Zustandsdateien sind gegen unbeabsichtigte Offenlegung geschützt, da das Tool die Daten nur über die entsprechenden Unterbefehle verarbeitet.
Fehlerbehebung
agent-browser install schlägt fehl
Stellen Sie sicher, dass Sie über eine stabile Internetverbindung verfügen. Auf einigen Systemen müssen Sie möglicherweise chromium oder google-chrome manuell installieren, wenn der Download fehlschlägt.
agent-browser open hängt
Wenn der Befehl hängt, versuchen Sie:
- Setzen Sie
AGENT_BROWSER_HEADED=1, um zu sehen, was Chrome tut - Erhöhen Sie die Wartezeit mit
--timeout(Standard 30s):agent-browser open --timeout 60000 <url> - Verwenden Sie
--debug, um detaillierte Protokolle zu erhalten:agent-browser --debug open https://example.com 2>&1 | head -50 - Starten Sie den Hintergrund-Daemon neu:
agent-browser close
Die Umgebungsvariable AGENT_BROWSER_DEBUG=1 aktiviert die Debug-Protokollierung für alle Befehle.
Docker-/CI-Umgebungen
In Docker benötigen Sie möglicherweise zusätzliche Flags, um Chrome ohne Sandbox auszuführen:
export AGENT_BROWSER_CHROME_ARGS="--no-sandbox --disable-gpu --disable-dev-shm-usage"
agent-browser open https://example.com
Der Standard-Download-Pfad in Docker funktioniert möglicherweise nicht. Legen Sie explizit ein beschreibbares Verzeichnis fest:
mkdir -p /tmp/downloads
agent-browser --download-path /tmp/downloads open https://example.com