agent-browser

Overview

What is agent-browser?

agent-browser ist ein Kommandozeilen-Tool zur Browser-Automatisierung, entwickelt für KI-Agenten und Shell-basierte Workflows. Es verbindet sich direkt mit Chrome oder Chromium über das Chrome DevTools Protocol (CDP), sodass du echte Browser-Interaktionen aus dem Terminal oder einem Agent-Runtime heraus skripten kannst.

Mit agent-browser kannst du:

• Webseiten öffnen und durch sie navigieren (agent-browser open <url>)
• Interaktive Elemente über strukturierte Snapshots erkennen
• Buttons klicken, Links folgen und mit Formularen interagieren
• Eingabefelder ausfüllen, Text eintippen und Tastenanschläge simulieren
• Snapshots erstellen, um die Seitenstruktur und verfügbare Aktionen zu verstehen
• Sessions verwalten und authentifizierte Zustände beibehalten
• Authentifizierungsabläufe durchlaufen (inklusive OAuth und 2FA mit menschlicher Unterstützung)
• Proxys für Geo-Tests oder Unternehmensumgebungen nutzen
• Performance-Traces für Profiling aufzeichnen
• Videos von Browser-Sessions für Debugging oder Dokumentation aufnehmen

Who is agent-browser for?

agent-browser ist eine gute Wahl, wenn du:

• Einen KI-Agenten oder ein Automatisierungsframework betreibst, das echte Browsersteuerung benötigt
• Einen CLI-first-Ansatz zur Automatisierung von Chrome-/Chromium-Workflows bevorzugst
• Robustes Element-Targeting brauchst, das LLM-freundlich ist (mithilfe kompakter @refs)
• Login-Flows, Formularübermittlungen oder mehrstufige Web-App-Flows automatisierst
• Reproduzierbare Tests, Demos oder Debugging-Sessions als Video oder Traces erfassen möchtest

Besonders sinnvoll ist es in diesen Szenarien:

• Browser-Automatisierung: geskriptete Navigation, Klicken und Formularausfüllung
• Workflow-Automatisierung: End-to-End-Sequenzen wie "einloggen → navigieren → Report exportieren"
• Testautomatisierung: Smoke-Tests, Regressionstests und Performance-Profiling von Webanwendungen

When agent-browser is and is not a good fit

Nutze agent-browser, wenn:

• Du ein lokales CLI ausführen kannst und Zugriff auf Chrome oder Chromium hast
• Du deterministisches, skriptbares Browserverhalten für einen KI-Agenten bereitstellen möchtest
• Du feingranulare Kontrolle über Sessions, Cookies und Authentifizierung brauchst

Es ist möglicherweise nicht die beste Wahl, wenn:

• Du Chrome/Chromium auf dem Host nicht installieren oder ausführen kannst
• Du nur rohes HTML oder einfache HTTP-Requests brauchst (ein reiner HTTP-Client oder Scraper ist dann oft ausreichend)
• Du Headless-Browsersteuerung in Sprachen oder Runtimes benötigst, die eng mit anderen Browser-Automatisierungsbibliotheken gekoppelt sind

How to Use

Installation options

agent-browser unterstützt mehrere Installationswege. Wähle die Variante, die zu deiner Umgebung passt:

• npm (Node.js)

  npm i -g agent-browser
  

• Homebrew (macOS/Linux)

  brew install agent-browser
  

• Rust / Cargo

  cargo install agent-browser
  

Führe nach der Installation des CLI das integrierte Chrome-Setup aus:

agent-browser install

Dies lädt eine kompatible Chrome-/Chromium-Version herunter und richtet sie ein. Wenn eine neue Version verfügbar ist, aktualisiere mit:

agent-browser upgrade

Wenn du agent-browser als Skill in einer Agent-Plattform verwendest, kannst du es auch so hinzufügen:

npx skills add https://github.com/vercel-labs/agent-browser --skill agent-browser

Sieh dir die Datei SKILL.md im Repository an, um die aktuellsten Skill-spezifischen Wiring-Details zu erhalten.

Core browser automation workflow

Jeder agent-browser-Workflow folgt einem einfachen Loop: open → snapshot → interact → re-snapshot.

1. Zu einer Seite navigieren

   agent-browser open https://example.com/form
   

2. Snapshot erstellen, um Elemente zu finden
   Nutze den interaktiven Snapshot-Modus, um eine kompakte Liste klickbarer und ausfüllbarer Elemente mit @refs zu erhalten:

   agent-browser snapshot -i
   

   Beispielausgabe (vereinfacht):

   @e1 [input type="email"]
   @e2 [input type="password"]
   @e3 [button] "Submit"
   

