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 un-à-un.

Principe fondamental : browser-use est agentique par défaut (le LLM décide chaque action). Stagehand vous permet de choisir combien d'IA utiliser. Une bonne migration remplace les boucles d'agent opaques par un pipeline inspectable, largement déterministe — en utilisant l'IA uniquement où la page est véritablement imprévisible. C'est une refonte avec jugement, pas une transpilation.

Source de vérité et versions. La valeur durable de cette compétence est le jugement — le spectre du déterminisme et la décision décomposer-vs-agent — pas les spécificités API, qui changent à chaque version. Les mappages de code ici sont un instantané validé contre @browserbasehq/stagehand 3.6.x et browser-use 0.13.x (juin 2026). En cas de conflit, les docs en ligne gagnent — toujours vérifier contre le paquet installé et ces sources avant d'émettre 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 majeure Stagehand installée n'est pas 3, traitez cette compétence comme conceptuelle uniquement et suivez les docs en ligne pour chaque signature.

Fichiers de référence (à consulter au besoin)

references/api-mapping.md — le mapping mécanique browser-use → Stagehand : détection de variante, table de fonctionnalités complète, code avant/après, options de plateforme Browserbase, et pièges de version v3. À lire pour tout construit non trivial.
references/determinism.md — comment choisir entre agent() vs act/extract/observe vs observe→act en cache. L'arbre de décision. À lire au moment de décider comment traduire un Agent(task=…).
references/trace-assisted.md — le workflow optionnel "l'exécuter sur Browserbase, lire les logs, puis réécrire" pour les scripts opaques/flottants.
references/guide.md — le guide de migration humain : shift de philosophie, mappage de fonctionnalités, spectre du déterminisme, et chemin de migration recommandé.
references/prompt.md — une version autonome et agnostique d'outil de cette compétence ; à coller dans n'importe quel assistant IA accompagné d'un script browser-use.
EXAMPLES.md — paires de scripts avant/après.

Flux de travail

1. Obtenir la source

Obtenir le(s) script(s) browser-use. Si l'utilisateur n'a décrit qu'un script, demander le(s) fichier(s). Noter la cible : TypeScript Stagehand sur Browserbase sauf indication contraire.

D'abord, filtrer par portée — est-ce même migratable ? Tout fichier browser-use n'est pas un script Agent(task=…). Si la source est browser-use exécuté comme serveur MCP (uvx browser-use --mcp, une config mcpServers) il n'y a pas d'équivalent Stagehand — le signaler comme hors de portée, ne pas en inventer un (voir api-mapping §3.7b). Si l'appel browser-use est intégré dans une application plus grande (un wrapper de classe/outil, route web, tâche de queue), convertir uniquement la surface browser-use et préserver la colle d'app environnante — voir api-mapping §3.8.

2. Détecter la variante browser-use

Identifier la variante legacy (pré-0.12) vs stable vs Rust bêta (seulement quand les imports viennent de browser_use.beta) — voir api-mapping §1. Note : la surface top-level classique from browser_use import Agent, ChatBrowserUse est bien vivante en 0.13.x — ChatBrowserUse seul n'est pas un indicateur bêta ; seul un import browser_use.beta en est un. Toutes les variantes se traduisent identiquement, donc en cas de doute, procéder avec le mappage stable. Normaliser les noms legacy avant de traduire. Indiquer quelle variante vous avez trouvée.

3. Inventorier le script

Extraire un inventaire structuré avant d'écrire du TypeScript :

Tâche(s) — la/les chaîne(s) task= ; scinder chacune en ses étapes ordonnées implicites.
Modèle — le fournisseur Chat* + id du modèle.
Config du navigateur — local vs cdp_url/Browserbase ; headless ; proxies ; user_data_dir/storage_state.
Sortie structurée — tout modèle Pydantic output_model_schema.
Secrets — sensitive_data, utilisation de variables d'env, flux de connexion.
Garde-fous — allowed_domains, max_steps.
Actions personnalisées — fonctions @tools.action / Controller, et si chacune est un side-effect déterministe ou une capacité d'agent.
Configuration — initial_actions, modèles secondaires (page_extraction_llm, planner_llm).

4. Décider du niveau de déterminisme par étape

Pour chaque étape de l'inventaire, appliquer l'arbre de décision dans determinism.md :

