Guide

Stagehand, l'automatisation du navigateur pilotée par un LLM

Stagehand 4 pilote un navigateur par des phrases (act, observe, extract) : licence MIT, mode local ou Browserbase, cache serveur, coûts et limites.

L'équipe CodeWorlds14 min de lecture ·

Pratique HTML et CSS dans des leçons interactives avec un éditeur de code.

Crée un compte gratuit→
Dans cet article9

Stagehand est une bibliothèque de contrôle du navigateur où tu décris une action en une phrase et où un modèle la transforme en clics et en saisie. La version 4.0.2, sortie le 20 août 2026, est sous licence MIT et fonctionne en local, mais la mise en cache des actions et le choix automatique du modèle ne marchent que sur l'infrastructure payante de Browserbase.

Ce qu'est Stagehand et ce que la version 4 a changé

La bibliothèque te donne trois méthodes pilotées par un modèle plus un pilote de navigateur déterministe complet à côté. act exécute une seule action décrite en une phrase, observe renvoie une liste d'éléments cliquables avec des sélecteurs prêts à l'emploi, et extract récupère des données structurées selon un schéma Zod ou Pydantic. À côté se trouve la classe Page avec goto, click, type, keyPress, screenshot, snapshot, evaluate, waitForSelector et locator, plus la classe Locator avec click, fill, innerText, selectOption, setInputFiles, nth et first.

La version 4 a changé les fondations. Le paquet 3.7.2 déclarait playwright-core en ^1.55.1 comme peer dependency facultative, à côté de puppeteer-core et de patchright-core. Le paquet 4.0.2 n'en a aucune. Il embarque à la place son propre client Chrome DevTools Protocol et une extension de navigateur : le tarball contient un répertoire dist/extension avec un service-worker.js d'environ deux mégaoctets et un manifest.json version trois qui demande les permissions debugger, offscreen, scripting et tabs plus l'accès à toutes les URL.

Cette distinction compte en pratique. Les noms de méthodes ressemblent à ceux de Playwright, mais ce n'est pas Playwright, c'est une implémentation séparée avec une interface similaire. Les plugins, les reporters, le expect du lanceur de tests et le reste de l'écosystème ne se transposent pas automatiquement. L'inférence du modèle se fait dans l'extension, qui appelle elle-même api.openai.com, api.anthropic.com, generativelanguage.googleapis.com, api.groq.com ou api.cerebras.ai, selon le fournisseur choisi.

Version, licence et contenu du paquet

J'ai vérifié la licence à trois endroits et la réponse est cohérente. Le fichier LICENSE du dépôt browserbase/stagehand contient le texte MIT avec la ligne Copyright (c) 2024 Browserbase Inc. Le champ license du registre npm pour @browserbasehq/stagehand indique MIT. Le tarball publié stagehand-4.0.2.tgz contient seize fichiers, dont package/LICENSE avec le même texte, et le code est réel : dist/index.mjs pèse 192 kilooctets, les déclarations de types dist/index.d.mts 244 kilooctets de plus, et l'ensemble se décompresse en environ 3,3 mégaoctets. Ce n'est ni une coquille vide ni un espace réservé.

Une petite divergence concerne le paquet Python. Le wheel stagehand-4.0.2-py3-none-any.whl déclare License-Expression: MIT dans ses métadonnées et contient quarante fichiers de vrai code, mais son répertoire dist-info n'a aucun fichier de texte de licence, seulement METADATA, WHEEL et RECORD. Si ton audit de dépendances exige un fichier de licence physique dans l'artefact, le build Python a besoin qu'on lui en ajoute un tiré du dépôt. Le README précise que Stagehand est une marque déposée de Browserbase, ce qui limite l'usage de la marque elle-même, pas du code.

Le projet paraît actif. Le dépôt compte environ 24 mille étoiles, les versions 4.0.0, 4.0.1 et 4.0.2 sont sorties respectivement les 10, 14 et 20 août 2026, et la branche 3.7.2 a reçu une version le même jour que la 4.0.2. La fraîcheur de la version majeure est un risque en soi : j'écris sur une bibliothèque dont la version majeure a douze jours, donc beaucoup d'exemples en ligne et de réponses de modèles décrivent encore l'interface de la version 3.

Les exigences techniques peuvent surprendre. Le champ engines demande Node 22.18.0 ou plus récent, et exports n'expose que le build ESM, donc require ne fonctionnera pas. La dépendance zod est figée exactement sur 4.4.3, sans plage.

