[STG-2850] Add Browser Use to v4 migration guide

[bbclanker]

Summary

Adds a "Migrate Browser Use to v4" guide under packages/docs/v4/migrations/, modeled on the existing v3 and Playwright migration guides in that directory.

The guide frames the core migration story: Browser Use is an autonomous-agent framework (Agent(task=..., llm=...).run()), and Stagehand v4 has no agent object — so, like the v3 guide's "why agent() is gone" narrative, it steers users to code mode (an assistant writes a script once) and tool calling (a model drives the full Stagehand API as tools). It leads with Python (Browser Use is Python-first) and includes TypeScript tabs.

Covered:

• Side-by-side hello world, code mode, and tool calling
• Breaking-change diffs: initialization/teardown, the task string, models (ChatOpenAI/ChatBrowserUse → model), structured output (output_model_schema → extract()), sensitive data (sensitive_data → variables), custom tools (@tools.action), and Browser(...) / @sandbox config
• A quick-reference mapping table and troubleshooting section
• Registered the page in docs.json under the v4 Migration guide group

Browser Use API details were grounded against the browser-use/browser-use repo's own reference docs; Stagehand v4 API against the existing v4 reference pages. All cross-links and deep anchors were verified to resolve, and docs.json validates as JSON.

Test plan

• jq confirms docs.json is valid JSON
• Verified all 13 cross-linked v4 pages exist and the models#model-gateway / act#secure-your-automations anchors resolve
• Confirmed all Python/TypeScript API idioms used (browserbase.launch, local_browser.launch, new_page, wait_for_load_state, ModelConfig, data.extraction, etc.) match usage elsewhere in the v4 docs
• Recommend running just check (Mint config + link validation) in CI

Requested by: sophie@browserbase.com
Linear: https://linear.app/browserbase/issue/STG-2850/add-browser-use-to-v4-migration-guide
Slack thread: https://browserbase.slack.com/archives/D0AH75TNSF9/p1786985811934049

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
stagehand	🟢 Ready	View Preview	Aug 17, 2026, 5:02 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[cubic-dev-ai]

cubic analysis

All reported issues were addressed across 2 files

Linked issue analysis

Linked issue: STG-2850: Add Browser Use to v4 migration guide

Status	Acceptance criteria	Notes
✅	Create a Browser Use → Stagehand v4 migration guide	The new browser-use.mdx guide provides migration guidance, examples, breaking-change mappings, troubleshooting, and references for both Python and TypeScript.
✅	Make the migration guide discoverable in the v4 documentation	The new guide is added to the v4 Migration guide group in the documentation navigation.

Architecture diagram

sequenceDiagram
    participant Dev as Developer/Migration Reader
    participant Docs as v4 Docs (Mintlify)
    participant DocsJSON as docs.json Config
    participant BrowserUse as Browser Use Agent
    participant Stagehand as Stagehand v4 SDK
    participant Browser as Browser Context
    participant LLM as LLM (e.g., GPT-4)
    
    Note over Dev,Docs: NEW: v4 Migration Guide for Browser Use users
    
    Dev->>Docs: Navigates to v4/migrations/browser-use
    Docs->>DocsJSON: CHANGED: Resolves page in nav config
    DocsJSON-->>Docs: Returns page reference
    Docs-->>Dev: Renders migration guide

    rect rgb(240, 240, 240)
    Note over Dev,LLM: Scenario A: Original Browser Use Pattern
    Dev->>BrowserUse: Agent(task="...", llm=...)
    BrowserUse->>Browser: Auto-manages browser session
    BrowserUse->>LLM: Per-step inference calls
    LLM-->>BrowserUse: Action decisions
    BrowserUse-->>Dev: Task result
    end

    rect rgb(240, 240, 240)
    Note over Dev,LLM: Scenario B: Stagehand v4 Pattern (Code Mode)
    Dev->>Stagehand: browserbase.launch(api_key)
    Stagehand->>Browser: Creates browser instance
    Dev->>Stagehand: Stagehand.create(browser)
    Stagehand->>Browser: Attaches runtime
    Dev->>Browser: page.locator() / page.goto()
    Browser-->>Dev: Deterministic results
    opt Model needed
        Dev->>Stagehand: stagehand.act("...")
        Stagehand->>LLM: Single inference call
        LLM-->>Stagehand: Action
        Stagehand-->>Dev: Result
    end
    end

    rect rgb(240, 240, 240)
    Note over Dev,LLM: Scenario C: Tool Calling Pattern
    Dev->>Stagehand: Exposes API as tools
    Stagehand->>Browser: page.snapshot() returns xpathMap
    Browser-->>Stagehand: Accessibility tree + selectors
    Stagehand->>LLM: Model reads page structure
    LLM-->>Stagehand: Selects tool + selector
    Stagehand->>Browser: Executes locator action
    Browser-->>Stagehand: Result
    Stagehand-->>Dev: Final response
    end

    Note over Dev,Docs: Includes: code mode, tool calling, migration diffs,<br/>env vars, custom tools, troubleshooting

Loading

<sub>Tip: cubic used a learning from your PR history. Let your coding agent read cubic learnings directly with the cubic MCP.

Re-trigger cubic</sub>

[changeset-bot]

⚠️ No Changeset found

Latest commit: c7ab9d4

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[cubic-dev-ai]

All reported issues were addressed across 1 file (changes from recent commits).

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 1 file (changes from recent commits).

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>