Stagehand

Stagehand est un SDK d'automatisation de navigateur open-source conçu par Browserbase qui comble le fossé entre les scripts à sélecteurs CSS fragiles et les agents entièrement autonomes imprévisibles. Lancé en octobre 2024 et désormais en v3, il offre aux développeurs TypeScript et Python trois primitives composables, act(), extract() et observe(), ainsi qu'un mode agent() autonome, chacun soutenu par le LLM de votre choix. Là où un script Playwright traditionnel code en dur page.click('#submit-btn') et se casse dès qu'un designer renomme une classe, Stagehand résout act("click the submit button") par rapport au DOM en direct lors de l'exécution, de sorte que le script survit aux refontes trimestrielles de l'interface utilisateur avec zéro maintenance.

Le framework est sous licence MIT et peut être exécuté gratuitement en local sur n'importe quelle instance Chromium. Il s'associe au runtime cloud géré de Browserbase (optionnel, payant) pour les proxys résidentiels, la navigation furtive, la résolution de CAPTCHA et l'enregistrement de session. Stagehand prend en charge OpenAI, Anthropic Claude et Google Gemini via le Vercel AI SDK, et l'architecture directe Chrome DevTools Protocol (CDP) de la v3 le rend agnostique vis-à-vis des modèles et des pilotes. En avril 2026, le dépôt GitHub compte 22,400 étoiles, 1,500 forks et 57 versions, avec un portage Python publié en parallèle de la série B de $40M de Browserbase en juin 2025.

Ce que Stagehand fait réellement en avril 2026

Stagehand v3, sorti le 29 octobre 2025, a entièrement supprimé la dépendance stricte à Playwright et a reconstruit le framework sur une communication CDP directe. Le changement d'architecture a été significatif : Stagehand n'hérite plus des hypothèses orientées test de Playwright, et il prend en charge Puppeteer, Playwright, Bun ou tout autre pilote compatible CDP en tant que backend modulaire. Sur les iframes et les interactions shadow-root, là où les outils basés sur des sélecteurs ont le plus de mal, la v3 est 44.11% plus rapide que la v2.

Les quatre primitives accomplissent chacune une tâche distincte. act() effectue des actions de navigation à partir d'anglais courant ("click the next page button," "fill the email field with [email protected]"). extract() extrait des données structurées d'une page et les valide par rapport à un schéma Zod, de sorte que vous récupérez des objets typés plutôt que du HTML brut. observe() fait remonter les éléments interactifs existants sur une page avant que vous ne vous engagiez dans une action, ce qui est utile pour la logique conditionnelle et les contrôles de sécurité. agent(), ajouté dans la v2, exécute des flux de travail en plusieurs étapes de manière autonome lorsque vous souhaitez une exécution de bout en bout sans orchestrer chaque étape manuellement.

La v3 a également introduit un constructeur de contexte qui ne fournit aux modèles que le sous-ensemble pertinent du DOM par action, plutôt que de déverser la page entière. Cela réduit considérablement le gaspillage de tokens et rend le coût par action plus prévisible. La mise en cache côté serveur, ajoutée dans la v3.1.0 (février 2026), stocke les résultats de act/extract/observe afin que les exécutions répétées du même flux ignorent entièrement l'inférence LLM une fois que le flux de travail se stabilise.

"Nos flux de travail Stagehand v3 sont nettement plus réactifs lorsqu'ils sont exécutés côte à côte avec la v2. Nous bénéficions désormais d'une observabilité détaillée et de rapports au niveau des tokens par action." - Steve Austin, cofondateur et CTO chez Benny, blog de lancement de Stagehand v3, octobre 2025

La prise en charge des modèles couvre GPT-4o, Claude 3.7 Sonnet, Gemini 2.0 et les versions plus récentes de chaque famille. Les conclusions internes de l'équipe : Claude gère mieux les étapes nécessitant beaucoup de raisonnement, les variantes de GPT-4o exécutent des actions précises de manière plus fiable, et Gemini convient aux tâches d'observation. La conception agnostique du framework vous permet de diriger différentes primitives vers différents modèles au sein d'un même script, bien que la plupart des équipes en choisissent un et s'y tiennent.

Où se situe Stagehand par rapport à Playwright et Browser-Use

Playwright (sans IA) est la référence à laquelle se mesure tout outil d'automatisation de navigateur par IA. Il est purement déterministe : chaque action nécessite un sélecteur explicite ou un localisateur de rôle, zéro coût LLM par action, et une vitesse d'exécution inférieure à 100ms par étape. Sur des interfaces utilisateur stables, les scripts Playwright écrits à la main accomplissent les tâches à 92-98%. Le coût de cette fiabilité est la maintenance : chaque refonte majeure de l'interface utilisateur casse 15-25% des sélecteurs, nécessitant l'intervention d'un ingénieur pour mettre à jour les scripts. Playwright compte plus de 70,000 étoiles GitHub, un outil de génération de code mature qui enregistre les sessions en scripts, et un écosystème de traçage et d'enregistrement vidéo de premier ordre. C'est le substrat que Stagehand enveloppait à l'origine et que la plupart des équipes utilisent encore pour les 80% prévisibles de leurs étapes d'automatisation. Le modèle de production pratique qui a émergé est Playwright pour la navigation déterministe et les flux de connexion, et Stagehand pour les étapes dynamiques d'extraction et d'action au milieu.

