Tutorial Browser Use: aprire pagine, cliccare pulsanti ed estrarre dati con un Agent IA

Dopo uvx browser-use install, il vero punto in cui ci si blocca spesso è il task. Se scrivi solo “apri il sito e guarda”, l’agent non sa cosa deve considerare completato. Può provare a vuoto, tirare a indovinare o fermarsi troppo presto.

Browser Use è una libreria Python open source che permette all’IA di controllare un browser Chromium per automazione web. Può girare in locale o in un ambiente self-hosted, senza dipendere da Browser Use Cloud. Se hai già chiaro il concetto di Browser Agent, questo tutorial va dall’installazione al primo task riuscito, includendo configurazione sicura, lettura dei risultati e debug degli errori.

Che cos’è Browser Use: la versione in una frase

Browser Use è una Python library for AI browser automation. Permette a un LLM Agent di usare il browser come una persona: navigare, cliccare, digitare, scorrere, estrarre dati e acquisire screenshot.

Il suo perimetro è l’esecuzione locale o self-hosted, non Browser Use Cloud. La libreria open source e il Cloud Agent hanno API diverse. Questa guida resta sul percorso open source; funzioni del Cloud SDK come structured output, human-in-the-loop e live preview sono fuori ambito.

Se ti stai ancora chiedendo “che cos’è un Browser Agent?”, parti dall’articolo concettuale quando sarà pubblicato. Se il concetto è già chiaro, questa guida risponde alla domanda pratica: come lo faccio girare adesso?

Installazione e preparazione: da uv alla chiave API

Al 2026-06-30, README ufficiale e quickstart descrivono questo percorso:

1. Requisito di versione Python

Browser Use richiede Python 3.11 o superiore. L’esempio del quickstart ufficiale crea un venv con Python 3.12, ma puoi scegliere in base al tuo ambiente.

2. Installare uv (consigliato)

uv è un gestore di pacchetti Python moderno sviluppato da Astral. Se non lo hai ancora:

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

3. Inizializzare il progetto e installare browser-use

# Crea la directory del progetto
mkdir my-browser-use
cd my-browser-use

# Inizializza il progetto
uv init

# Installa browser-use con le dipendenze core
uv add "browser-use[core]"

# Sincronizza le dipendenze
uv sync

Se non usi uv, puoi usare anche pip:

Vultr - Cloud server NVMe ad alte prestazioni, 32 location globali, deploy Docker con un clic

Vedi prezzi →Pubbl.

pip install "browser-use[core]"

4. Installare l’ambiente Chromium

Browser Use dipende da Playwright sotto il cofano, quindi prima installa Chromium:

uvx browser-use install

Questo comando scarica e configura Chromium, così l’agent può avviare un’istanza del browser.

5. Configurare la chiave API

Browser Use deve collegarsi a un LLM per capire i task e prendere decisioni. Il quickstart ufficiale consiglia ChatBrowserUse, un modello progettato per task browser.

Crea un file .env nella root del progetto:

# .env
BROWSER_USE_API_KEY=your_api_key_here

Se usi OpenAI, Anthropic, Google Gemini o Ollama locale, inserisci la chiave corrispondente:

OPENAI_API_KEY=your_openai_key
ANTHROPIC_API_KEY=your_anthropic_key
GOOGLE_API_KEY=your_google_key

Scrivere il primo script: template minimo

Lo script minimo richiede tre parti: importare i moduli, creare l’Agent, eseguire il task.

from browser_use import Agent, Browser, ChatBrowserUse
import asyncio

async def main():
    # Crea un'istanza del browser (visibile durante il debug)
    browser = Browser(headless=False)

    # Crea l'istanza LLM
    llm = ChatBrowserUse()

    # Crea l'Agent
    agent = Agent(
        task="Apri quotes.toscrape.com, scorri verso il basso di una schermata, clicca il pulsante 'Next' ed estrai tutte le quote e gli autori della seconda pagina",
        llm=llm,
        browser=browser
    )

    # Esegui il task con limite di passaggi
    history = await agent.run(max_steps=20)

    # Chiudi il browser
    await browser.close()

if __name__ == "__main__":
    asyncio.run(main())

Questo script fa alcune cose:

1. Browser(headless=False): mostra la finestra del browser e rende più semplice il debug. Dopo il debug puoi passare a headless=True.
2. ChatBrowserUse(): usa il modello browser ufficiale. Puoi anche passare a ChatOpenAI(model="gpt-4o") o a un altro modello.
3. task deve essere concreto: non scrivere “apri il sito e guarda”. Scrivi “naviga verso X URL, scorri, clicca il pulsante Y, estrai il contenuto Z”. Task vaghi portano a loop o chiusure anticipate.
4. max_steps=20: limita l’agent a un massimo di 20 azioni. Per il primo task, 10-20 passaggi sono un buon intervallo di debug.