En local ou Browserbase

La bibliothèque fonctionne sans compte Browserbase, et cela répond à la question la plus importante sur l'enfermement chez le fournisseur. La fabrique localBrowser.launch() démarre Chrome sur ta machine, et localBrowser.connect({ cdpUrl }) se connecte à un navigateur que tu exécutes déjà à l'adresse donnée. Les options de launch comprennent headless, executablePath, userDataDir, preserveUserDataDir, proxy, viewport, downloadsPath et chromiumSandbox, entre autres. Aucune clé Browserbase n'est requise nulle part dans ce chemin.

Trois choses cessent de fonctionner en dehors du cloud de l'éditeur, et les trois comptent. D'abord le cache : le constructeur de contexte dans le code de l'extension renvoie undefined quand apiKey ou sessionId manque, et un navigateur local n'a pas d'identifiant de session Browserbase. L'option cache devient un poids mort et chaque appel paie le plein prix de l'inférence. Ensuite la Model Gateway, le mode sans champ model dans lequel l'éditeur choisit un modèle pour chaque appel. La documentation indique clairement qu'il lui faut un navigateur hébergé, car il n'y a rien à facturer ni à autoriser sinon. Enfin toute la couche d'infrastructure : proxys, mode furtif, enregistrements de sessions, choix de région et mise à l'échelle de sessions parallèles.

En local, tu dois donc fournir ta propre clé de modèle dans model.apiKey ou fournir ta propre fonction generate qui dialogue avec n'importe quel fournisseur, y compris un modèle exécuté sur ton propre matériel. Les préfixes de noms de modèles pris en charge sont openai/, anthropic/, google/, groq/ et cerebras/, donc un compte chez OpenAI ou un accès à Claude suffit.

Trois méthodes d'IA et le chemin de retour vers les sélecteurs

L'exemple local le plus simple ressemble à ceci.

Bash
node --version   # 22.18.0 or newer required
npm install @browserbasehq/stagehand zod
export OPENAI_API_KEY="sk-..."
TypeScript
import { localBrowser, Stagehand } from '@browserbasehq/stagehand'
import { z } from 'zod/v4'

const browser = await localBrowser.launch({ headless: false })

const stagehand = await Stagehand.create({
  browser,
  model: {
    modelName: 'openai/gpt-5.4-mini',
    apiKey: process.env.OPENAI_API_KEY
  },
  selfHeal: true,
  domSettleTimeoutMs: 3000
})

const page = await browser.context.activePage()
await page.goto('https://news.ycombinator.com')

const { data, metadata } = await stagehand.extract(
  'list the title and score of the first three entries',
  z.object({
    items: z.array(z.object({ title: z.string(), points: z.number() }))
  }),
  { screenshot: false }
)

console.log(data.items, metadata.usage.inputTokens, metadata.usage.inferenceTimeMs)
await stagehand.close()
await browser.close()

Le motif le plus intéressant est celui où le modèle travaille une fois puis s'efface. observe renvoie un tableau d'objets avec les champs selector, description, method et arguments. Tu peux conserver le sélecteur de ton côté et l'utiliser directement lors des exécutions suivantes, sans aucun appel au modèle.

TypeScript
const { data: actions } = await stagehand.observe('find the login button')

// deterministic path: click by selector, zero tokens
await page.locator(actions[0].selector).click()

// model path, for when the page changed and the selector no longer matches
await stagehand.act('click the login button', {
  timeout: 20000,
  variables: {
    login: { value: process.env.APP_LOGIN!, description: 'user name' }
  }
})

const metrics = await stagehand.metrics()
console.log(metrics.actPromptTokens, metrics.totalInferenceTimeMs)

Le champ variables existe pour que tu ne colles pas de mots de passe dans le texte de l'instruction, qui part vers le modèle et devient une partie de la clé de cache. Les options locator et ignoreLocators restreignent la partie de la page sur laquelle le modèle travaille, ce qui raccourcit le contexte et réduit la facture.

Le cache côté serveur

Un mécanisme de cache existe, mais il n'est pas ce qu'il paraît au premier regard, comme le confirme la documentation du cache. Le cache ne vit pas sur le disque à côté de ton projet, il vit dans un service à api.stagehand.browserbase.com, avec des endpoints séparés pour les régions us-west-2, us-east-1, eu-central-1 et ap-southeast-1. Les requêtes vont vers les routes /cache/get et /cache/set avec un en-tête x-bb-api-key, et le projet est déterminé à partir de l'identifiant de session.

