Prezzo early bird (fino al 25 dic.), bloccato finché resti abbonato: Go a $10/mese (invece di $20), Plus con Opus 5.5 a soli $30/mese (invece di $50)Abbonati ora →

Browser-Use 1.0: guida a configurazione e migrazione

Se hai costruito qualcosa con browser-use 0.x, la versione 1.0 cambia sia l’architettura sia diversi default. Le 24 azioni browser lasciano il posto a un unico Python REPL persistente, mentre Browser() ora indica un browser cloud. Qui trovi tutto ciò che serve per bloccare la versione 1.0.7, completare il primo avvio e portare il codice 0.x alla nuova release, seguendo le note di rilascio della 1.0.7, MIGRATING.md e il post tecnico del 20 novembre.

Browser-use 1.0 operativo in 5 minuti

Per prima cosa blocca la release. La versione 1.0.0 è arrivata il 10 novembre 2026; il 20 novembre il tag stabile era la 1.0.7, mentre la 1.0.8rc1 si trovava ancora in pre-release (release). Il README dice esplicitamente di non usare mai >=, perché le API possono cambiare tra una minor release e l’altra.

bash
uv add 'browser-use==1.0.7'
# or
pip install 'browser-use==1.0.7'

I requisiti sono abbastanza chiari: Python 3.11 o superiore e inferiore alla 4.0 (README, PyPI). Tutte le dipendenze sono bloccate con ==: una scelta utile per la riproducibilità, ma potenzialmente problematica se la tua applicazione richiede una versione diversa di pydantic, mcp o google-genai.

Autenticati una volta sola. Crea una chiave su cloud.browser-use.com, poi esportala oppure esegui l’helper di login:

bash
export BROWSER_USE_API_KEY=bu_...
# or
browser-use login

Il login salva le credenziali in ~/.config/browser-harness/auth.json e le rende disponibili a CLI, server MCP e browser-harness (MIGRATING.md). Nei container usa BROWSER_USE_AUTO_LOGIN=true; su SSH o su macchine headless, la release candidate 1.0.8 mostra un link e un codice di approvazione da confermare da un altro dispositivo (note della 1.0.8rc1).

Il primo test richiede tre righe:

python
from browser_use import Agent

result = Agent(
    "Find the number of stars of the browser-use repo"
).run_sync()

print(result.final_result())

Attenzione: per impostazione predefinita questa esecuzione genera costi. Usa un browser Browser Use Cloud e il modello gateway predefinito (README Path 1 / Path 3, default di MIGRATING.md). Se vuoi fare una prova senza spendere sul cloud, aggiungi subito Browser('chromium') e specifica il tuo llm.

Che fine hanno fatto le 24 azioni

In browser-use 0.x il modello aveva davanti un menu: a ogni passaggio sceglieva un’azione partendo da un dump del DOM. La versione 1.0 elimina quel menu. Al modello viene fornito un solo strumento principale, python: un REPL persistente con gli helper di browser-harness e il cdp() grezzo già importati, costruito su Pydantic AI (post tecnico):

python
async def python(ctx: RunContext[Session], code: str) -> list[Any]:
    """Run Python in the persistent REPL
    (browser-harness helpers and raw cdp() pre-imported)."""

La rimozione ha eliminato 136.905 righe e ne ha aggiunte 29.601 distribuite su 554 file; i file Python sono passati da 178 a 43 (post tecnico).

La dimostrazione più efficace riguarda il recupero da una pagina bloccata: l’agente ha chiamato Page.stopLoading, fermato lo script incastrato, ricaricato la pagina, individuato l’endpoint JSONP privato e poi recuperato 730 date in batch, ritentando soltanto i batch falliti. Il risultato è stato di 4.720 righe, senza alcuno strumento dedicato a una di queste operazioni (post tecnico).

La regola adottata dal team è semplice: creare un helper solo quando il modello non riesce a riscriverlo dopo averlo letto una volta. L’eccezione è il CAPTCHA. In un piccolo test di staging, le istruzioni in prosa hanno ottenuto 0/3 su hCaptcha, mentre lo strumento dedicato solve_captcha ha raggiunto 6/6, perché attiva un interruttore del solver che la pagina non può raggiungere (post tecnico).

