Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Browser & automation

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-stagehand

About 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/stagehand 3.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:

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 choose agent() vs act/extract/observe vs cached observe→act. The decision tree. Read this when deciding how to translate an Agent(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, a mcpServers config) 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_schema Pydantic models.
  • Secrets — sensitive_data, env-var usage, login flows.
  • Guardrails — allowed_domains, max_steps.
  • Custom actions — @tools.action / Controller functions, 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 replay act(action) (no LLM call).
  • Reading data → extract("…", zodSchema).
  • Genuinely open-ended → keep stagehand.agent().execute(...) (tightened with maxSteps/systemPrompt).

Default to decomposition when the flow is known; keep agent() only wh

Read the complete source ↗