Automatiser le navigateur avec Stagehand

L'automatisation du navigateur avec Stagehand comporte deux couches : Stagehand fournit des primitives au niveau de la page, tandis qu'un lanceur choisit l'exécutable Chromium et ses arguments de démarrage. Stagehand v4 documente act, extract et observe, puis se connecte via Chrome DevTools Protocol (CDP) à un Chromium déjà démarré. BotBrowser permet de démarrer Chromium avec un exécutable choisi par l'opérateur et le flag --bot-profile; Stagehand v4 peut s'y connecter par CDP. BotBrowser ne fournit pas d'adaptateur Stagehand, ne définit pas la politique d'agent et ne garantit pas la classification d'un site tiers. Le guide browser-use couvre un autre framework, et le guide Playwright direct décrit une autre API de contrôle.

Une connexion réussie ne prouve pas que le processus attendu a été démarré. Une URL CDP désigne un endpoint, pas le chemin du binaire, l'argument de profil, le routage réseau ou l'état de la page. Conservez ces observations séparément et consultez la référence des options de ligne de commande BotBrowser pour le flag de profil pris en charge; un appel Stagehand ne configure pas le démarrage du navigateur.

TL;DR

• observe() découvre des actions candidates, act() exécute une action et extract() renvoie des données conformes à un schéma.
• Stagehand v4 se connecte à Chromium via CDP; sa documentation actuelle indique qu'il ne dépend ni de Playwright ni de Puppeteer.
• Le lanceur, et non les primitives de page Stagehand, choisit l'exécutable et transmet --bot-profile avant le démarrage.
• Une réponse CDP prouve qu'un endpoint a répondu. Elle ne prouve pas quel exécutable ou profil a été utilisé.
• Gardez l'endpoint sur loopback, vérifiez séparément le processus et arrêtez-vous en cas de désaccord.

Sommaire

• Responsabilité de chaque primitive
• Lancement et connexion sont deux opérations distinctes
• Démarrer le navigateur contrôlé avant Stagehand
• Exécuter les trois primitives sur un jeu de test
• Vérifier le processus et la cible CDP
• Tableau des pannes et reprise
• Ce qui reste hors de Stagehand
• Conclusion pratique

Responsabilité de chaque primitive

Les trois primitives nommées de Stagehand répondent à des besoins différents. observe() découvre les éléments interactifs et renvoie des actions structurées; act() exécute une instruction ou une action produite par observe(); extract() lit le contenu de la page selon la forme demandée. Les références officielles de observe, act et extract décrivent leurs entrées et résultats. Ce sont des opérations Stagehand, pas des options de sélection du binaire.

Cette distinction limite ce qu'une trace peut affirmer. Un résultat observe() signifie que Stagehand a trouvé des actions candidates selon la page et l'instruction présentes; il ne vaut pas consentement de l'utilisateur. Un résultat act() enregistre une tentative d'interaction; l'application distante peut encore la refuser ou appliquer un autre changement. Un résultat extract() contient les données qui correspondent au schéma demandé; il ne s'agit ni d'une copie de la base serveur ni d'une vérification indépendante de la page.

Primitive	Travail sur la page	Éléments utiles à conserver
observe()	Découvrir des éléments candidats pour une instruction délimitée	Origine, identifiant d'instruction, nombre de candidats et action choisie
act()	Exécuter une instruction ou une action sélectionnée	Identifiant de l'action et résultat renvoyé, sans parler d'acceptation distante
extract()	Lire le contenu selon un schéma demandé	Version du schéma et champs minimaux utiles au traitement

Les trois opérations peuvent s'enchaîner, mais leurs résultats ne devraient pas devenir un unique indicateur success. La connexion au navigateur peut réussir alors que l'extraction échoue; une extraction peut réussir alors qu'un envoi ultérieur reste en attente. Enregistrez les états séparément pour localiser la couche à examiner. Un élément trouvé plus tôt peut être périmé après une navigation, une boîte de dialogue ou un changement d'origine.

Stagehand fournit aussi des méthodes de page familières, comme la navigation et les locators. Cela ne fait pas de Stagehand v4 un wrapper Playwright : son introduction actuelle décrit un contrôle par CDP sans dépendance à Playwright ni à Puppeteer. Un projet qui a besoin du cycle BrowserType.launch() de Playwright doit suivre le guide de configuration Playwright et utiliser son propre lancement. Un projet qui a besoin des primitives Stagehand suit plutôt son contrat de connexion au navigateur.