Browser-Use est l'alternative orientée Python avec une philosophie différente. Là où Stagehand est hybride (vous décidez quelles étapes sont pilotées par l'IA), Browser-Use exécute une boucle d'agent autonome complète où le LLM reçoit l'état de la page, décide de la marche à suivre, et itère jusqu'à ce que l'objectif soit atteint. Il prend en charge les modèles Ollama locaux, ce qui signifie un coût d'inférence nul pour les équipes prêtes à utiliser leur propre matériel. Browser-Use a franchi le cap des 80,000 étoiles GitHub début 2026, fortement stimulé par les développeurs Python qui trouvent son API plus simple et plus accessible. Le compromis est la prévisibilité : Browser-Use raisonne à nouveau de zéro à chaque exécution, de sorte que le même objectif peut produire des chemins d'exécution différents selon les jours. Le modèle de mise en cache et les primitives explicites de Stagehand le rendent plus reproductible en production, où vous devez auditer ce que le script a fait et pourquoi. Pour les tâches web exploratoires et ouvertes où la séquence d'étapes n'est pas fixe, Browser-Use est souvent le meilleur choix. Pour les pipelines de production où vous exécutez le même flux de travail 500 fois par jour et avez besoin d'une exécution fiable et débogable, Stagehand l'emporte.

Une troisième catégorie digne d'intérêt est AgentQL, qui adopte une approche par langage de requête plutôt qu'une approche par appel de méthode. AgentQL utilise une syntaxe inspirée de GraphQL pour décrire les éléments de la page de manière déclarative, tandis que Stagehand utilise un code impératif avec des arguments en langage naturel. Les deux reposent sur une infrastructure de navigateur similaire, mais le modèle mental diffère considérablement. Les équipes ayant de solides modèles TypeScript ont tendance à préférer Stagehand ; les équipes qui souhaitent exprimer des schémas de données sous forme de requêtes ont tendance à préférer AgentQL. L'API act/extract/observe de Stagehand est plus simple à appréhender lors du débogage.

À quoi ressemble la réalité du flux de travail des agents

La plupart des configurations Stagehand en production suivent un modèle prévisible. Les étapes déterministes et bien comprises (s'authentifier, naviguer vers la page cible, définir des filtres) utilisent des appels Playwright ou Stagehand classiques avec des sélecteurs explicites. Les étapes où la structure de la page varie (tableaux chargés dynamiquement, composants shadow-DOM, données authentifiées derrière des flux à plusieurs étapes) font appel aux primitives d'IA de Stagehand. Cette approche hybride permet de maintenir les coûts LLM gérables : à $0.002-$0.02 par appel act/extract, un flux de travail avec cinq étapes d'IA coûte moins de $0.10 par exécution, ce qui est viable. Faire passer chaque étape par l'IA est le moment où les équipes rencontrent des problèmes de rentabilité à grande échelle.

Le débogage est différent du débogage de Playwright pur. Lorsqu'un appel act() échoue ou interprète mal une instruction ambiguë, l'erreur apparaît comme une exception d'exécution avec l'action interprétée par le modèle consignée, mais lire les traces de décision de l'IA est une compétence différente de la lecture d'une inadéquation de sélecteur. L'API Stagehand (publiée en juin 2026) a déplacé une partie de ce travail de traduction vers une infrastructure gérée avec des journaux d'action lisibles par l'homme et une observabilité au niveau des tokens par étape, ce qui répond directement à la plainte de la "boîte noire" du premier fil de discussion sur HN.

"Je ne pense pas pouvoir plaider de manière plausible pour l'utilisation de LLM à l'exécution dans notre suite de tests au travail. La bonne approche serait d'utiliser l'IA pour aider à écrire le code de test Playwright, et non pour remplacer la partie déterministe." - mpalmer, Hacker News, 9 janvier 2025

Ce scepticisme issu du fil de lancement sur HN s'est avéré en partie fondé et en partie erroné. Pour les suites de tests CI/CD où le déterminisme est non négociable, l'approche LLM à l'exécution de Stagehand reste difficile à vendre. Pour les pipelines d'automatisation de production où le coût de maintenance est le véritable ennemi, le compromis s'est avéré rentable pour une part importante des équipes. La distinction architecturale importante est que Stagehand est avant tout un outil d'automatisation de navigateur qui se trouve bien fonctionner dans des contextes de test, et non un framework de test auquel on a ajouté des fonctionnalités d'IA.

La véritable complexité opérationnelle survient lorsque vous avez besoin de capacités d'infrastructure de navigateur que Stagehand ne fournit pas nativement. La détection de bots, la résolution de CAPTCHA, les proxys résidentiels, l'enregistrement de session, l'exécution multi-régions et le traitement des données conforme à la loi HIPAA nécessitent soit le runtime géré payant de Browserbase, soit une plomberie personnalisée substantielle. Les équipes qui créent une automatisation interne simple peuvent exécuter Stagehand sur une instance Chromium locale et ne payer que leurs coûts d'API LLM. Les équipes qui créent des agents web de niveau production ont généralement besoin des deux.

À qui s'adresse Stagehand

Les développeurs TypeScript qui créent des agents de navigation pour l'automatisation de la production constituent le public principal. Les ingénieurs QA qui souhaitent écrire des tests en langage naturel lisible par l'homme, sans s'engager dans la maintenance des sélecteurs Playwright, représentent un public secondaire solide. Les équipes qui possèdent déjà des bases de code Playwright et qui souhaitent enrichir des étapes spécifiques avec un raisonnement par IA (plutôt que de remplacer l'ensemble de la pile) constituent un troisième segment où Stagehand s'intègre proprement.

