browser-use-to-stagehand
Migrate browser-use (Python) browser-automation scripts to Stagehand v3 (TypeScript) on Browserbase. Use when the user wants to convert, port, rewrite, or migrate a browser-use Agent script to Stagehand, map browser-use features/APIs to Stagehand primitives (act/extract/observe/agent), or move agentic browser automation onto Browserbase with more determinism. Triggers on "browser-use", "browser_use", or "Agent(task=...)".
browserbase · AI review on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add browserbase/skills --skill browser-use-to-stagehandAbout this skill
name: browser-use-to-stagehand
description: Migrate browser-use (Python) browser-automation scripts to Stagehand v3 (TypeScript) on Browserbase. Use when the user wants to convert, port, rewrite, or migrate a browser-use Agent script to Stagehand, map browser-use features/APIs to Stagehand primitives (act/extract/observe/agent), or move agentic browser automation onto Browserbase with more determinism. Triggers on "browser-use", "browser_use", or "Agent(task=...)".
compatibility: "The skill itself uses only Read/Write/Edit/Grep/Bash — no install step. The Stagehand code it generates needs Node 18+, @browserbasehq/stagehand (v3) and zod, plus BROWSERBASE_API_KEY / BROWSERBASE_PROJECT_ID and a model-provider key (e.g. ANTHROPIC_API_KEY) to run. The optional trace-assisted path uses the Browserbase SDK or the sibling browser-trace skill."
license: MIT
allowed-tools: Read, Write, Edit, Grep, Bash
browser-use → Stagehand on Browserbase (/browser-use-to-stagehand)
Convert a browser-use (Python) script into an idiomatic Stagehand v3 (TypeScript) script on Browserbase, choosing the right level of determinism at each step rather than producing a one-to-one agentic copy.
Core principle: browser-use is agentic-by-default (the LLM decides every action). Stagehand lets you choose how much AI to use. A good migration replaces opaque agent loops with an inspectable, mostly-deterministic pipeline — using AI only where the page is genuinely unpredictable. This is a refactor with judgment, not a transpile.
Source of truth & versions. This skill's durable value is the judgment — the determinism spectrum and the decompose-vs-agent decision — not the API specifics, which drift every release. The code mappings here are a snapshot validated against
@browserbasehq/stagehand3.6.x and browser-use 0.13.x (2026-06). On any conflict, the live docs win — always verify against the installed package and these sources before emitting code:
- Stagehand v3: https://docs.stagehand.dev/v3 · installed types:
node_modules/@browserbasehq/stagehand- Browserbase: https://docs.browserbase.com
- browser-use: https://docs.browser-use.com
If the installed Stagehand major is not 3, treat this skill as conceptual only and follow the live docs for every signature.
Reference files (read as needed)
references/api-mapping.md— the mechanical browser-use → Stagehand mapping: variant detection, the full feature table, before/after code, Browserbase platform options, and v3 version gotchas. Read this for any non-trivial construct.references/determinism.md— how to chooseagent()vsact/extract/observevs cachedobserve→act. The decision tree. Read this when deciding how to translate anAgent(task=…).references/trace-assisted.md— the optional "run it on Browserbase, read the logs, then rewrite" workflow for opaque/flaky scripts.references/guide.md— the human migration guide: philosophy shift, feature mapping, the determinism spectrum, and a recommended migration path.references/prompt.md— a self-contained, tool-agnostic version of this skill; paste it into any AI assistant along with a browser-use script.EXAMPLES.md— before/after script pairs.
Workflow
1. Get the source
Obtain the browser-use script(s). If the user only described a script, ask for the file(s). Note the target: TypeScript Stagehand on Browserbase unless they say otherwise.
First, gate on scope — is this even migratable? Not every browser-use file is an
Agent(task=…)script. If the source is browser-use running as an MCP server (uvx browser-use --mcp, amcpServersconfig) there is no Stagehand equivalent — flag it as out of scope, don't invent one (see api-mapping §3.7b). If the browser-use call is embedded in a larger app (a class/tool wrapper, web route, queue task), convert only the browser-use surface and preserve the surrounding app glue — see api-mapping §3.8.
2. Detect the browser-use variant
Identify legacy (pre-0.12) vs stable vs Rust beta (only when imports come from browser_use.beta)
— see api-mapping §1. Note: the classic top-level from browser_use import Agent, ChatBrowserUse
surface is alive and well in 0.13.x — ChatBrowserUse alone is not a beta tell; only a
browser_use.beta import is. All variants translate identically, so when unsure, proceed with the
stable mapping. Normalize legacy names before translating. State which variant you found.
3. Inventory the script
Extract a structured inventory before writing any TypeScript:
- Task(s) — the
task=string(s); split each into its implied ordered steps. - Model — the
Chat*provider + model id. - Browser config — local vs
cdp_url/Browserbase; headless; proxies;user_data_dir/storage_state. - Structured output — any
output_model_schemaPydantic models. - Secrets —
sensitive_data, env-var usage, login flows. - Guardrails —
allowed_domains,max_steps. - Custom actions —
@tools.action/Controllerfunctions, and whether each is a deterministic side-effect or an agent capability. - Setup —
initial_actions, secondary models (page_extraction_llm,planner_llm).
4. Decide the determinism level per step
For each step from the inventory, apply the decision tree in determinism.md:
- Navigate to a known URL →
page.goto(url)on the Stagehand page (no AI). - On-page action →
act("…"); if it repeats,observe()once then replayact(action)(no LLM call). - Reading data →
extract("…", zodSchema). - Genuinely open-ended → keep
stagehand.agent().execute(...)(tightened withmaxSteps/systemPrompt).
Default to decomposition when the flow is known; keep agent() only wh