browser-use → Stagehand sur Browserbase (/browser-use-to-stagehand)

Convertir un script « browser-use » (Python) en un script Stagehand v3 (TypeScript) idiomatique sur Browserbase, en choisissant le bon niveau de déterminisme à chaque étape plutôt que de produire une copie agentique à l'identique.

Principe fondamental : browser-use est « agentique » par défaut (le LLM décide de chaque action). Stagehand vous permet de choisir le degré d’intervention de l’IA. Une bonne migration remplace les boucles d’agent opaques par un pipeline inspectable et majoritairement déterministe — en n’utilisant l’IA que lorsque la page est véritablement imprévisible. Il s’agit d’une refactorisation faisant appel au jugement, et non d’une simple transcompilation.

Source de vérité et versions. La valeur durable de cette compétence réside dans le jugement — le spectre du déterminisme et la décision entre décomposition et agent — et non dans les spécificités de l’API, qui évoluent à chaque nouvelle version. Les mappages de code présentés ici constituent un instantané validé par rapport à @browserbasehq/stagehand 3.6.x et browser-use 0.13.x (juin 2026). En cas de conflit, la documentation en ligne prévaut — vérifiez toujours par rapport au paquet installé et à ces sources avant de générer du code :

• Stagehand v3 : https://docs.stagehand.dev/v3 · types installés : node_modules/@browserbasehq/stagehand
• Browserbase : https://docs.browserbase.com
• browser-use : https://docs.browser-use.com

Si la version majeure de Stagehand installée n’est pas la 3, considérez cette compétence comme purement conceptuelle et suivez la documentation en ligne pour chaque signature.

Fichiers de référence (à consulter si nécessaire)

• references/api-mapping.md — le mappage technique browser-use → Stagehand : détection des variantes, tableau complet des fonctionnalités, code avant/après, options de la plateforme Browserbase et pièges de la version v3. À lire pour toute construction non triviale.
• references/determinism.md — comment choisir agent() vs act/extract/observe vs mis en cache observe→act. L’arbre de décision. À lire lorsque vous devez décider comment traduire une Agent(task=…).
• references/trace-assisted.md — le workflow optionnel « exécutez-le sur Browserbase, lisez les journaux, puis réécrivez » pour les scripts opaques ou instables.
• references/guide.md — le guide de migration pour les humains : changement de philosophie, mise en correspondance des fonctionnalités, spectre du déterminisme et parcours de migration recommandé.
• references/prompt.md — une version autonome et indépendante de tout outil de cette compétence ; collez-la dans n’importe quel assistant IA avec un script d’utilisation du navigateur.
• EXAMPLES.md — des paires de scripts « avant/après ».

Workflow

1. Obtenir la source

Récupérez le ou les scripts d’utilisation du navigateur. Si l’utilisateur n’a décrit qu’un script, demandez-lui le ou les fichiers. Notez la cible : TypeScript Stagehand sur Browserbase, sauf indication contraire.

Commencez par vérifier la portée : la migration est-elle même possible ? Tous les fichiers « browser-use » ne sont pas des Agent(task=…) script. Si la source est un script « browser-use » s’exécutant en tant que serveur MCP (uvx browser-use --mcp, une mcpServers configuration), il n’existe pas d’équivalent Stagehand — signalez-le comme hors du champ d’application, n’en inventez pas (voir mappage des API §3.7b). Si l’appel « browser-use » est intégré dans une application plus vaste (un wrapper de classe/outil, une route web, une tâche de file d’attente), ne convertissez que l’interface « browser-use » et conservez le code de liaison de l’application environnante — voir api-mapping §3.8.

2. Détecter la variante « browser-use »

Identifiez les versions héritées (antérieures à la version 0.12), stables et bêta de Rust (uniquement lorsque les importations proviennent de browser_use.beta) — voir api-mapping §1. Remarque : l’interface de niveau supérieur classique from browser_use import Agent, ChatBrowserUse est toujours bien présente dans la version 0.13.x — ChatBrowserUse n’est pas en soi un indicateur de version bêta ; seule une browser_use.beta import l’est. Toutes les variantes se traduisent de manière identique ; en cas de doute, utilisez donc le mappage de la version stable. Normalisez les noms hérités avant la traduction. Précisez quelle variante vous avez identifiée.