La clé est construite à partir de la méthode, de l'URL de la page, de l'arbre d'accessibilité collecté via CDP et des options que tu as passées. La configuration du modèle est délibérément exclue de la clé, donc changer de modèle n'invalide pas les entrées stockées. Par-dessus se trouve un seuil de succès : le champ threshold dit combien de fois l'éditeur doit voir un résultat identique avant de commencer à le servir. Une valeur de 1 signifie un succès à la deuxième exécution, une valeur plus élevée retarde le moment où un résultat est considéré comme stable.

Chaque résultat de act, observe et extract porte un objet metadata.cache avec le statut HIT, MISS ou DISABLED. Un succès te donne count, threshold et tokensSaved, un échec te donne missReason, avec la distinction entre replay_failed, quand une entrée a été trouvée mais n'a pas pu être rejouée, et read_failed, quand la requête de cache elle-même a échoué. Le statut DISABLED est celui que tu vois toujours quand tu travailles en local.

TypeScript
import { browserbase, Stagehand } from '@browserbasehq/stagehand'

const browser = await browserbase.launch({
  apiKey: process.env.BROWSERBASE_API_KEY!,
  region: 'eu-central-1'
})

const stagehand = await Stagehand.create({
  browser,
  cache: { threshold: 2 }
})

const result = await stagehand.act('click the first search result', {
  cache: { threshold: 1 }
})

if (result.metadata.cache.status === 'HIT') {
  console.log('tokens saved:', result.metadata.cache.tokensSaved?.totalTokens)
} else {
  console.log('miss reason:', result.metadata.cache.missReason)
}

Deux factures : l'infrastructure et le modèle

La première facture est celle de Browserbase. Le plan gratuit donne trois navigateurs simultanés, une heure de navigateur, trois exécutions d'agent, mille appels Search et mille appels Fetch, des sessions plafonnées à quinze minutes, sept jours de conservation des données et cinq dollars de tokens. Le plan Developer coûte 20 dollars par mois et donne 25 navigateurs simultanés et cent heures, puis 0,12 dollar par heure. Le plan Startup coûte 99 dollars par mois, cent navigateurs simultanés, cinq cents heures, puis 0,10 dollar par heure, et trente jours de conservation. Le plan Scale est chiffré individuellement.

La page des tarifs n'a pas de bascule de facturation annuelle ni de prix annuel, donc douze mois du plan Developer font simplement 240 dollars, sans remise. J'ai trouvé une divergence au sein de la page des tarifs elle-même : la carte du plan Startup indique le dépassement Fetch à 1 dollar pour mille appels, tandis que le tableau comparatif plus bas sur la même page indique 0,50 dollar pour mille pour le même plan. Les deux chiffres y figurent aujourd'hui, donc confirme le tarif auprès de l'éditeur avant de bâtir un budget dessus.

La seconde facture est celle du modèle. Chaque act, observe et extract qui rate le cache est un appel au modèle avec l'arbre d'accessibilité de la page dans le contexte. En local, tu le paies à chaque fois, et tu le paies séparément, sur la facture du fournisseur du modèle. La Model Gateway fusionne les deux factures en une, au prix de devoir faire vivre le navigateur chez l'éditeur. Avant de chiffrer une campagne de scraping, collecte metrics() sur une seule exécution et multiplie par le nombre de pages.

Quand le langage naturel aide et quand il nuit

Un sélecteur CSS est gratuit, instantané et déterministe : il correspond ou non. Une phrase en langage naturel coûte un appel au modèle, prend des centaines de millisecondes ou des secondes, et à l'exécution suivante peut choisir un autre élément parce que la page a bougé ou que le modèle a répondu différemment. Ce n'est pas un défaut d'implémentation, c'est une propriété de l'outil.

Pour une suite de non-régression stable, Stagehand est le mauvais choix. Un test de non-régression doit produire le même résultat à chaque exécution, et un voyant rouge doit signifier un bug dans l'application, pas un caprice du modèle. C'est le rôle de Playwright ou de Cypress, avec la couche de logique testée dans Vitest. Stagehand est rentable là où la page appartient à quelqu'un d'autre et change sans prévenir : le scraping de services sans API, le remplissage de formulaires dans des portails partenaires, l'extraction de données depuis des dashboards que personne ne versionne.