Lancement et connexion sont deux opérations distinctes

Le lancement crée le processus du système. Le lanceur transmet le chemin du binaire, l'argument de profil, le répertoire de données utilisateur, l'endpoint de débogage et les paramètres réseau reçus par ce processus. Une connexion CDP ultérieure rejoint un navigateur déjà en cours d'exécution. La référence de configuration navigateur de Stagehand documente localBrowser.launch() pour un processus local et localBrowser.connect() pour un Chromium existant. L'exemple de connexion utilise une URL CDP et transmet le navigateur obtenu à Stagehand.create().

Pour BotBrowser, le profil est choisi au démarrage avec --bot-profile. Ce n'est ni une instruction Stagehand, ni une valeur de page.evaluate(), ni un réglage qu'observe() peut appliquer après le démarrage. La documentation Playwright de BotBrowser montre où l'exécutable et l'argument de profil entrent dans un lancement Playwright; le principe est identique avec tout lanceur : le processus reçoit ses options avant que Stagehand se connecte. Le guide de gestion des profils explique leur sélection et le traitement des fichiers.

Décision	Démarrage	Connexion
Qui démarre Chromium ?	La fabrique locale de Stagehand ou un lanceur externe	Un lanceur géré par l'opérateur le démarre d'abord
Où choisir le binaire ?	Dans la configuration de lancement prise en charge par la version fixée	Dans les arguments du processus avant la connexion Stagehand
Où passer --bot-profile ?	Seulement si l'API de lancement prise en charge transmet les arguments navigateur	Dans les arguments du processus avant l'ouverture de l'endpoint CDP
Que reçoit Stagehand ?	Un navigateur renvoyé par son appel de lancement local	Un navigateur connecté à l'URL CDP déclarée
Quoi vérifier séparément ?	Le processus réel et ses arguments	L'identité du processus, l'endpoint et l'argument de profil

La connexion convient si l'environnement possède déjà un processus Chromium contrôlé ou si un superviseur distinct gère sa création. Elle ajoute une dépendance stricte : Stagehand ne se connecte qu'une fois l'endpoint disponible. Le lancement local peut être plus simple quand les options de la version fixée couvrent tous les besoins. Ne supposez pas qu'un helper local accepte n'importe quel exécutable ou argument de profil parce qu'il sait démarrer Chrome; vérifiez les types de cette version.

Démarrer le navigateur contrôlé avant Stagehand

Un lancement géré par l'opérateur rend la configuration visible. La forme shell suivante utilise des variables de remplacement; elle ne constitue pas un compte rendu d'exécution et ne prouve pas qu'un binaire BotBrowser donné a accepté ces valeurs. Définissez les variables dans la configuration de déploiement, attribuez un port loopback libre à chaque exécution et transmettez le même STAGEHAND_CDP_PORT au lanceur et au client :

"$BOTBROWSER_EXEC_PATH" \
  --user-data-dir="$STAGEHAND_USER_DATA_DIR" \
  --remote-debugging-port="$STAGEHAND_CDP_PORT" \
  --bot-profile="$BOT_PROFILE_PATH"

--bot-profile sélectionne le fichier de profil BotBrowser. --user-data-dir est un répertoire Chromium distinct; il ne remplace pas le profil chiffré BotBrowser. Utilisez un nouveau répertoire dédié lorsque la version du navigateur l'exige pour le débogage distant, et ne réutilisez pas des données client pour un essai. L'endpoint CDP donne un contrôle privilégié du navigateur : limitez-le à loopback, ne l'exposez pas aux réseaux partagés et fermez le processus à la fin. La documentation Chrome sur le débogage distant décrit cette interface et sa limite de sécurité.

Une fois le processus disponible, la forme de connexion documentée par Stagehand reste courte :

import { localBrowser, Stagehand } from '@browserbasehq/stagehand';
import { z } from 'zod';

const cdpPort = process.env.STAGEHAND_CDP_PORT;
if (!cdpPort || !/^\d+$/.test(cdpPort)) {
  throw new Error('The launcher must assign a numeric CDP port');
}

const browser = await localBrowser.connect({
  cdpUrl: `http://127.0.0.1:${cdpPort}`,
});
const stagehand = await Stagehand.create({ browser });