Esegui lo script:

uv run python main.py

Non lasciare l’agent correre all’infinito: max_steps è la linea di sicurezza

max_steps limita il numero di passaggi che l’agent può eseguire. Il valore ufficiale di default è 100, ma per il primo task conviene scendere a 10-20.

Perché serve:

• L’agent può incontrare un clic fallito, una pagina lenta, un popup o un elemento nascosto e ripetere la stessa azione.
• Senza limite può consumare tempo e token senza fare progressi.
• L’obiettivo del primo task è verificare che il ciclo funzioni, non completare un workflow complesso alla perfezione. Un limite più basso fa emergere prima il problema.

Impostazioni consigliate:

# Primo task: 10-20 passaggi
await agent.run(max_steps=20)

# Task complesso: aumenta se serve, ma all'inizio evita di superare 50
await agent.run(max_steps=50)

Configurazione sicura per iniziare

Non partire con il tuo account principale già autenticato e non lasciare che l’agent navighi liberamente su qualsiasi sito. Una configurazione iniziale sicura include:

KiloClaw - OpenClaw gestito per enterprise: orchestrazione agenti IA e routing intelligente

Inizia →Pubbl.

1. Modalità debug headless=False

browser = Browser(headless=False)

La finestra del browser resta visibile. Puoi capire se l’agent clicca nel posto sbagliato, se la pagina si blocca o se la descrizione del task è ambigua. Dopo il debug passa a headless=True.

2. Limitare la navigazione con allowed_domains

browser = Browser(
    headless=False,
    allowed_domains=["quotes.toscrape.com"]
)

allowed_domains impedisce all’agent di navigare verso altri domini. Se il task riguarda un solo sito, mantieni questa limitazione.

Browser Use supporta wildcard di sottodominio come allowed_domains=["*.example.com"], ma non supporta wildcard di TLD. allowed_domains=["example.*"] non verrà riconosciuto. Per un sito fisso, la scelta più stabile è scrivere il dominio completo:

allowed_domains=["quotes.toscrape.com", "github.com"]

3. Usare un profilo isolato, non il Chrome principale

browser = Browser(
    headless=False,
    user_data_dir="./browser_profile"
)

L’agent crea un profilo browser separato. Non accede a cookie, stato di login o dati sensibili del tuo Chrome principale. Questo primo tutorial usa solo pagine pubbliche.

4. Non usare disable_security

Il parametro disable_security disattiva le policy di sicurezza del browser. La documentazione ufficiale lo indica come non consigliato. Se lo trovi in un altro tutorial, salta quel passaggio.

Leggere i risultati: non basta vedere il browser muoversi

agent.run() restituisce un AgentHistoryList. Puoi usare diversi helper per leggere risultato e processo:

history = await agent.run(max_steps=20)

# Risultato finale
result = history.final_result()
print("Risultato finale:", result)

# Contenuto estratto
extracted = history.extracted_content()
print("Contenuto estratto:", extracted)

# Lista degli errori
errors = history.errors()
print("Errori:", errors)

# Se ci sono stati errori
if history.has_errors():
    print("Il task ha incontrato errori")

# Lista degli URL visitati
urls = history.urls()
print("URL visitati:", urls)

# Percorsi degli screenshot
screenshots = history.screenshot_paths()
print("Screenshot:", screenshots)

# Nomi delle azioni eseguite
actions = history.action_names()
print("Azioni:", actions)

# Numero totale di passaggi
steps = history.number_of_steps()
print("Passaggi:", steps)

Un errore comune all’inizio è guardare la finestra del browser muoversi e considerare il task riuscito. Se final_result() è vuoto, l’agent potrebbe essersi fermato troppo presto o aver capito male il task. Se errors() contiene elementi, leggili prima di cambiare il prompt.

Prima serie di task: aprire, cliccare, estrarre

Usa quotes.toscrape.com come primo ambiente. È un sito pubblico creato per esercitarsi con lo scraping, non richiede login e ha una struttura semplice.

task 1: aprire e scorrere

agent = Agent(
    task="Apri quotes.toscrape.com e scorri verso il basso di una schermata",
    llm=ChatBrowserUse(),
    browser=Browser(headless=False, allowed_domains=["quotes.toscrape.com"])
)
history = await agent.run(max_steps=10)
print("URL visitati:", history.urls())

task 2: cliccare un pulsante

agent = Agent(
    task="Apri quotes.toscrape.com e clicca il pulsante 'Next' in fondo alla pagina",
    llm=ChatBrowserUse(),
    browser=Browser(headless=False, allowed_domains=["quotes.toscrape.com"])
)
history = await agent.run(max_steps=10)
print("Successo:", history.is_successful())

task 3: estrarre contenuti