Prima di lasciarti convincere dai numeri su costi e velocità, leggi anche la nota metodologica. Il post del 20 novembre riporta, sugli stessi tre modelli, punteggi superiori di 14–33 punti e costi da 2,7 a 5,2 volte inferiori con la 1.0 rispetto alla 0.x. Il test comprendeva 200 attività, eseguite l’8 novembre, ma solo 180 sono state valutate. Gli autori precisano inoltre che si è trattato di una sola esecuzione per modello e che i default erano cambiati: il nuovo design degli strumenti, quindi, non può prendersi tutto il merito (post tecnico).

I confronti più puliti sono più circoscritti. La versione 1.0.4 ha ottenuto 76,1 contro 76,0 della 1.0.3, mentre il costo del modello è sceso da 0,434 a 0,208 dollari per attività dopo la riduzione degli screenshot nei batch, che ha preservato il prompt caching (note della 1.0.4). In BU Bench v2, la modalità 1.0 ultrafast ha raggiunto 62,5 punti, 0,070 dollari e 650 secondi, contro 56,3 punti, 0,082 dollari e 743 secondi di Browser Use Pi. Gli autori dicono però che il divario perde significatività una volta esclusi gli errori del provider. In sintesi: aspettati qualcosa di più economico e veloce, non automaticamente più intelligente.

I default che cambiano senza avvisare costi e browser

La tabella è compilata usando MIGRATING.md e le note della versione 1.0.6; riflette la 1.0.7 e il cambio del modello predefinito avvenuto nel corso della serie 1.0, spesso assente nelle guide più vecchie.

Impostazione0.x1.0.7
llm=NoneRichiedeva un modellobu-4.0 tramite il gateway Browser Use
Prezzo di bu-4.0n/a1,80 $ / 1 M di input, 9,00 $ / 1 M di output
Prezzo di bu-fastn/a0,12 $ / 1 M di input, 0,60 $ / 1 M di output
Browser()Chromium localeBrowser cloud Browser Use
Browser localePredefinitoBrowser('chromium') da specificare esplicitamente
Chiave APIUna per providerUn’unica BROWSER_USE_API_KEY
max_steps500100 (un passaggio è riservato alla consegna)
Timeout dell’agenteNon specificato1.700 secondi, esclusi avvio e arresto
JudgeDa attivarejudge=True per impostazione predefinita
Ragionamento / modalitàn/areasoning='medium', mode='ultrafast' su bu-fast / bu-ultrafast
Gateway model price per 1M tokens, bu-4.0 versus bu-fast

Ci sono tre trappole da tenere presenti. La prima: il modello predefinito è cambiato nel corso della serie 1.0. Fino alla 1.0.5 il default era bu-fast, ma la 1.0.6 è passata a bu-4.0, con un prezzo per token 15 volte superiore. L’esempio del progetto porta lo stesso test breve a 0,022 $ con bu-4.0, contro 0,0014 $ con bu-fast. Se vuoi mantenere il vecchio profilo di costo, passa esplicitamente llm='bu-fast'. Seconda trappola: un semplice Browser() ora crea un browser cloud al costo di 0,06 $ per ora-browser, a cui si aggiungono modello e ricerche (README); i browser cloud non possono raggiungere localhost o gli IP privati (MIGRATING.md). Terza: un passaggio equivale a una richiesta al modello e a una cella Python. Il limite ridotto a 100 passaggi diventa quindi anche un limite di spesa; max_steps < 1 o timeout <= 0 ora fanno fallire l’esecuzione prima dell’avvio del browser (MIGRATING.md).

Anche il judge introduce una voce di costo poco visibile. Dopo qualsiasi esecuzione con almeno un passaggio, il tuo modello effettua un’ulteriore richiesta a bassa intensità su un trace di massimo 120.000 caratteri e, con la visione attiva, sulle ultime quattro immagini distinte, inclusa la pagina finale. I dati vengono inviati senza redazione (MIGRATING.md). Il risultato finisce in result.judgement, con success, failure_reason, gotchas e i flag per bot/CAPTCHA; il costo confluisce in result.cost_usd. Puoi disattivarlo con judge=False oppure passare judge_context con la risposta attesa. Se gli screenshot non devono mai uscire dal tuo perimetro, imposta use_vision=False.

Quando serve, resta in locale

Scegli il browser in base alla rete che deve raggiungere, non per abitudine. L’identificatore del modello qui sotto è l’esempio illustrativo del provider usato nello snippet del README per il browser locale (README):

python
from browser_use import Agent, Browser, ChatOpenAI