3. Über refs interagieren

   agent-browser fill @e1 "user@example.com"
   agent-browser fill @e2 "password123"
   agent-browser click @e3
   

4. Warten und erneut snapshotten

   agent-browser wait --load networkidle
   agent-browser snapshot -i
   

Dieses Muster ermöglicht es einem KI-Agenten, mit einer kompakten Strukturansicht statt mit dem kompletten DOM zu arbeiten, was den Kontextbedarf deutlich reduziert.

Command reference basics

agent-browser stellt eine Vielzahl an Commands bereit (siehe references/commands.md), darunter:

• Navigation

  agent-browser open <url>
  agent-browser back
  agent-browser forward
  agent-browser reload
  agent-browser close
  

• Snapshot und refs

  agent-browser snapshot          # vollständiger Baum
  agent-browser snapshot -i       # nur interaktive Elemente (empfohlen)
  agent-browser snapshot -c       # kompakte Ausgabe
  agent-browser snapshot -d 3     # Tiefe begrenzen
  agent-browser snapshot -s "#main"  # auf CSS-Selector einschränken
  

• Interaktionen

  agent-browser click @e1
  agent-browser dblclick @e1
  agent-browser hover @e1
  agent-browser focus @e1
  agent-browser fill @e2 "text"
  agent-browser type @e2 "text"
  agent-browser press Enter
  

Nutze references/snapshot-refs.md für detaillierte Hinweise dazu, wie @refs erzeugt werden und wie lange sie gültig bleiben.

Working with sessions and authentication

agent-browser bietet integrierte Tools für authentifiziertes Browsen und Multi-Sessions. Das ist hilfreich für Login-Flows, Tests mit mehreren Accounts oder zur Trennung verschiedener Rollen.

• Benannte Sessions (siehe references/session-management.md):

  # Session "auth": Login-Flow
  agent-browser --session auth open https://app.example.com/login
  
  # Session "public": getrenntes Browsing
  agent-browser --session public open https://example.com
  

  Jede Session hat eigene Cookies, Storage, Cache und History.

• Persistente Session-States:

  # Cookies und Storage speichern
  agent-browser state save ./auth-state.json
  
  # Später wiederherstellen
  agent-browser state load ./auth-state.json
  agent-browser open https://app.example.com/dashboard
  

• Authentifizierungs-Muster (siehe references/authentication.md):

  • Cookies aus einem Debug-fähigen Chrome importieren, in dem du bereits eingeloggt bist
  • Standard-Loginformulare mit Snapshots und fill/click durchlaufen
  • Cookie-basierte Authentifizierung, HTTP Basic Auth und Token-Refresh handhaben

Für komplexe OAuth- oder 2FA-Flows kann anfangs weiterhin ein Mensch eingebunden sein. Anschließend kann agent-browser den gespeicherten authentifizierten Zustand wiederverwenden.

Proxy support and network configuration

Wenn du Traffic über einen Proxy leiten musst (für Geo-Tests, Rate-Limits oder in Unternehmensnetzwerken), nutze die Optionen aus references/proxy-support.md:

• HTTP/HTTPS-Proxy per CLI-Flag

  agent-browser --proxy "http://proxy.example.com:8080" open https://example.com
  

• Konfiguration über Umgebungsvariablen

  export HTTP_PROXY="http://proxy.example.com:8080"
  export HTTPS_PROXY="https://proxy.example.com:8080"
  agent-browser open https://example.com
  

• SOCKS-Proxy

  export ALL_PROXY="socks5://proxy.example.com:1080"
  agent-browser open https://example.com
  

Profiling and performance tracing

Für Testautomatisierung und Performance-Analysen kann agent-browser Chrome-Performance-Traces erfassen (siehe references/profiling.md):

# Start profiling
agent-browser profiler start

# Run your scenario
agent-browser open https://example.com
agent-browser click @e1
agent-browser wait 1000

# Stop and save trace
agent-browser profiler stop ./trace.json

Die erzeugte Datei trace.json kannst du in den Chrome DevTools (Tab "Performance") oder in kompatiblen Viewern öffnen, um JavaScript-Ausführung, Rendering und User-Timing-Events zu analysieren.

Video recording for debugging and documentation

agent-browser kann ein Video der Browser-Session aufzeichnen – ideal, um fehlgeschlagene Automationen zu debuggen oder How-to-Guides zu erstellen (siehe references/video-recording.md):

# Start recording
agent-browser record start ./demo.webm

# Perform actions
agent-browser open https://example.com
agent-browser snapshot -i
agent-browser click @e1

# Stop recording
agent-browser record stop

Diese .webm-Aufnahmen kannst du in Dokumentationen einbetten, mit Teammitgliedern teilen oder Bugreports beifügen.