Naviguer vers une URL connue → page.goto(url) sur la page Stagehand (pas d'IA).
Action sur page → act("…") ; si elle se répète, observe() une fois puis rejouer act(action) (pas d'appel LLM).
Lire des données → extract("…", zodSchema).
Véritablement open-ended → garder stagehand.agent().execute(...) (serré avec maxSteps/systemPrompt).

Préférer la décomposition quand le flux est connu ; garder agent() seulement où il ne l'est pas. Pour un lift-and-shift initial, une traduction fidèle agent() est acceptable — le dire et noter le chemin d'optimisation.

5. Produire la réécriture Stagehand v3

D'abord, vérifier l'API. Avant d'écrire, confirmer les signatures exactes que vous êtes sur le point d'utiliser contre le paquet installé (node_modules/@browserbasehq/stagehand types) ou https://docs.stagehand.dev/v3. Les mappages ci-dessous sont un instantané 3.6.x ; si quoi que ce soit diffère dans la version installée, la version installée gagne. Puis émettre du TypeScript exécutable. Toujours :

import { Stagehand } from "@browserbasehq/stagehand"; et import { z } from "zod"; quand on extrait.
Obtenir la page via const page = stagehand.context.pages()[0];.
Appeler les méthodes IA sur l'instance : stagehand.act(...), stagehand.extract(...), stagehand.observe(...) — jamais page.act(...).
Définir le modèle comme une chaîne "provider/model".
Par défaut env: "BROWSERBASE" ; montrer env: "LOCAL" comme option de dev.
Passer les secrets via variables et process.env, jamais en dur.
await stagehand.init() au démarrage, await stagehand.close() dans un finally.

Inclure la configuration du projet pour qu'il s'exécute (voir les templates ci-dessous).

6. Écrire le résumé de migration

Aux côtés du code, produire un court résumé :

Variante détectée et les choix de déterminisme effectués (quelles étapes sont devenues déterministes vs IA vs agent), avec le raisonnement.
Nécessite une revue humaine — tout ce qui ne s'est pas mappé 1:1 : garde-fous allowed_domains perdus, logique d'action personnalisée, intention de modèle secondaire, chaînes de tâche ambiguës.
Prochaine étape recommandée — Browserbase Context pour la réutilisation d'auth, caching pour la production, ou le chemin trace-assisted si le flux était opaque.

7. Proposer le chemin trace-assisted (seulement si justifié)

Si la source était un grand agent(task=…) opaque, était flottante, ou votre réécriture ne peut pas être mappée avec confiance, proposer le workflow trace-assisted (trace-assisted.md) : exécuter l'original sur Browserbase, extraire sessions.logs.list, et réécrire à partir du comportement observé. Ne rien exécuter sans l'accord de l'utilisateur.

Templates 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" }
}

Ajouter "ai": "^5.0.0" (Vercel AI SDK) seulement si une action browser-use personnalisée se mappe à un agent tool. Épingler v5, pas v4 — Stagehand 3.6.x agrège ai v5 et type agent({ tools }) comme le v5 ToolSet, où le champ schema d'un tool est inputSchema. Le helper v4 tool() émet parameters à la place et va échouer la vérification de type contre le v5 ToolSet de Stagehand. Si vous ne pouvez pas contrôler la version ai remontée, sauter le helper tool() et passer un objet brut { description, inputSchema: zodSchema, execute } — il satisfait le v5 ToolSet peu importe quelle majeure ai se résout.

.env

BROWSERBASE_API_KEY=...
BROWSERBASE_PROJECT_ID=...
ANTHROPIC_API_KEY=...   # ou le fournisseur correspondant à votre chaîne de modèle

index.ts squelette (décomposé, la forme préféré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");          // squelette déterministe
    await stagehand.act("…");                          // IA où la page varie
    const data = await stagehand.extract("…", z.object({ /* … */ }));  // lectures structurées

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

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

Checklist de validation (avant de déclarer terminé)

[ ] Les méthodes IA sont sur l'instance (stagehand.act/extract/observe), pas la page.
[ ] Page obtenue via stagehand.context.pages()[0].
[ ] Le modèle est une chaîne "provider/model" ; la clé de fournisseur correspondante est dans .env.
[ ] extract utilise un schéma zod ; zod est dans les dépendances.
[ ] Les secrets utilisent variables + process.env ; rien en dur.
[ ] init() / close() présents ; close() dans finally.
[ ] Chaque étape browser-use est comptabilisée, placée délibérément sur le spectre du déterminisme.
[ ] Le résumé de migration liste les choix de déterminisme et les items "nécessite revue humaine".

Erreurs courantes à éviter

Copier la syntaxe v2 (page.act(), stagehand.page, modelName/modelClientOptions, enableCaching) depuis d'anciens articles. Utiliser v3 — voir api-mapping "Notes de version".
Traduire chaque étape en act() — naviguer avec page.goto et cacher les étapes répétables via observe→act ; ne pas dépenser un appel LLM sur chaque action.
Tout défaillir par défaut à agent() — cela reproduit juste la non-déterminisme de browser-use dans un nouveau framework. Décomposer où le flux est connu.
Silencieusement supprimer allowed_domains — Stagehand n'a pas de firewall de domaine ; le signaler pour revue.
Inventer des options Browserbase/Stagehand — en cas de doute sur un champ, vérifier https://docs.stagehand.dev/v3 / https://docs.browserbase.com plutôt que de deviner.

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