agent = Agent(
    task="Apri quotes.toscrape.com ed estrai tutti i testi delle quote e i relativi autori dalla prima pagina",
    llm=ChatBrowserUse(),
    browser=Browser(headless=False, allowed_domains=["quotes.toscrape.com"])
)
history = await agent.run(max_steps=15)
extracted = history.extracted_content()
print("Contenuto estratto:", extracted)

task 4: combinare i passaggi

agent = Agent(
    task="Apri quotes.toscrape.com, clicca il pulsante 'Next' ed estrai tutti i testi delle quote e i relativi autori dalla seconda pagina",
    llm=ChatBrowserUse(),
    browser=Browser(headless=False, allowed_domains=["quotes.toscrape.com"])
)
history = await agent.run(max_steps=20)
print("Risultato finale:", history.final_result())
print("Errori:", history.errors())

Dove guardare quando fallisce

Quando l’agent restituisce un risultato vuoto, segnala un errore o si blocca, segui questa checklist:

1. Clic fallito

• Controlla se history.errors() contiene “click failed” o “element not found”
• Aggiungi un fallback da tastiera nel task: “se il clic fallisce, usa Tab per mettere a fuoco il pulsante e premi Enter”
• Controlla history.screenshot_paths() per capire se l’elemento era visibile

2. Estrazione vuota

• Controlla history.urls() per confermare che la pagina sia stata davvero aperta
• Controlla history.screenshot_paths() per vedere lo stato della pagina
• Verifica che il task sia specifico: “estrai tutti i testi delle quote e i relativi autori”, non “guarda il contenuto”

3. Pagina bloccata

• Controlla se allowed_domains ha bloccato una navigazione
• Controlla connessione e tempo di caricamento
• Riduci max_steps o aggiungi comportamento di timeout: “se la pagina non carica entro 10 secondi, torna alla home”

4. Risultato incompleto

• Controlla se max_steps ha interrotto il run troppo presto
• Controlla history.number_of_steps() per vedere quanti passaggi sono stati usati
• Riscrivi il task e dividilo in sottotask più piccoli

5. Fallimento complessivo

• Controlla che la chiave API in .env sia corretta
• Conferma che il modello sia supportato: ChatBrowserUse, OpenAI, Anthropic, Google Gemini o Ollama locale
• Verifica se il task è troppo astratto: sostituisci “apri il sito e guarda” con azioni concrete

Beta Agent vs API stabile: due ingressi

Al 2026-06-30, il README ufficiale descrive due percorsi di import per Agent:

API stabile

from browser_use import Agent, Browser

Questo è l’ingresso stabile. Se usavi già Browser Use, puoi continuare con questo percorso.

Alibaba Cloud - Scelta top per sviluppatori, 15% di sconto esclusivo su Lighthouse

Ottieni -15% →Pubbl.

API beta (0.13)

from browser_use.beta import Agent, BrowserProfile, ChatBrowserUse

Questo è il beta agent 0.13, basato su Rust core e browser harness. Il README ufficiale dice che gli utenti esistenti possono restare sull’API stabile, mentre i nuovi possono provare la beta.

Se hai dubbi, controlla il README ufficiale attuale. Questa guida usa esempi stabili; l’API beta può essere diversa.

Open source vs Cloud: capire il confine

Questa guida usa la libreria open source Browser Use in locale.

Browser Use Cloud è un servizio hosted con API diversa:

• Il Cloud SDK usa attualmente API v3
• Cloud offre structured output, human-in-the-loop, live preview, persistent profiles e altre funzioni di produzione
• Il SDK Python/TypeScript Cloud non è compatibile con l’API della libreria open source

Quando ha senso considerare Cloud:

• Deployment in produzione o runtime hosted
• Esigenze avanzate come stealth, CAPTCHA e proxy, non trattate qui
• Account multipli, profili persistenti e collaborazione in team

Questa guida resta sull’onboarding locale. Uso di Cloud e prezzi appartengono a un articolo successivo.

Prossimi passi

Questo tutorial copre l’ingresso locale in Browser Use: installazione, chiavi API, script minimo, apertura di una pagina, clic su un pulsante, estrazione di informazioni e debug degli errori.

Buoni prossimi passi:

• Già pubblicati: guida pratica OpenClaw per l’automazione browser, Computer-Use Agent: far usare il computer all’IA, guida ai plugin MCP
• Temi successivi: Playwright MCP con Claude, Codex e Cursor; ingegneria Stagehand; scelta degli strumenti Browser Use; stato di login e autenticazione; infrastruttura cloud; compliance e sicurezza
• Documentazione ufficiale: quickstart, prompting guide, browser config

Fai funzionare prima un task su quotes.toscrape.com o su una pagina GitHub pubblica. Solo dopo passa a stato di login e Cloud.