const { data: actions } = await stagehand.observe('Find the read-only build marker');
if (actions.length !== 1) {
  throw new Error(`Expected one build-marker action; found ${actions.length}`);
}

await stagehand.act(actions[0]);
const { data } = await stagehand.extract({
  instruction: 'Read the build marker from the current page',
  schema: z.object({ build: z.string() }),
});
console.log(data.build);

La connexion et les appels aux primitives suivent la documentation Stagehand v4 actuelle; l'endpoint, le jeu de test et l'installation des paquets dépendent de l'environnement. Fixez la version Stagehand et comparez les imports et champs de résultat à la référence correspondante. L'exemple lit un jeu de test détenu par l'équipe; il n'envoie pas de formulaire, ne se connecte pas à un compte et ne modifie aucun enregistrement distant. C'est une forme d'intégration locale, pas la preuve que le code a été exécuté ici.

Attribuez un endpoint à une exécution, au lieu d'utiliser un port constant qui pourrait appartenir au navigateur d'un autre utilisateur. Si le port est déjà occupé, ne vous y connectez pas silencieusement : l'adresse peut viser un autre Chromium. Faites attribuer et enregistrer l'endpoint par le lanceur et liez-le à localhost. N'exposez pas CDP sur une interface publique; toute personne qui peut y accéder peut contrôler le navigateur.

Exécuter les trois primitives sur un jeu de test

Un jeu de test détenu par l'équipe rend les couches observables sans dépendre d'un site public. Il peut exposer un identifiant de compilation fixe et un contrôle inoffensif. La première instruction observe() doit désigner ce contrôle; l'action choisie révèle seulement l'identifiant, puis extract() renvoie cette valeur selon un petit schéma. Évitez un jeu de test avec des identifiants, achats, changements de compte ou suppressions : cela transformerait une vérification d'intégration navigateur en flux d'autorisation.

Ne conservez que quelques valeurs attendues et observées. Le jeu de test peut renvoyer build: "stagehand-fixture-7"; le reçu peut garder cette chaîne, la version du jeu, l'origine et le nom du schéma. Il n'est pas nécessaire d'enregistrer tout le DOM, une capture contenant du contenu sans rapport, les cookies, le stockage local ou la trace complète du modèle. Un reçu réduit limite l'exposition accidentelle et facilite la classification de l'échec.

Le jeu de test doit être assez stable pour séparer un problème de connexion d'un problème de page. Un marqueur connu vérifie que la navigation a atteint l'origine locale attendue. Un bouton en lecture seule teste observe() et act() sans changer l'état serveur. Un petit objet JSON teste extract() et son schéma. Versionnez ces éléments ensemble : si l'attribut du marqueur change tandis que Chromium reste identique, le contrat du jeu de test a changé, pas le lanceur.

N'utilisez pas le user-agent visible par la page comme preuve du processus ou du profil sélectionné. Une valeur visible sert à son propre contrôle, mais n'identifie pas le binaire qui a ouvert l'onglet. À l'inverse, un chemin de processus ne prouve pas que le jeu de test attendu a été rendu. Le processus du lanceur, l'endpoint CDP et la réponse du jeu de test répondent à des questions différentes et restent des champs séparés.

Le jeu de test peut également séparer l'état de page de la disponibilité d'une action. Si le marqueur n'apparaît qu'après un choix de consentement, l'instruction observe() ne doit pas transformer cette décision en clic de préparation banal. Indiquez que l'action exige une approbation ou créez un parcours distinct en lecture seule. Un contrat de test stable ne justifie pas l'automatisation d'un changement de permission ou de données.

Vérifier le processus et la cible CDP

Trois contrôles établissent des faits distincts. Premièrement, inspectez le processus du lanceur et comparez son exécutable et ses arguments expurgés aux valeurs déclarées. Deuxièmement, interrogez l'endpoint CDP de loopback pour confirmer que le service de débogage attendu répond. Troisièmement, naviguez vers le jeu de test détenu par l'équipe et lisez son marqueur. Une ligne réussie ne remplace pas les autres.

Contrôle	Observation attendue	Ce que cela n'établit pas
Processus du lanceur	L'exécutable correspond au chemin BotBrowser déclaré et le flag de profil requis est présent	Que le profil chiffré a été accepté ou produit une valeur de page attendue
Endpoint CDP	L'URL locale déclarée renvoie des métadonnées navigateur	Que l'endpoint appartient au processus contrôlé dans la première ligne
Page de test	Stagehand voit l'origine attendue et le marqueur de compilation	Qu'un service tiers affichera la même page ou prendra la même décision