3. Dresser l’inventaire du script

Extrayez un inventaire structuré avant d’écrire le moindre code TypeScript :

• Tâche(s) — la task= chaîne(s) ; décomposez chacune d’elles en ses étapes ordonnées implicites.
• Modèle — l’ Chat* fournisseur + l’identifiant du modèle.
• Configuration du navigateur — local ou cdp_url/Browserbase ; mode sans interface graphique ; proxys ; user_data_dir/storage_state.
• Sortie structurée — tout output_model_schema modèles Pydantic.
• Secrets — sensitive_data, utilisation des variables d’environnement, flux de connexion.
• Mesures de sécurité — allowed_domains, max_steps.
• Actions personnalisées — @tools.action / Controller fonctions, et si chacune d’entre elles est un effet secondaire déterministe ou une capacité de l’agent.
• Configuration — initial_actions, modèles secondaires (page_extraction_llm, planner_llm).

4. Déterminer le niveau de déterminisme à chaque étape

Pour chaque étape de l’inventaire, appliquez l’arbre de décision figurant dans determinism.md :

• Accéder à une URL connue → page.goto(url) sur la page Stagehand (sans IA).
• Action sur la page → act("…"); si elle se répète, observe() une fois, puis rejouer act(action) (pas d’appel LLM).
• Lecture des données → extract("…", zodSchema).
• Véritablement ouvert → conserver stagehand.agent().execute(...) (affiné par maxSteps/systemPrompt).

Par défaut, décomposition lorsque le flux est connu ; conserver agent() uniquement lorsqu’il ne l’est pas. Pour un premier « lift-and-shift », une agent() est acceptable — le préciser et noter la voie d’optimisation.

5. Réaliser la réécriture Stagehand v3

Commencez par vérifier l’API. Avant d’écrire le code, vérifiez les signatures exactes que vous vous apprêtez à utiliser par rapport au paquet installé (node_modules/@browserbasehq/stagehand types) ou sur https://docs.stagehand.dev/v3. Les correspondances ci-dessous proviennent d’un instantané de la version 3.6.x ; en cas de divergence avec la version installée, c’est cette dernière qui prévalent. Générez ensuite du code TypeScript exécutable. Toujours :

• import { Stagehand } from "@browserbasehq/stagehand"; et import { z } from "zod"; lors de l’extraction.
• Récupérez la page via const page = stagehand.context.pages()[0];.
• Appelez les méthodes AI sur l’instance : stagehand.act(...), stagehand.extract(...), stagehand.observe(...) — jamais page.act(...).
• Définir le modèle en tant que "provider/model" chaîne de caractères.
• Par défaut, env: "BROWSERBASE"; afficher env: "LOCAL" comme option de développement.
• Transmettre les secrets via variables et process.env, jamais en code source.
• await stagehand.init() au début, await stagehand.close() dans un finally.

Incluez la configuration du projet pour qu’il s’exécute (voir les modèles ci-dessous).

6. Rédigez le résumé de la migration

En plus du code, rédigez un bref résumé :

• Variante détectée et choix de déterminisme effectués (quelles étapes sont devenues déterministes, lesquelles relèvent de l’IA et lesquelles relèvent de l’agent), avec le raisonnement correspondant.
• Nécessite une vérification humaine — tout ce qui n’a pas été mappé en 1:1 : perte de allowed_domains , logique d’action personnalisée, intention du modèle secondaire, chaînes de tâches ambiguës.
• Prochaine étape recommandée — Browserbase Context pour la réutilisation de l’authentification, la mise en cache pour la production, ou le chemin assisté par trace si le flux était opaque.

7. Proposer le chemin assisté par trace (uniquement si cela se justifie)

