Stagehand: SDK open-source per automazione browser ibrida con AI

Cos'è

Stagehand è un framework open-source, rilasciato da Browserbase sotto licenza MIT, che si propone come ponte tra l'automazione browser classica e gli agenti artificiali. Invece di sostituire Playwright — lo standard industriale per il testing e lo scraping — lo estende con un livello di ragionamento basato su modelli di linguaggio. Il risultato è uno strumento che permette di scrivere automazioni in cui alcuni passaggi restano codice preciso e deterministico, mentre altri vengono delegati a istruzioni in linguaggio naturale.

Il progetto è nato nel 2024 ed è cresciuto rapidamente, raggiungendo oltre 22.000 stelle su GitHub entro la prima metà del 2026. Il repository principale è in TypeScript, ma esistono SDK anche per Python, Kotlin, Java e PHP, rendendo Stagehand accessibile a stack diversi. L'obiettivo dichiarato è rendere le automazioni browser resilienti, leggibili e pronte per la produzione, senza forzare l'utente in un agente completamente autonomo e difficile da controllare.

A cosa serve

Stagehand risolve il problema classico delle automazioni web: i selettori CSS e gli XPath sono precisi e veloci, ma si rompono appena il sito target cambia layout, rinominando classi o spostando elementi. Questo loop di manutenzione è familiare a chi gestisce scraping, test end-to-end, caricamento di form, download da portali B2B o estrazione di dati da registri pubblici.

I casi d'uso tipici includono:

• Estrazione dati strutturata: tirare fuori nomi, indirizzi, partite IVA o recapiti da pagine come LinkedIn, InfoCamere o directory di settore, ottenendo JSON tipizzato anziché HTML grezzo.
• Automazione di portali senza API: scaricare fatture, dichiarazioni o report da aree riservate di fornitori o pubbliche amministrazioni dove non esiste un'interfaccia programmatica.
• Test e QA: scrivere flussi di test che resistono a restyling dell'interfaccia, combinando passaggi deterministici con azioni descritte in linguaggio naturale.
• Competitive intelligence: monitorare prezzi, disponibilità o contenuti di concorrenti senza dover aggiornare gli script a ogni piccolo cambiamento grafico.

In sintesi, Stagehand serve quando il target è troppo dinamico per Playwright puro, ma troppo importante per affidarsi a un agente totalmente autonomo che potrebbe compiere azioni impreviste.

Come funziona

Stagehand si basa su quattro primitive principali, pensate per coprire fasi diverse di un'interazione web.

act()

La primitiva act esegue azioni a partire da un'istruzione in linguaggio naturale. Esempi: "clicca il pulsante di login", "compila il campo CAP", "scorri fino alla sezione recensioni". Il modello legge il DOM, identifica l'elemento target e restituisce l'azione eseguita. Se il sito cambia, l'istruzione rimane valida perché non è legata a un selettore specifico.

extract()

La primitiva extract estrae dati strutturati dalla pagina secondo uno schema definito, solitamente con Zod o Pydantic. Ad esempio, può restituire un oggetto con titolo, autore e data di un articolo, oppure una lista di aziende con nome, settore e città. Questo elimina il parsing manuale del DOM e garantisce output tipizzati, utili per pipeline di dati successive.

observe()

La primitiva observe analizza lo stato corrente della pagina e restituisce cosa è possibile fare, aiutando lo script a decidere se procedere in modalità deterministica o chiedere supporto all'IA. È utile per gestire biforcazioni e condizioni impreviste.

agent() / execute()

Nelle versioni più recenti, Stagehand offre anche una modalità agentica per flussi multi-passo, in cui il modello pianifica e porta avanti autonomamente una sequenza di azioni. A differenza di agenti puri, però, resta possibile interrompere il flusso, ispezionare lo stato e riprendere il controllo programmatico.

Ibrido e caching

Il punto di forza di Stagehand è proprio la commistione: si usano i comandi Playwright classici (page.goto, page.click) per le parti stabili del flusso, e le primitive AI per le parti incerte. Inoltre Stagehand supporta il caching delle azioni: una volta che il modello ha risolto un'istruzione in un determinato DOM, l'azione può essere memorizzata ed eseguita senza ulteriori chiamate LLM, riducendo latenza e costi.

Perché conta

Nel panorama italiano di founder, PMI e agenzie, la capacità di automatizzare il web senza API ufficiali è spesso un vantaggio competitivo. Molti servizi pubblici e privati non offrono endpoint programmatici, e ricorrere a selettori fragili significa manutenzione costante. Stagehand riduce questo attrito mantenendo un approccio DOM-driven, che nel 2026 si è dimostrato più affidabile delle soluzioni basate solo sulla visione artificiale: test pubblici riportano tassi di successo dell'89% su compiti comuni, contro il 75-78% di agenti puramente vision-driven.

Altri motivi di rilevanza:

• Trasparenza e controllo: non è una scatola nera. Lo sviluppatore decide esattamente quando usare l'IA e quando restare nel codice, facilitando audit e debug.
• Flessibilità di provider: Stagehand può usare diversi modelli LLM tramite Vercel AI SDK o il Model Gateway di Browserbase, senza obbligare a un singolo fornitore.
• Self-hosting possibile: funziona in locale con Chromium e non richiede necessariamente l'infrastruttura cloud di Browserbase, anche se quest'ultima offre vantaggi a scale elevate.
• Licenza MIT: può essere integrato in prodotti commerciali, modificato e redistribuito.
• Costo prevedibile: una chiamata act costa tipicamente tra $0,002 e $0,01, mentre extract tra $0,005 e $0,02 con modelli come GPT-4.1: molto meno di un agente completamente autonomo che richiede decine di passaggi.

Limiti e quando sceglierlo

Stagehand non è la risposta a tutto. Se il sito target è estremamente stabile e le automazioni sono ad alto volume, Playwright puro resta più veloce ed economico, perché non paga il costo dei token LLM. Se invece serve interagire con interfacce grafiche basate su canvas, mappe o applicazioni dove il DOM è poco informativo, gli agenti vision-driven come Anthropic Computer Use o OpenAI CUA sono più adatti.

Inoltre, Stagehand richiede ancora di scrivere codice: non è un no-code tool. Chi cerca un flusso completamente autonomo e black-box potrebbe preferire librerie come Browser Use, che cede il controllo totale al modello. Infine, essendo un progetto relativamente giovane rispetto a Playwright, alcuni casi limite possono richiedere interventi manuali o attesa di fix dalla community.

Dove trovarlo

• Repository GitHub: https://github.com/browserbase/stagehand (licenza MIT)
• Sito ufficiale: https://stagehand.dev
• Documentazione: https://docs.stagehand.dev
• Package npm: @browserbasehq/stagehand
• Package PyPI: stagehand
• Community: Discord ufficiale raggiungibile dal repository

Per provarlo in pochi minuti, basta installare il pacchetto TypeScript o Python, configurare una chiave per un modello LLM e scrivere il primo script che combini una page.goto di Playwright con un extract in linguaggio naturale.