Stagehand s'intègre également naturellement dans les frameworks d'agents d'IA. Ses primitives act/extract/observe correspondent bien aux appels d'outils dans les architectures de style OpenAI Agents SDK, où un agent de planification décide des actions web à entreprendre et Stagehand les exécute. Les équipes qui créent des pipelines de données incluant des données web aux côtés de sources structurées combinent souvent Stagehand pour l'extraction avec des outils comme Firecrawl (pour une extraction propre de documents) ou Apify (pour une infrastructure de scraping évolutive). Stagehand gère les scénarios authentifiés, riches en JavaScript et de remplissage de formulaires que les robots d'exploration statiques ne peuvent pas atteindre.

L'étape de la série B (juin 2025) et les plus de 500,000 téléchargements hebdomadaires sur NPM confirment que Stagehand est passé d'une expérience open-source prometteuse à un framework bénéficiant d'une véritable adoption en production et soutenu par une équipe financée. L'architecture CDP de la v3 supprime la dépendance à un composant amont spécifique (Playwright), ce qui réduit le risque que des modifications internes de Playwright ne cassent le comportement de Stagehand.

Ce que Stagehand n'est pas

Stagehand n'est pas un remplaçant de Playwright pour l'automatisation à haut volume et sensible aux coûts. À 10,000 extractions par jour, les frais de LLM s'élèvent à $50-200/jour avec des modèles de niveau intermédiaire, même avec la mise en cache. Pour ce volume avec des structures de page stables et bien comprises, maintenir les sélecteurs Playwright est moins cher. Le seuil de rentabilité où les économies de maintenance de Stagehand l'emportent sur ses coûts LLM dépend fortement de la fréquence à laquelle les sites cibles modifient leur DOM et du coût du temps de vos ingénieurs.

Stagehand n'est pas un outil axé sur le local ou la confidentialité. Il nécessite des identifiants d'API LLM cloud pour chaque étape pilotée par l'IA. La prise en charge d'Ollama par Browser-Use en fait le meilleur choix pour les équipes qui ne peuvent pas envoyer le contenu des pages à des API externes en raison d'exigences de résidence des données ou de politiques de sécurité.

Ce n'est pas un outil no-code de type pointer-cliquer. Stagehand est un SDK pour développeurs. Vous écrivez du code TypeScript (ou Python). Le langage naturel se trouve à l'intérieur des appels de méthode, et non dans un constructeur de flux de travail visuel. Les équipes sans capacité d'ingénierie devraient se tourner vers le produit Director.ai de Browserbase (sorti en juin 2025) pour une interface d'agent de navigation no-code.

Ce n'est pas un remplacement complet de la navigation supervisée par l'homme dans des contextes sensibles. Les transactions financières, la saisie de données de santé et les flux de travail de documents juridiques nécessitent des étapes d'approbation, des journaux d'audit et des outils de conformité que Stagehand ne fournit pas par défaut. Le framework est une infrastructure, pas un produit de conformité.

Enfin, Stagehand n'est pas bien adapté aux tâches de recherche exploratoires et ouvertes où la séquence exacte des actions du navigateur n'est pas connue à l'avance. Si votre objectif est de "trouver le meilleur prix pour X sur ces 12 sites" sans flux de travail fixe, la boucle de raisonnement autonome de Browser-Use gère l'exploration web orientée vers un but plus naturellement que le modèle de primitives composables de Stagehand. Pour les flux de travail de production reproductibles avec des étapes définies et des résultats mesurables, l'approche hybride de Stagehand s'avère payante. Pour les tâches de recherche floues à plusieurs tours, un framework plus orienté agent pourrait mieux vous servir.