agent = Agent(
    "Summarize the dashboard at http://localhost:3000",
    llm=ChatOpenAI("gpt-6-luna"),
    browser=Browser("chromium"),
)
print(agent.run_sync().final_result())

Usa Browser('chromium') per localhost, reti private, viewport personalizzati o in tutti i casi in cui le chiamate cloud alle metriche del dispositivo non rifletterebbero il viewport reale della pagina. Usa Browser('chrome') per pilotare il tuo Chrome già aperto con i login esistenti; Browser('chrome', profile='Work') avvia una copia temporanea con i login, ma senza sincronizzare le modifiche. Su Windows, chiudi prima il Chrome originale, perché mantiene i cookie bloccati (MIGRATING.md). Il cloud resta la scelta giusta quando servono stealth gestito, proxy, gestione dei CAPTCHA o nessuna configurazione locale (README); considera però separatamente il costo delle ore-browser e quello dei token.

I modelli personalizzati continuano a funzionare, ma il percorso da usare è importante (MIGRATING.md):

  • Alias del gateway: bu-4.0, bu-4.0-mini, bu-4.0-pro, bu-fast, bu-ultrafast, bu-smart
  • Provider: ChatOpenAI, ChatAnthropic, ChatGoogle oppure stringhe Pydantic AI come groq:llama-3.3-70b-versatile
  • Azure tramite llm='azure:<deployment>' con AZURE_OPENAI_ENDPOINT, AZURE_OPENAI_API_KEY e OPENAI_API_VERSION

Gli oggetti chat LangChain passati come Agent(llm=...) ora generano un TypeError, mentre i nomi gateway ritirati, come bu-2-0, vengono rifiutati prima dell’avvio del browser. Ogni agente parallelo deve avere il proprio Browser(); condividere lo stesso browser tra due agenti genera un RuntimeError. In sequenza, invece, puoi riutilizzare un browser con keep_alive=True (MIGRATING.md).

Migra senza tirare a indovinare: lascia parlare gli errori

La versione 1.0 fallisce rapidamente, e lo fa intenzionalmente. Gli import rimossi generano un ImportError che indica il sostituto; gli argomenti non supportati di Agent(...) generano un TypeError; tutto ciò che la 1.0 non può gestire produce un errore prima dell’avvio del browser o dell’addebito (MIGRATING.md). Un gruppo più ristretto di opzioni, tra cui use_vision=True, vision_detail_level, max_actions_per_step, flash_mode, max_failures e highlight_elements, viene invece accettato ma ignorato, con un solo warning per ciascuna. use_vision=False resta significativo, perché impedisce l’invio degli screenshot al modello.

Dopo l’avvio il comportamento cambia: in genere run() restituisce un risultato con errore invece di sollevare un’eccezione, impostando status='error' e mettendo i dettagli in result.error. Solo la cancellazione continua a propagarsi. Di conseguenza, aggiorna anche i controlli:

python
# 0.x
history = await agent.run(max_steps=500)
ok = history.is_successful()

# 1.0
result = await agent.run(max_steps=100)
ok = result.is_done() and result.success is not False

is_done() ora indica soltanto che l’esecuzione è terminata; il successo dipende dal verdetto finish(result, success) del modello, mentre is_successful() restituisce None quando il modello non ha espresso alcun verdetto. I vecchi helper della cronologia per singolo passaggio — action_names(), model_actions(), extracted_content(), save_as_playwright_script() e gli altri elencati tra le API rimosse della cronologia in MIGRATING.md — non esistono più. Al loro posto usa result.messages, result.status, result.partial, i file in agent.workspace e result.judgement.

Comincia da tre modifiche. Sposta max_steps da Agent(...) a agent.run(max_steps=...); sostituisci i callback rimossi (on_step_start, pause, stop, multi_act, save_history) con logging.getLogger('browser_use') a livello INFO oppure con BROWSER_USE_LOGGING_LEVEL=warning; infine rivedi la gestione dei segreti. Ora i segreti con ambito di dominio vengono tipizzati solo sulle pagine corrispondenti, i nomi che terminano in bu_2fa_code vengono trattati come seed TOTP, il vecchio placeholder <secret>name</secret> genera un errore e deve diventare type_secret('name'). Nei contenuti e nei risultati i valori vengono mascherati come <secret:name>: è redazione, non sandbox, perché il codice Python scritto dal modello può comunque leggerli (MIGRATING.md). Se ti serve tempo, blocca pip install 'browser-use<1' e migra su un branch.

