Browser-Automatisierung mit agent-browser
Das CLI verwendet Chrome/Chromium direkt über CDP. Installieren Sie es 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. Vorhandene Installationen von Chrome, Brave, Playwright und Puppeteer werden automatisch erkannt. Führen Sie agent-browser upgrade aus, um auf die neueste Version zu aktualisieren.
Kernworkflow
Jede Browser-Automatisierung folgt diesem Muster:
- Navigieren:
agent-browser open <url> - Snapshot:
agent-browser snapshot -i(Elementverweise wie@e1,@e2abrufen) - Interagieren: Verweise zum Klicken, Ausfüllen, Auswählen verwenden
- Erneuter Snapshot: Nach Navigation oder DOM-Änderungen frische Verweise 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 2000
agent-browser snapshot -i # Ergebnis prüfen
Befehlskettung
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.
# Öffnen + Snapshot in einem Aufruf verketten (open wartet bereits auf Seitenladung)
agent-browser open https://example.com && agent-browser snapshot -i
# Mehrere Interaktionen verketten
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 screenshot
Wann verkettet werden sollte: Verwenden Sie &&, wenn Sie die Ausgabe eines Zwischenbefehls nicht lesen müssen, bevor Sie fortfahren (z. B. open + wait + screenshot). Führen Sie Befehle getrennt aus, wenn Sie zuerst die Ausgabe parsen müssen (z. B. Snapshot, um Verweise zu entdecken, dann Interaktion mit diesen Verweisen).
Behandlung der Authentifizierung
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-Status verwenden
agent-browser --state ./auth.json open https://app.example.com/dashboard
Statusdateien enthalten Session-Tokens im Klartext – zu .gitignore hinzufügen und löschen, wenn nicht mehr benötigt. Setzen Sie AGENT_BROWSER_ENCRYPTION_KEY für die Verschlüsselung im Ruhezustand.
Option 2: Chrome-Profil-Wiederverwendung (keine Einrichtung)
# Verfügbare Chrome-Profile auflisten
agent-browser profiles
# Vorhandenen Chrome-Anmeldestatus des Benutzers wiederverwenden
agent-browser --profile Default open https://gmail.com
Option 3: Persistenzprofil (für wiederkehrende Aufgaben)
# Erster Durchlauf: manuell oder per Automatisierung anmelden
agent-browser --profile ~/.myapp open https://app.example.com/login
# ... Anmeldedaten eingeben, absenden ...
# Alle zukünftigen Durchläufe: bereits authentifiziert
agent-browser --profile ~/.myapp open https://app.example.com/dashboard
Option 4: Session-Name (automatisches Speichern/Wiederherstellen von Cookies + localStorage)
agent-browser --session-name myapp open https://app.example.com/login
# ... Anmeldeablauf ...
agent-browser close # Status automatisch gespeichert
# Nächstes Mal: Status automatisch wiederhergestellt
agent-browser --session-name myapp open https://app.example.com/dashboard
Option 5: Auth-Tresor (Anmeldedaten verschlüsselt gespeichert, Anmeldung nach Name)
echo "$PASSWORD" | agent-browser auth save myapp --url https://app.example.com/login --username user --password-stdin
agent-browser auth login myapp
auth login navigiert mit load und wartet dann darauf, dass die Anmeldeformular-Selektoren erscheinen, bevor ausgefüllt/geklickt wird – zuverlässiger bei verzögerten SPA-Anmeldebildschirmen.
Option 6: Statusdatei (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-Aktualisierungsmuster.
Wesentliche Befehle
# Batch: IMMER batch für 2+ aufeinanderfolgende Befehle verwenden. Befehle werden nacheinander ausgeführt.
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"
# Navigation
agent-browser open <url> # Navigieren (Aliase: goto, navigate)
agent-browser close # Browser schließen
agent-browser close --all # Alle aktiven Sitzungen schließen
# Snapshot
agent-browser snapshot -i # Interaktive Elemente mit Verweisen (empfohlen)
agent-browser snapshot -i --urls # href-URLs für Links einschließen
agent-browser snapshot -s "#selector" # Auf CSS-Selektor eingrenzen
# Interaktion (@refs aus snapshot verwenden)
agent-browser click @e1 # Element anklicken
agent-browser click @e1 --new-tab # Klicken und in neuem Tab öffnen
agent-browser fill @e2 "text" # Leeren und Text eingeben
agent-browser type @e2 "text" # Eingeben ohne Leeren
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" # Text an aktueller Fokusposition eingeben (kein 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 2000 # Millisekunden warten
agent-browser wait --url "**/page" # Auf URL-Muster warten
agent-browser wait --text "Welcome" # Warten, bis Text erscheint (Teilzeichenfolgen-Suche)
agent-browser wait --load networkidle # Auf Netzwerkinaktivität warten (Vorsicht: siehe Fallstricke)
agent-browser wait --fn "!document.body.innerText.includes('Loading...')" # Warten, bis Text verschwindet
agent-browser wait "#spinner" --state hidden # Warten, bis Element verschwindet
# Downloads
agent-browser download @e1 ./file.pdf # Element zum Auslösen des Downloads anklicken
agent-browser wait --download ./output.zip # Warten, bis ein Download abgeschlossen ist
agent-browser --download-path ./downloads open <url> # Standard-Download-Verzeichnis festlegen
# Tab-Verwaltung
agent-browser tab list # Alle offenen Tabs auflisten
agent-browser tab new # Neuen leeren Tab öffnen
agent-browser tab new https://example.com # URL in einem neuen Tab öffnen
agent-browser tab 2 # Zu Tab nach Index wechseln (0-basiert)
agent-browser tab close # Aktuellen Tab schließen
agent-browser tab close 2 # Tab nach Index schließen
# Netzwerk
agent-browser network requests # Verfolgte Anfragen anzeigen
agent-browser network requests --type xhr,fetch # Nach Ressourcentyp filtern
agent-browser network requests --method POST # Nach HTTP-Methode filtern
agent-browser network requests --status 2xx # Nach Status filtern (200, 2xx, 400-499)
agent-browser network request <requestId> # Vollständige Anfrage-/Antwortdetails anzeigen
agent-browser network route "**/api/*" --abort # Passende Anfragen blockieren
agent-browser network har start # HAR-Aufzeichnung starten
agent-browser network har stop ./capture.har # HAR-Datei stoppen und speichern
# Viewport & Geräteemulation
agent-browser set viewport 1920 1080 # Viewport-Größe festlegen (Standard: 1280x720)
agent-browser set viewport 1920 1080 2 # 2x Retina (gleiche CSS-Größe, höhere Auflösung bei Screenshots)
agent-browser set device "iPhone 14" # Gerät emulieren (Viewport + User-Agent)
# Erfassung
agent-browser screenshot # Screenshot in temporäres Verzeichnis
agent-browser screenshot --full # Vollständiger Seiten-Screenshot
agent-browser screenshot --annotate # Kommentierter Screenshot mit nummerierten Elementbeschriftungen
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
# Live-Vorschau / Streaming
agent-browser stream enable # Runtime-WebSocket-Streaming auf einem automatisch gewählten Port starten
agent-browser stream enable --port 9223 # Bestimmten Localhost-Port binden
agent-browser stream status # Aktivierten Status, Port, Verbindung und Screencasting prüfen
agent-browser stream disable # Runtime-Streaming stoppen und .stream-Metadatendatei entfernen
# Zwischenablage
agent-browser clipboard read # Text aus Zwischenablage lesen
agent-browser clipboard write "Hallo, Welt!" # Text in Zwischenablage schreiben
agent-browser clipboard copy # Aktuelle Auswahl kopieren
agent-browser clipboard paste # Aus Zwischenablage einfügen
# Dialoge (alert, confirm, prompt, beforeunload)
# Standardmäßig werden alert- und beforeunload-Dialoge automatisch akzeptiert, sodass sie den Agenten nie blockieren.
# confirm- und prompt-Dialoge erfordern weiterhin explizite Behandlung.
# Verwenden Sie --no-auto-dialog (oder AGENT_BROWSER_NO_AUTO_DIALOG=1), um die automatische Behandlung zu deaktivieren.
agent-browser dialog accept # Dialog akzeptieren
agent-browser dialog accept "meine Eingabe" # Prompt-Dialog mit Text akzeptieren
agent-browser dialog dismiss # Dialog ablehnen/abbrechen
agent-browser dialog status # Prüfen, ob ein Dialog aktuell geöffnet ist
# 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 Pixeldiff erstellen
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 eingrenzen
# Chat (KI-Natürlichsprachsteuerung)
agent-browser chat "öffne google.com und suche nach Katzen" # Einmalige Anweisung
agent-browser chat # Interaktiver REPL-Modus
agent-browser -q chat "fasse diese Seite zusammen" # Leise (nur Text, keine Tool-Aufrufe)
agent-browser -v chat "fülle das Anmeldeformular aus" # Ausführlich (Befehlsausgabe anzeigen)
agent-browser --model openai/gpt-4o chat "mache einen Screenshot" # Modell überschreiben
Streaming
Jede Sitzung startet automatisch einen WebSocket-Stream-Server auf einem vom Betriebssystem zugewiesenen Port. Verwenden Sie agent-browser stream status, um den gebundenen Port und den Verbindungsstatus zu sehen. Verwenden Sie stream disable, um ihn zu beenden, und stream enable --port <port>, um ihn auf einem bestimmten Port wieder zu aktivieren.
Batch-Ausführung
Verwenden Sie IMMER batch, wenn 2+ Befehle nacheinander ausgeführt werden. Batch führt Befehle nacheinander aus, sodass abhängige Befehle (wie Navigieren, dann Screenshot) korrekt funktionieren. Jedes in Anführungszeichen gesetzte Argument ist ein separater Befehl.
# Navigieren und einen Snapshot erstellen
agent-browser batch "open https://example.com" "snapshot -i"
# Navigieren, Snapshot und Screenshot in einem Aufruf
agent-browser batch "open https://example.com" "snapshot -i" "screenshot"
# Klicken, warten, dann Screenshot
agent-browser batch "click @e1" "wait 1000" "screenshot"
# Mit --bail, um beim ersten Fehler anzuhalten
agent-browser batch --bail "open https://example.com" "click @e1" "screenshot"
Verwenden Sie nur einen einzelnen Befehl (nicht batch), wenn Sie die Ausgabe lesen müssen, bevor Sie den nächsten Befehl entscheiden. Beispielsweise müssen Sie snapshot -i als einzelnen Befehl ausführen, wenn Sie die Verweise lesen müssen, um zu entscheiden, worauf Sie klicken möchten. Nachdem Sie den Snapshot gelesen haben, bündeln Sie die restlichen Schritte.
Der Stdin-Modus wird auch für die programmatische Verwendung unterstützt:
echo '[["open","https://example.com"],["screenshot"]]' | agent-browser batch --json
agent-browser batch --bail < commands.json
Effizienzstrategien
Diese Muster minimieren Tool-Aufrufe und Token-Verbrauch.
--urls verwenden, um erneute Navigation zu vermeiden. Wenn Sie Links von einer Seite besuchen müssen, verwenden Sie snapshot -i --urls, um alle href-URLs im Voraus zu erhalten. Öffnen Sie dann jede URL direkt, anstatt auf Verweise zu klicken und zurück zu navigieren.
Einmal Snapshot, mehrfach handeln. Erstellen Sie niemals einen erneuten Snapshot derselben Seite. Extrahieren Sie alle benötigten Informationen (Verweise, URLs, Text) aus einem einzigen Snapshot und bündeln Sie dann die restlichen Aktionen.
Multi-Seiten-Workflow (z. B. „N Seiten besuchen und jeweils einen Screenshot machen“):
# 1. Alle URLs in einem Aufruf abrufen
agent-browser batch "open https://news.ycombinator.com" "snapshot -i --urls"
# Ausgabe lesen, um URLs zu extrahieren, dann jede direkt besuchen:
# 2. Ein Batch pro Zielseite
agent-browser batch "open https://github.com/example/repo" "screenshot"
agent-browser batch "open https://example.com/artikel" "screenshot"
agent-browser batch "open https://andere.com/seite" "screenshot"
Dieser Ansatz verwendet 4 Tool-Aufrufe statt 14+. Gehen Sie zwischen den Besuchen niemals zurück zur Listenseite.
Häufige Muster
Formularabsendung
# Navigieren und die Formularstruktur abrufen
agent-browser batch "open https://example.com/registrierung" "snapshot -i"
# Die Snapshot-Ausgabe lesen, um Formularverweise zu identifizieren, dann ausfüllen und absenden
agent-browser batch "fill @e1 \"Max Mustermann\"" "fill @e2 \"[email protected]\"" "select @e3 \"Bayern\"" "check @e4" "click @e5" "wait 2000"
Authentifizierung mit Auth-Vault (empfohlen)
# Anmeldedaten einmal speichern (verschlüsselt mit AGENT_BROWSER_ENCRYPTION_KEY)
# Empfohlen: Passwort über stdin übergeben, 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 niemals das Passwort)
agent-browser auth login github
# Profile auflisten/anzeigen/löschen
agent-browser auth list