CritèreStagehand 4.0.2browser-use 0.13.8Playwright 1.62.1
Contrôlephrase plus sélecteurstâche pour un agentsélecteurs uniquement
Moteurclient CDP et extension propresChromium via CDPpilotes propres
LicenceMITMITApache 2.0
LangagesTypeScript, Python, GoPythonTypeScript, Python, Java, .NET
Coût par appeltokens du modèletokens du modèlezéro
Répétabilitédépend du modèle et du cachedépend du modèletotale
Cache d'actionscôté serveur, Browserbase uniquementaucun intégrésans objet
Exécution localeoui, sans compte chez l'éditeurouioui

La configuration hybride raisonnable ressemble à ceci : lance observe une fois, enregistre les sélecteurs dans ton dépôt, et garde act comme chemin de secours pour quand un sélecteur stocké cesse de correspondre. Tu paies alors le modèle au changement, pas à chaque exécution. La comparaison avec browser-use se ramène au niveau d'abstraction : là-bas, tu décris l'objectif de toute la tâche et tu confies à l'agent le contrôle de la boucle, ici tu pilotes pas à pas et tu peux redescendre à un sélecteur brut à tout moment.

Erreurs fréquentes

La première erreur est d'attendre de cache: true qu'il fasse quoi que ce soit avec un navigateur local. Il ne fait rien, et le seul signal est le statut DISABLED dans les métadonnées, que personne ne lit.

La deuxième est de mettre act dans une suite de non-régression et d'être surpris qu'une exécution sur vingt donne un résultat différent. Le même effet vient de la Model Gateway sans modèle figé : si l'éditeur choisit un modèle à chaque appel, deux exécutions peuvent utiliser des modèles différents.

La troisième est de copier des exemples de la version 3, où les méthodes étaient accrochées à l'objet page. Dans la version 4, act, observe et extract sont des méthodes de l'instance Stagehand, et la page sert à la navigation et aux sélecteurs.

La quatrième concerne l'environnement : un Node antérieur à 22.18.0, ou un projet CommonJS. Le paquet n'exporte que de l'ESM et require plantera tout simplement.

La cinquième est de coller des mots de passe directement dans l'instruction au lieu de variables. L'instruction part vers le modèle et devient une partie de la clé de cache.

La sixième est d'ignorer le coût du contexte. Sans locator ni ignoreLocators, le modèle reçoit l'arbre d'accessibilité de la page entière, et tu le paies à chaque échec de cache.

FAQ

Stagehand fonctionne-t-il sans compte Browserbase ?

Oui. localBrowser.launch() démarre Chrome sur ta machine et localBrowser.connect({ cdpUrl }) se connecte à un navigateur que tu exécutes déjà. Il te faut alors ta propre clé de modèle ou ta propre fonction generate. Sans compte chez l'éditeur, tu perds le cache, la Model Gateway, les proxys, le mode furtif et les enregistrements de sessions.

Stagehand remplacera-t-il Playwright dans les tests ?

Pas dans les tests de non-régression. Un appel au modèle ne comporte aucune garantie de répétabilité, et un test qui passe au rouge une fois toutes les quelques dizaines d'exécutions sans changement de code cesse d'être utile. Stagehand convient aux parcours exploratoires et aux pages que tu ne contrôles pas.

Combien coûte un appel act ?

Cela dépend du modèle et de la taille de l'arbre d'accessibilité de la page, donc il n'y a pas de chiffre unique. Mesure-le toi-même : metadata.usage renvoie inputTokens, outputTokens, reasoningTokens et inferenceTimeMs pour un seul appel, et stagehand.metrics() agrège les mêmes chiffres répartis entre act, extract et observe.

En quoi Stagehand diffère-t-il de browser-use ?

Par le niveau de contrôle. browser-use prend un objectif et pilote lui-même la boucle de l'agent. Stagehand exécute une action par appel, renvoie des sélecteurs via observe et te laisse retomber à tout moment sur un page.locator() déterministe. Stagehand fournit aussi des SDK officiels pour TypeScript, Python et Go.

Quel est le coût de la migration de la version 3 vers la 4 ?

Ce sont les fondations qui ont changé, pas seulement les noms. La dépendance playwright-core a disparu, les méthodes d'IA sont passées de l'objet page à l'instance Stagehand, le navigateur est créé par une fabrique et passé à Stagehand.create, et la version de Node requise est montée à 22.18.0. La branche 3.7.x reçoit encore des versions, donc la migration n'a pas à se faire d'un coup.

À lire aussi