Un écart arrête le flux. Si le chemin du processus diffère, ne continuez pas uniquement parce que l'endpoint est sain. Si le chemin correspond mais que l'endpoint identifie un autre navigateur, examinez l'attribution du port et le propriétaire du processus. Si les deux correspondent mais que le marqueur manque, inspectez la route du jeu de test et le cycle de vie de la page au lieu de changer les valeurs du profil. Cet ordre évite qu'une nouvelle tentative de page masque une erreur de lancement.

Un reçu compact peut contenir runId, la version fixée de Stagehand, le nom expurgé de l'exécutable, l'identifiant non sensible du profil, l'endpoint local, la compilation du jeu de test, la primitive utilisée et le premier échec. N'enregistrez pas le contenu du profil chiffré, les jetons, les identifiants de proxy ou un chemin absolu contenant un identifiant client. Le reçu n'est utile que s'il distingue une valeur configurée d'une valeur observée.

Les métadonnées CDP ne sont pas un certificat d'identité du navigateur. Si plusieurs processus peuvent écouter ou transférer l'endpoint, associez l'URL à l'identifiant du processus et inspectez ses arguments locaux. Un tunnel, un mappage de port conteneur, un proxy de développement ou un ancien navigateur peut diriger le client vers un processus différent. Utilisez un endpoint par exécution et terminez les processus obsolètes avant de réutiliser un port.

Le cycle de vie du navigateur compte aussi. Fermez la connexion Stagehand après le contrôle en lecture seule, puis ne fermez le processus que si cette exécution le possède. La documentation navigateur de Stagehand distingue les navigateurs démarrés par Stagehand de ceux auxquels l'appelant s'est connecté. Un client attaché ne doit pas supposer qu'il peut terminer le processus; un superviseur peut encore l'utiliser pour une autre tâche contrôlée.

Tableau des pannes et reprise

Observation	Couche probable	Contrôle suivant	Condition d'arrêt
La connexion CDP est refusée	Démarrage navigateur ou attribution du port	Confirmez l'état du lanceur et le port attribué	Ne démarrez pas implicitement un autre navigateur
CDP se connecte, mais le chemin du processus est inattendu	Mauvais endpoint ou processus obsolète	Reliez l'endpoint à l'identifiant de processus enregistré	Fermez l'exécution avant toute action de page
Le processus est correct, mais l'argument de profil manque	Configuration du lanceur	Examinez le constructeur d'arguments avant le démarrage	N'affirmez pas que le profil a été sélectionné
Le flag existe, mais le jeu de test diffère	Profil, jeu de test ou application	Comparez séparément la compatibilité du profil et la version du jeu	Ne modifiez pas la page pour forcer une correspondance
observe() ne renvoie aucune action	État de page ou instruction	Inspectez le jeu de test et le contrôle visible	N'élargissez pas l'instruction à une autre action
act() renvoie un résultat, mais le jeu reste inchangé	Résultat de l'action ou état applicatif	Relisez le marqueur et inspectez le résultat	Ne déclarez aucun changement distant sans preuve
extract() échoue à valider le schéma	Sortie de page ou contrat de schéma	Comparez les données visibles du jeu au schéma demandé	Gardez peu de données et ne relâchez pas le schéma en silence
Le navigateur se déconnecte pendant une action	Cycle de vie ou résultat distant	Vérifiez le jeu ou un état idempotent avant une reprise	Ne répétez jamais à l'aveugle une action à effet

La reprise suit la première couche en échec. Une connexion refusée ne se corrige pas en modifiant le schéma d'extraction. Un endpoint valide connecté au mauvais processus ne se corrige pas en élargissant l'instruction. Un argument de profil absent se corrige dans le lanceur, puis exige un nouveau processus et un nouvel identifiant d'exécution. Si une mutation distante a pu être envoyée avant une déconnexion, vérifiez son état avec une requête idempotente ou confiez le cas à l'opérateur responsable; ne la rejouez pas automatiquement.

Le guide browser-use décrit les approbations pour une autre boucle d'agent. L'aperçu de détection de l'automatisation traite des signaux généraux. Aucun ne remplace la distinction propre à Stagehand entre résultat de primitive, connexion CDP et exécutables/profil choisis avant l'attachement.

Ce qui reste hors de Stagehand