Using templates for common workflows

Im Repository findest du Shell-Skript-Templates im Verzeichnis templates/, mit denen du wiederholbare Workflows aufbauen kannst:

• templates/form-automation.sh – strukturiertes Muster zum Ausfüllen und Absenden von Formularen
• templates/authenticated-session.sh – Beispiel für Login und persistente Session-States
• templates/capture-workflow.sh – Muster zum Snapshotten oder Aufzeichnen eines mehrstufigen Flows

Du kannst diese Skripte kopieren und an deine Umgebung, CI-Jobs oder Agent-Pipelines anpassen.

FAQ

Welche Probleme löst agent-browser im Vergleich zu einfachen HTTP-Clients?

agent-browser steuert eine echte Chrome-/Chromium-Instanz über CDP. Dadurch kann es:

• Clientseitiges Rendering und komplexes JavaScript verarbeiten
• Single-Page-Apps bedienen, die auf Browser-APIs angewiesen sind
• Echte User-Interaktionen wie Klicken, Tippen und Tastendrücke simulieren
• Visuelle Timings, Rendering-Verhalten und Performance-Traces erfassen

Wenn du nur rohes HTML oder JSON von einfachen Endpoints benötigst, reicht ein HTTP-Client meist aus. Für alles, was sich wie ein echter Nutzer in einem Browser verhalten soll, ist agent-browser die passendere Lösung.

Wie installiere ich Chrome oder Chromium für agent-browser?

Nachdem du das CLI mit npm, Homebrew oder Cargo installiert hast, führe aus:

agent-browser install

Dadurch wird eine kompatible Chrome-/Chromium-Version heruntergeladen und so konfiguriert, dass agent-browser sie über CDP steuern kann. Wenn eine neue Version erscheint, aktualisiere mit:

agent-browser upgrade

Kann agent-browser meine bestehende eingeloggte Browser-Session wiederverwenden?

Ja. In references/authentication.md wird beschrieben, wie du Chrome mit --remote-debugging-port startest und Cookies aus einer Session importierst, in der du bereits eingeloggt bist. Sobald die Cookies importiert sind, kannst du diesen authentifizierten Zustand mit agent-browser state save sichern und später wiederherstellen, ohne den kompletten Login-Flow erneut durchlaufen zu müssen.

Eignet sich agent-browser für CI und automatisiertes Testing?

Ja. agent-browser ist ein CLI-Tool, das sich gut in automatisierten Umgebungen einsetzen lässt, solange Chrome/Chromium verfügbar ist. Du kannst:

• End-to-End-Flows als Teil deiner Test-Suites ausführen
• Performance-Traces während Builds erfassen
• Videos von fehlschlagenden Szenarien aufzeichnen

Für CI verwendest du die Installationsmethode, die zu deinem Build-Image passt (npm, Homebrew oder Cargo), und skriptest deine Flows mit Shell-Skripten oder deinem Agent-Framework.

Wie hilft agent-browser KI-Agenten beim Umgang mit komplexen Seiten?

Statt das komplette DOM auszugeben, stellt agent-browser kompakte Snapshots mit stabilen @refs für wichtige Elemente (Links, Buttons, Inputs etc.) bereit. Das reduziert den Tokenverbrauch drastisch und erleichtert es einem KI-Agenten:

• Die Seitenstruktur zu verstehen
• Das richtige Element über einen Ref auszuwählen
• gezielte click, fill und press Commands abzusetzen

references/snapshot-refs.md erklärt, wie Refs generiert werden, wann du sie aktualisieren solltest und welche Best Practices es für robuste Automatisierung gibt.

Unterstützt agent-browser Proxys und Firmennetzwerke?

Ja. Du kannst HTTP-, HTTPS- und SOCKS-Proxys entweder über CLI-Flags (--proxy) oder über Umgebungsvariablen (HTTP_PROXY, HTTPS_PROXY, ALL_PROXY) konfigurieren. references/proxy-support.md behandelt Basis-Konfiguration, authentifizierte Proxys, Bypass-Regeln und Troubleshooting-Tipps.

Wo sollte ich im Repository anfangen, um mehr zu lernen?

Für einen praxisnahen Einstieg in agent-browser:

• Beginne mit SKILL.md für einen Überblick und einen schnellen Einstieg
• Lies references/commands.md für die vollständige Befehlsliste und Optionen
• Sieh dir references/authentication.md, references/session-management.md, references/snapshot-refs.md, references/profiling.md und references/video-recording.md für spezielle Themen an
• Erkunde das Verzeichnis templates/ für fertige Workflow-Skripte, die du an deine eigenen Use Cases anpassen kannst