[Docs] v3-->v4 migration guide

[akeimach]

why

what changed

test plan

---

Summary by cubic

Adds a v3→v4 migration guide with two paths to replace agent()—code mode or a tool-calling loop—plus a quick reference, troubleshooting, and why agent() was removed. Updates the docs nav with a new “Migration guide” group and aligns with Linear STG-2685. Includes TypeScript, Python, and Go examples.

• Migration
  • New guide at v4/migrations/v3 with TypeScript, Python, and Go examples using @browserbasehq/stagehand; includes AI rules setup, a copy/paste migration prompt, a recommended order, quick reference, troubleshooting, and a TODO for an integrations overview link.
  • Replace agent() with either: (1) Code mode (generate a v4 script), or (2) a tool-calling loop exposing the full API with a suggested tool surface; use page.snapshot() for planner context; optional page tools via WebMCP.
  • Initialize with browserbase.launch()/localBrowser.launch() and Stagehand.create({ browser }) (constructor is private).
  • Pages/context now on browser.context with async getters; act(), extract(), and observe() moved to the Stagehand instance (target tabs with { page }); prefer retrying observe().
  • Primitives return { data, metadata }; extract() uses positional args.
  • Model config is model: { modelName, apiKey }; enable server caching with cache (requires a Browserbase browser).
  • Logging via logging: { level, format, onLog }; metrics via await stagehand.metrics().
  • Manage Browserbase session IDs explicitly; page.deepLocator() removed (use page.locator() with the same selectors).
  • Adds a “Coming from Python or Go” mapping from the v3 hosted clients to the unified v4 SDK.

^{Written for commit 698c8be. Summary will update on new commits.}

[changeset-bot]

⚠️ No Changeset found

Latest commit: 698c8be

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 2 files

Architecture diagram

sequenceDiagram
    participant Dev as Developer
    participant AS as AI Assistant
    participant Rules as AI Rules File
    participant SH as Stagehand v4 SDK
    participant Browser as Browser Instance
    participant Page as Page / Context
    participant Model as LLM Model

    Note over Dev,Model: v3→v4 Migration - Code Mode Path

    Dev->>AS: Request: "Write a Stagehand v4 script that..."
    AS->>Rules: Read AI rules (v4 API conventions)
    Rules-->>AS: Return rules
    AS->>SH: Generate script using Stagehand.create()
    AS-->>Dev: Return generated script
    
    Dev->>SH: Execute generated script
    SH->>Browser: browserbase.launch() / localBrowser.launch()
    Browser-->>SH: Return browser instance
    SH->>SH: Stagehand.create({ browser })
    SH->>Browser: browser.context.newPage(url)
    Browser-->>SH: Return page
    
    alt Deterministic operations (stable selectors)
        SH->>Page: page.locator().click()
        SH->>Page: page.goto()
        Page-->>SH: Standard Playwright responses
    else Model-backed operations (natural language)
        SH->>Page: page.snapshot()
        Page-->>SH: formattedTree + xpathMap
        SH->>Model: stagehand.act("Open most-commented story")
        Model-->>SH: Action instruction
        SH->>Page: Locator-based action
        SH->>Model: stagehand.extract("Extract top 5 comments", schema)
        Model-->>SH: Structured data
    end
    
    SH-->>Dev: Return { data, metadata }
    Dev->>SH: stagehand.close()
    SH->>Browser: browser.close()

    Note over Dev,Model: v3→v4 Migration - Tool Calling Path

    Dev->>AS: Request: "Create tool-calling loop"
    AS->>Rules: Read AI rules
    Rules-->>AS: Return rules
    AS-->>Dev: Return tool definitions
    
    alt Tool execution loop
        loop Each step
            Dev->>Model: Call with tool definitions + context
            Model-->>Dev: Select tool + parameters
            alt Navigation tools
                Dev->>Page: page.goto() / page.reload() / page.goBack()
            else Perception tools
                Dev->>Page: page.snapshot() / page.screenshot()
                Page-->>Dev: formattedTree (for next model call)
            else Element interaction
                Dev->>Page: locator.click() / locator.fill()
            else Model-backed tools
                Dev->>SH: stagehand.act() / stagehand.extract()
                SH->>Model: Process natural language instruction
                Model-->>SH: Result
                SH-->>Dev: { data, metadata }
            end
        end
    end

Loading

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 2 files

Architecture diagram

sequenceDiagram
    participant CodeGen as AI Coding Assistant
    participant UserScript as Stagehand Script
    participant SDK as Stagehand v4 SDK
    participant Page as Browser Page
    participant Model as AI Model (LLM)
    participant Snap as Page Snapshot

    Note over CodeGen,Snap: Migration Path 1: Code Mode (Recommended)

    UserScript->>SDK: browserbase.launch() / localBrowser.launch()
    SDK-->>UserScript: Browser instance
    UserScript->>SDK: Stagehand.create({ browser })
    SDK-->>UserScript: Stagehand instance
    UserScript->>Page: browser.context.newPage(url)
    Page-->>UserScript: Page handle

    alt Deterministic Navigation
        UserScript->>Page: page.locator(selector).click()
        UserScript->>Page: page.goto(url)
        Page-->>UserScript: DOM state
    else Model-backed Interaction
        UserScript->>SDK: stagehand.act("Natural language instruction")
        SDK->>Model: Process instruction
        Model-->>SDK: Action plan
        SDK->>Page: Execute action
        Page-->>SDK: Result
        SDK-->>UserScript: { data, metadata }
    end

    UserScript->>SDK: stagehand.extract("Extract structured data", schema)
    SDK->>Page: Read page content
    Page-->>SDK: Raw content
    SDK->>Model: Parse structure
    Model-->>SDK: Structured result
    SDK-->>UserScript: { data, metadata }

    Note over CodeGen,Snap: Migration Path 2: Tool-Calling Loop

    UserScript->>Page: page.snapshot()
    Page->>Snap: Build formattedTree + xpathMap
    Snap-->>UserScript: Accessibility tree + selectors

    loop Each step
        UserScript->>Model: Expose tools (click, fill, snapshot, act, extract, etc.)
        Model->>SDK: Choose tool + parameters
        alt Deterministic tool
            SDK->>Page: Use Playwright locator (click, fill, goto)
            Page-->>SDK: Result
        else Model-backed tool
            SDK->>Model: Process natural language
            Model-->>SDK: Structured action
            SDK->>Page: Execute
            Page-->>SDK: Result
        end
        SDK-->>UserScript: { data, metadata }
    end

    Note over UserScript,SDK: Cleanup

    UserScript->>SDK: stagehand.close()
    UserScript->>SDK: browser.close()

Loading

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

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

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>