Si la source était un seul grand code opaque agent(task=…), instable, ou si votre réécriture ne peut pas être mappée avec certitude , proposez le workflow assisté par trace (trace-assisted.md) : exécutez l’original sur Browserbase, extrayez sessions.logs.list, puis réécrivez à partir du comportement observé. N’exécutez rien sans l’accord de l’utilisateur.

Modèles de sortie

package.json

{
  "name": "stagehand-migration",
  "type": "module",
  "scripts": { "start": "tsx index.ts" },
  "dependencies": {
    "@browserbasehq/stagehand": "^3.0.0",
    "dotenv": "^16.0.0",
    "zod": "^3.25.0"
  },
  "devDependencies": { "tsx": "^4.0.0", "typescript": "^5.0.0" }
}

Ajoutez "ai": "^5.0.0" (Vercel AI SDK) uniquement si une action personnalisée d’utilisation du navigateur correspond à un agent tool. Fixez la version v5, et non la v4 — Stagehand 3.6.x intègre ai la v5 et les types agent({ tools }) comme la v5 ToolSet, où le champ « schema » d’un outil est inputSchema. L’assistant v4 tool() émet parameters à la place et échouera à la vérification de type par rapport à la version v5 de Stagehand ToolSet. Si vous ne pouvez pas contrôler la version ai , ignorez la tool() helper et transmettez un objet simple { description, inputSchema: zodSchema, execute } : il est compatible avec la v5 ToolSet , quelle que soit la ai résolution principale.

.env

BROWSERBASE_API_KEY=...
BROWSERBASE_PROJECT_ID=...
ANTHROPIC_API_KEY=...   # or the provider matching your model string

index.ts Squelette (décomposé, la forme recommandée)

import "dotenv/config";
import { Stagehand } from "@browserbasehq/stagehand";
import { z } from "zod";

async function main() {
  const stagehand = new Stagehand({
    env: "BROWSERBASE",
    model: "anthropic/claude-sonnet-4-6",
  });
  await stagehand.init();
  try {
    const page = stagehand.context.pages()[0];

    await page.goto("https://example.com");          // deterministic skeleton
    await stagehand.act("…");                          // AI where the page varies
    const data = await stagehand.extract("…", z.object({ /* … */ }));  // structured reads

    console.log(data);
  } finally {
    await stagehand.close();
  }
}

main().catch((err) => { console.error(err); process.exit(1); });

Liste de contrôle de validation (avant de déclarer la tâche terminée)

• Les méthodes d’IA s’appliquent à l’instance (stagehand.act/extract/observe), et non sur la page.
• Page obtenue via stagehand.context.pages()[0].
• Modèle est une "provider/model" chaîne de caractères ; la clé du fournisseur correspondante se trouve dans .env.
• extract utilise un schéma Zod ; zod figure dans les dépendances.
• Les secrets utilisent variables + process.env; rien n’est codé en dur.
• init() / close() présents ; close() dans finally.
• Chaque étape d’utilisation du navigateur est prise en compte et placée délibérément sur le spectre du déterminisme.
• Le résumé de la migration répertorie les choix en matière de déterminisme et les éléments « nécessitant une vérification humaine ».

Erreurs courantes à éviter

• Copier la syntaxe de la v2 (page.act(), stagehand.page, modelName/modelClientOptions, enableCaching) provenant d’anciens articles de blog. Utilisez la v3 — voir les « Notes de version » de l’api-mapping.
• Traduire chaque étape en «act()» — naviguer avec page.goto et mettez en cache les étapes répétables via observe→act; ne gaspillez pas un appel LLM pour chaque action.
• Tout définir par défaut sur «agent() » — cela ne fait que reproduire le non-déterminisme de l’utilisation du navigateur dans un nouveau framework. Décomposez le flux lorsque celui-ci est connu.
• Supprimer discrètement l’allowed_domains — Stagehand ne dispose pas de pare-feu de domaine ; signalez-le pour révision.
• Inventer des options Browserbase/Stagehand — en cas de doute sur un champ, consultez https://docs.stagehand.dev/v3 / https://docs.browserbase.com plutôt que de deviner.