Agent Browser

Browser Automation with agent-browser

CLI per browser automation ottimizzata per agenti AI (Vercel Labs). Browser visibile con cookie persistenti, dev tools completi e video streaming.

Requisiti

npm install -g agent-browser
agent-browser install  # Scarica Chromium (~684MB)

HOW IT WORKS

agent-browser mantiene la sua sessione browser con cookies.

• Login una volta → cookies salvati → autenticazione persistente
• WARNING: agent-browser close CANCELLA TUTTI I COOKIES - dovrai fare re-login!
• Per mantenere l'autenticazione: MAI chiudere la sessione, naviga solo verso nuovi URL

WORKFLOW COMPLETO

1. Apri Browser (PATTERN OBBLIGATORIO)

# SEMPRE usa questo pattern alla prima apertura - setta viewport a 1920x1080:
pkill -f agent-browser; sleep 1; agent-browser open <url> --headed && agent-browser set viewport 1920 1080

# Se il browser è già in esecuzione, naviga semplicemente:
agent-browser open <url> --headed

2. Gestisci Cookie Banner (OBBLIGATORIO su siti pubblici)

Dopo aver aperto una pagina, SEMPRE:

1. Esegui agent-browser snapshot -i per verificare banner cookie consent
2. Se presente: clicca "Accept" / "Accetta" / "Accept all"
3. A meno che l'utente non chieda esplicitamente di mantenerlo (per debug)

agent-browser snapshot -i                     # Cerca cookie banner
agent-browser click @eX                       # Clicca accept (usa il @ref corretto)

3. Analizza Pagina

agent-browser snapshot -i                     # Elementi interattivi con @refs
agent-browser snapshot -i -c                  # Output compatto

4. Interagisci (usa @refs da snapshot)

agent-browser click @e1                       # Click elemento
agent-browser fill @e2 "text"                 # Clear e riempi input
agent-browser type @e2 "text"                 # Digita senza cancellare
agent-browser press Enter                     # Premi tasto
agent-browser select @e1 "value"              # Seleziona dropdown
agent-browser scroll down 500                 # Scroll pagina
agent-browser hover @e1                       # Hover elemento
agent-browser check @e1                       # Seleziona checkbox
agent-browser dblclick @e1                    # Doppio click
agent-browser uncheck @e1                     # Deseleziona checkbox
agent-browser scrollintoview @e1              # Scroll a elemento

5. Ottieni Informazioni

agent-browser get text @e1                    # Testo elemento
agent-browser get value @e1                   # Valore input
agent-browser get html @e1                    # HTML elemento
agent-browser get attr data-id @e1            # Attributo elemento
agent-browser get title                       # Titolo pagina
agent-browser get url                         # URL corrente
agent-browser get box @e1                     # Bounding box elemento
agent-browser get count @e1                   # Numero elementi matching

6. Naviga

agent-browser open <url>                      # Vai a URL (mantiene cookies!)
agent-browser back                            # Indietro
agent-browser forward                         # Avanti
agent-browser reload                          # Ricarica pagina

7. Attendi

agent-browser wait @e1                        # Attendi elemento
agent-browser wait 2000                       # Attendi millisecondi
agent-browser wait --text "Success"           # Attendi testo
agent-browser wait --load networkidle         # Attendi rete

8. Screenshot

mkdir -p .agent-screenshots
agent-browser screenshot .agent-screenshots/YYYYMMDD-HHMMSS-description.png
agent-browser screenshot .agent-screenshots/YYYYMMDD-HHMMSS-description.png --full

DEV TOOLS (SEMPRE USA --json!)

Console Logs (CRITICO - sempre usa --json!)

agent-browser console --json                  # Vedi TUTTI i log (log, warn, error, debug)
agent-browser console --clear                 # Pulisci buffer console
agent-browser errors --json                   # Solo errori pagina

Cookies & Storage

agent-browser cookies get --json              # Ottieni tutti i cookies
agent-browser cookies clear                   # Pulisci cookies
agent-browser storage local --json            # Ottieni localStorage
agent-browser storage session --json          # Ottieni sessionStorage

Network Requests

agent-browser network requests --filter "" --json    # Vedi richieste catturate
agent-browser network requests --clear               # Pulisci buffer richieste
agent-browser network route "*/api/*" --abort        # Blocca richieste
agent-browser network route "*/api/*" --body '{"mock":true}'  # Mock response
agent-browser network unroute                        # Rimuovi tutte le route

Esegui JavaScript

agent-browser eval "window.location.href"            # Esegui JS, ottieni risultato
agent-browser eval "document.title"
agent-browser eval "localStorage.getItem('key')"
agent-browser eval "console.log('test')"             # Log in console

Debug Helpers

agent-browser highlight @e1                   # Evidenzia elemento visivamente
agent-browser trace start                     # Inizia registrazione trace
agent-browser trace stop ./trace.zip          # Ferma e salva trace file

VIDEO STREAMING

Abilita streaming video real-time via WebSocket:

# Avvia con streaming abilitato (porta 9223)
pkill -f agent-browser                        # Termina daemon esistente
AGENT_BROWSER_STREAM_PORT=9223 agent-browser open <url> --headed

# Connetti via WebSocket a ws://localhost:9223
# Ricevi: {"type":"frame","data":"<base64 JPEG>"} per frame video
# Ricevi: {"type":"status","connected":true,"screencasting":true}

REGOLE (IMPORTANTI!)

1. Prima apertura: SEMPRE usa il pattern pkill+open+viewport dalla sezione 1
2. Cookie banner: SEMPRE dismissalo su siti pubblici (accetta cookies), a meno che l'utente non chieda di mantenerlo per debug
3. --headed: SEMPRE usalo per il comando open (l'utente deve vedere il browser)
4. --json: SEMPRE usalo per console, errors, cookies, storage, network
5. snapshot prima di interagire: SEMPRE ottieni @refs freschi prima di click/fill
6. ri-snapshot dopo navigazione: Cambio pagina = nuovi @refs
7. screenshots: Salva in .agent-screenshots/YYYYMMDD-HHMMSS-description.png
8. MAI chiudere sessione: close cancella cookies = ri-login richiesto!

AUTENTICAZIONE

Per siti che richiedono login:

1. Naviga alla pagina login
2. Usa fill per credenziali, click per submit
3. I cookies sono salvati automaticamente
4. Le navigazioni future mantengono l'autenticazione

BROWSER SETTINGS

agent-browser set viewport 1920 1080          # Dimensione viewport
agent-browser set media dark                  # Dark mode
agent-browser set media light                 # Light mode
agent-browser set headers '{"Accept-Language": "it-IT"}'   # Italiano
agent-browser set headers '{"Accept-Language": "en-US"}'   # Inglese

SESSION MANAGEMENT

agent-browser session list                    # Lista sessioni attive
agent-browser session                         # Nome sessione corrente

CRITICO: agent-browser close DISTRUGGE la sessione e TUTTI i cookies!

• Dopo close, DEVI ri-loggarti sui siti autenticati
• Per preservare auth: naviga semplicemente con open <url>, mai close
• Usa close solo quando hai completamente finito O vuoi un fresh start

LOCATORI SEMANTICI (alternativa a refs)

agent-browser find role button click --name "Submit"
agent-browser find text "Accedi" click
agent-browser find label "Email" fill "user@test.com"
agent-browser find placeholder "Cerca..." fill "query"
agent-browser find testid "submit-btn" click

SESSIONI MULTIPLE (Analisi Parallela)

# Sessione 1: Competitor A
agent-browser --session compA open https://competitor-a.com --headed
agent-browser --session compA wait --load networkidle
agent-browser --session compA snapshot -i

# Sessione 2: Competitor B (in parallelo)
agent-browser --session compB open https://competitor-b.com --headed
agent-browser --session compB wait --load networkidle
agent-browser --session compB snapshot -i

ENVIRONMENT VARIABLES

AGENT_BROWSER_SESSION=mySession               # Sessione isolata
AGENT_BROWSER_EXECUTABLE_PATH=/path/chrome    # Browser custom
AGENT_BROWSER_STREAM_PORT=9222                # WebSocket streaming

OUTPUT JSON (per parsing)

agent-browser --json snapshot -i
agent-browser --json get text @e1

TROUBLESHOOTING

"Browser not launched" error:

pkill -f agent-browser; sleep 1; agent-browser open <url> --headed

Browser non risponde:

pkill -f agent-browser                        # Termina daemon (perde cookies!)
agent-browser open <url> --headed             # Restart fresh (serve re-login)

Console/Cookies mostrano vuoto:

# SEMPRE usa --json per dev tools:
agent-browser console --json                  # Corretto
agent-browser console                         # Sbagliato - può mostrare vuoto

Cookie banner non rilevato:

# Esegui snapshot per vedere tutti gli elementi interattivi:
agent-browser snapshot -i

# Cerca bottoni con testo tipo "Accept", "Accetta", "OK", "Agree"
# Poi clicca il @ref corretto

Sessione persa / Serve re-login:

# NON usare 'close' - cancella tutti i cookies!
agent-browser close                           # Distrugge sessione

# Invece, naviga semplicemente verso nuovi URL:
agent-browser open <new-url>                  # Mantiene cookies

Elemento non trovato:

# SEMPRE ri-snapshot dopo navigazione o cambio pagina:
agent-browser open <url>
agent-browser snapshot -i                     # Ottieni @refs freschi
agent-browser click @e1                       # Usa nuovi refs

vs Playwright MCP

QUANDO USARE AGENT-BROWSER

• Web scraping e data extraction
• Analisi competitor (struttura, contenuti)
• Clonazione UI per reverse engineering
• Navigazione con autenticazione persistente
• Analisi multi-sito parallela
• Debug interattivo con browser visibile
• Form automation su siti reali

QUANDO USARE PLAYWRIGHT MCP

• Test E2E automatizzati
• Visual regression testing
• CI/CD pipelines (GitHub Actions)
• Integrazione con framework di test (Vitest/Jest)