Stagehand fournit des API d'automatisation navigateur; l'application reste responsable de l'autorisation des tâches, du choix des comptes, du routage réseau, des secrets, de la conservation des données et de l'approbation des actions sensibles. Un navigateur connecté peut être techniquement prêt alors que la tâche est inappropriée ou que sa destination a changé. La politique doit se trouver dans l'application appelant Stagehand, pas dans une instruction que l'agent peut réécrire.

Gardez la sélection de profil dans la configuration de lancement examinée. L'agent ne doit pas parcourir des fichiers arbitraires, afficher leur contenu ni choisir un compte d'après le texte d'une page. Le lanceur peut résoudre un identifiant approuvé et transmettre son chemin au navigateur. Le reçu peut conserver une étiquette non sensible et une version de configuration sans copier le fichier chiffré ni son contenu.

Le routage réseau est un autre paramètre indépendant. Un argument de profil ne prouve pas le chemin de sortie d'une requête, et un endpoint CDP ne rapporte pas une décision de permission applicative. Si le flux exige une route donnée, configurez-la dans la couche externe et validez-la avec les diagnostics autorisés. N'attribuez pas à Stagehand une route, une langue ou un état de compte sauf si le système environnant fournit cette valeur et en identifie la source.

La même séparation s'applique à une classification tierce. Un act() réussi indique qu'une interaction navigateur a renvoyé un résultat; un extract() réussi indique que la forme demandée a été renvoyée. Ni l'un ni l'autre ne garantit l'acceptation d'une session, une catégorie de détecteur ou un résultat commercial. BotBrowser offre une option de navigateur contrôlé, pas un résultat garanti par un tiers.

Lorsque le flux atteint des identifiants, un consentement, un paiement, une suppression, une modification de permission, une publication ou un envoi irréversible, faites une pause dans la couche applicative pour obtenir une décision opérateur. La demande doit montrer l'origine cible, l'action et les paramètres visibles nécessaires, sans transmettre de secret à la trace du modèle. Cette limite relève de la politique de l'application, pas de observe(), act() ou extract().

Questions fréquentes

Stagehand v4 utilise-t-il Playwright en interne ?

L'introduction actuelle de Stagehand v4 décrit un contrôle du navigateur par CDP et indique une absence de dépendance à Playwright ou Puppeteer. Ses API de page peuvent être familières aux utilisateurs de Playwright, mais cela n'équivaut pas au cycle de lancement BrowserType.

Stagehand peut-il choisir un profil BotBrowser après la connexion ?

Non. Le profil est transmis au processus lors du démarrage. Les primitives de page opèrent après la connexion et ne modifient pas rétroactivement les arguments. Placez --bot-profile approuvé dans la configuration du lanceur avant d'ouvrir l'endpoint CDP.

Une connexion CDP réussie prouve-t-elle que le bon navigateur a démarré ?

Non. Elle prouve qu'un service a répondu sur l'endpoint. Associez cet endpoint à l'identifiant du processus et au chemin de l'exécutable, examinez les arguments expurgés et lisez séparément le jeu de test.

Cette intégration garantit-elle le résultat d'un détecteur ou d'un site ?

Non. Les actions Stagehand et une configuration navigateur contrôlée ne garantissent ni classification, ni acceptation, ni résultat commercial tiers. Ces résultats ne font pas partie du contrôle de lancement.

Sources

• Introduction Stagehand v4
• Stagehand act()
• Stagehand extract()
• Stagehand observe()
• Configuration navigateur Stagehand
• Débogage distant de Chrome
• Chrome DevTools Protocol
• Configuration Playwright de BotBrowser
• Options CLI BotBrowser

Conclusion pratique

Gardez les primitives Stagehand séparées de la création du processus. La même vérification vaut quand un serveur MCP possède le lancement au lieu d’un script, et les clés qui y portent l’exécutable sont traitées dans configuration Playwright MCP pour un build Chromium personnalisé. Sélectionnez l'exécutable BotBrowser et le profil dans le lanceur, n'exposez qu'un endpoint CDP de loopback, puis connectez Stagehand à ce navigateur déjà démarré. Vérifiez séparément le processus, l'endpoint et le jeu de test; arrêtez-vous au moindre désaccord. Cela établit un contrôle d'intégration délimité, pas une affirmation sur la validité du profil, l'autorisation d'une tâche ou la décision d'un tiers.