"browser use is more a python framework for building your own browsing agent" — u/Starks1293 su r/ClaudeCode

Questa descrizione coincide con il modo in cui gli utenti ne parlano nelle discussioni su Reddit: un framework per costruire agenti di navigazione, citato spesso in relazione a siti protetti da sistemi anti-bot e al controllo a livello di codice. L’affidabilità dipende comunque dal modello e dal sito; un resoconto in produzione parla di cinque minuti e nove passaggi falliti per compilare un modulo di base.

Prima della produzione: judge, segreti e affidabilità variabile

Per gli utilizzi più avanzati, gli elementi importanti sono:

  • Risultati tipizzati tramite output_model_schema, da leggere in result.structured_output
  • Upload nell’area di lavoro e workspace/downloads, con i file disponibili in result.downloads
  • Controlli sui domini (allowed_domains, prohibited_domains, block_ip_addresses), che proteggono da un modello allineato ma non isolano la rete
  • web_search=True da attivare esplicitamente, con il costo di ogni ricerca conteggiato in result.cost_usd
  • CLI/MCP tramite browser-use --cli-mcp, browser-use skill install e browser-use --doctor

Considera la 1.0 un framework in rapido movimento: blocca le versioni esatte, aggiungi judge_context alle attività lunghe, salva il lavoro parziale con checkpoint('titles.json', titles, partial=True) ed esegui i task non affidabili in container, perché i limiti sui domini e la redazione dei segreti non equivalgono a un isolamento (README).

Migrare subito, bloccare la versione o restare su 0.x?

SituazioneScelta consigliata
Nuovo progetto con agente, cloud accettabileParti da ==1.0.7, mantieni bu-4.0 come default e lascia attivo il judge
Job batch sensibili ai costiPassa llm='bu-fast' e judge=False, poi misura prima di aumentare la scala
Localhost / intranet / viewport personalizzatoBrowser('chromium') insieme al tuo modello, mai un semplice Browser()
0.x già in produzioneBlocca browser-use<1 sul ramo principale e migra su un branch sfruttando gli errori fail-fast
Flusso con molti CAPTCHAMetti a budget il solver dedicato: nel test del team le sole istruzioni in prosa hanno ottenuto 0/3

Ottieni un agente capace di bloccare uno script incastrato o chiamare un’API privata che non avevi mai integrato, ma perdi le protezioni offerte da un menu di azioni predefinite. Se questo compromesso funziona per il tuo sito, procedi con la migrazione; in caso contrario, per i sistemi già in produzione l’opzione più prudente resta mantenere browser-use<1 mentre valuti il passaggio.

Domande frequenti

Che cosa cambia in browser-use 1.0?

Un unico Python REPL persistente, con gli helper di browser-harness e CDP grezzo, sostituisce il menu da 24 azioni della serie 0.x e rimuove circa l’80% della libreria, portando i file Python da 178 a 43. I default diventano Browser Use Cloud, un modello gateway e un’unica BROWSER_USE_API_KEY.

Il mio codice 0.x smetterà di funzionare?

I punti d’ingresso principali (Agent, Browser, run(), final_result()) esistono ancora, ma import e opzioni rimossi generano ImportError o TypeError prima di qualsiasi addebito. Inoltre max_steps è stato spostato in run() e Browser() ora indica il cloud. Per restare sulla versione precedente, blocca browser-use<1; in alternativa, esegui prima la migrazione su un branch.

Posso continuare a usare il mio modello e un browser locale?

Sì. Puoi passare provider come ChatOpenAI, ChatAnthropic e ChatGoogle, oppure una stringa Pydantic AI, e usare Browser('chromium') per un browser locale nuovo o Browser('chrome') per il tuo Chrome già aperto. I browser cloud non possono raggiungere localhost.

Quale versione di Python serve a browser-use 1.0?

Python 3.11 o superiore e inferiore alla 4.0. I pin esatti delle dipendenze possono entrare in conflitto con altri pacchetti: prima dell’installazione, quindi, conviene usare un ambiente virtuale pulito.

Come disattivo il judge dell’esecuzione?

Passa judge=False per saltare la richiesta aggiuntiva di valutazione, oppure usa judge_context con i criteri di accettazione per rendere più utile il verdetto. Imposta use_vision=False se gli screenshot del judge non devono essere inviati.