[Docs] v3-->v4 migration guide by akeimach · Pull Request #2613 · browserbase/stagehand

akeimach · 2026-08-05T23:25:08Z

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 table, troubleshooting, and rationale for removing agent(). Updates the docs nav with a new “Migration guide” group and aligns with Linear STG-2685.

Migration
- New guide at v4/migrations/v3 with TypeScript and Python examples using @browserbasehq/stagehand; includes a copy-paste upgrade block, a recommended migration 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; 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).

^{Written for commit 3db26a8. Summary will update on new commits.}

changeset-bot · 2026-08-05T23:25:16Z

⚠️ No Changeset found

Latest commit: 3db26a8

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

Kylejeong2 · 2026-08-06T00:22:40Z

+| Streaming, callbacks, abort signal, message continuation | No equivalent. Your loop already sits between steps, so log, cancel, or persist there |
+
+<Note>
+If you want a framework to own the loop instead of writing it yourself, the [LangChain](/v4/integrations/langchain/introduction) and [CrewAI](/v4/integrations/crew-ai/introduction) integrations expose the primitives as agent tools.


i think we'll have an overview page for agent integrations as a port to all the integrations which we can link to as well later

Sounds great, I've made this a TODO for now

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

_{Reply with feedback, questions, or to request a fix.

Re-trigger cubic}

cubic-dev-ai

1 issue found across 2 files

Confidence score: 4/5

In packages/docs/v4/migrations/v3.mdx, the migration mapping reads as language-agnostic even though it is TypeScript-specific, so Python users may copy invalid fields (modelName, apiKey, onLog) and hit avoidable runtime/type errors during migration — split the guidance by language (or clearly label TS-only fields) and provide Python-safe equivalents.

Prompt for AI agents (unresolved issues)


Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/docs/v4/migrations/v3.mdx">

<violation number="1" location="packages/docs/v4/migrations/v3.mdx:263">
P2: The copy-paste migration mapping is TypeScript-only but appears language-agnostic, so Python users can migrate to non-existent fields (`modelName`, `apiKey`, `onLog`) and get runtime/type errors. Consider splitting this block by language (or annotating TS vs Python equivalents) so Python points to `model`, `model_api_key`, and `on_log`.

(Based on your team's feedback about SDK-native field spellings for TS/Python.)</violation>
</file>

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()

_{Reply with feedback, questions, or to request a fix.

Re-trigger cubic}

cubic-dev-ai · 2026-08-07T15:31:13Z

+  - act/extract/observe now return { data, metadata }; read .data
+  - extract({ instruction, schema })  ->  extract(instruction, schema)
+  - page.deepLocator(sel)  ->  page.locator(sel)
+  - modelName + modelClientOptions  ->  model: { modelName, apiKey }


P2: The copy-paste migration mapping is TypeScript-only but appears language-agnostic, so Python users can migrate to non-existent fields (modelName, apiKey, onLog) and get runtime/type errors. Consider splitting this block by language (or annotating TS vs Python equivalents) so Python points to model, model_api_key, and on_log.

(Based on your team's feedback about SDK-native field spellings for TS/Python.)

View Feedback

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At packages/docs/v4/migrations/v3.mdx, line 263: <comment>The copy-paste migration mapping is TypeScript-only but appears language-agnostic, so Python users can migrate to non-existent fields (`modelName`, `apiKey`, `onLog`) and get runtime/type errors. Consider splitting this block by language (or annotating TS vs Python equivalents) so Python points to `model`, `model_api_key`, and `on_log`. (Based on your team's feedback about SDK-native field spellings for TS/Python.) </comment> <file context> @@ -0,0 +1,488 @@ + - act/extract/observe now return { data, metadata }; read .data + - extract({ instruction, schema }) -> extract(instruction, schema) + - page.deepLocator(sel) -> page.locator(sel) + - modelName + modelClientOptions -> model: { modelName, apiKey } + - enableCaching -> cache + - verbose + logger -> logging: { level, format, onLog } </file context>

Kylejeong2 · 2026-08-07T19:48:07Z

+icon: 'arrow-up-right-dots'
+---
+
+Two changes account for most of this migration:


should we recommend just giving this page to your agent to help you fast migrate?

Kylejeong2 reviewed Aug 6, 2026

View reviewed changes

akeimach force-pushed the alyssamaruyama/stg-2685-do-a-migration-guide branch from 29e0822 to 8279a88 Compare August 7, 2026 06:14

akeimach marked this pull request as ready for review August 7, 2026 14:16

akeimach requested a review from a team as a code owner August 7, 2026 14:16

cubic-dev-ai Bot reviewed Aug 7, 2026

View reviewed changes

Comment thread packages/docs/v4/migrations/v3.mdx Outdated

Comment thread packages/docs/v4/migrations/v3.mdx Outdated

Comment thread packages/docs/v4/migrations/v3.mdx Outdated

akeimach changed the title ~~v3-->v4 migration guide~~ [Docs] v3-->v4 migration guide Aug 7, 2026

akeimach added 7 commits August 7, 2026 10:05

Rough draft for v3-->v4 migration guide

0bd7c2c

general doc not just typescript

32b9c89

next iteration of migration doc

7c1e454

fix sidebar not plural

ae3ea44

move table, clean up intro

d751f6e

add todo for integrations

b5192b2

integrate cubic comments

3db26a8

akeimach force-pushed the alyssamaruyama/stg-2685-do-a-migration-guide branch from 0595ba6 to 3db26a8 Compare August 7, 2026 15:16

cubic-dev-ai Bot reviewed Aug 7, 2026

View reviewed changes

akeimach added the v4-pre-release label Aug 7, 2026

Kylejeong2 reviewed Aug 7, 2026

View reviewed changes

Kylejeong2 approved these changes Aug 8, 2026

View reviewed changes

Navigation Menu

Uh oh!

[Docs] v3-->v4 migration guide - #2613

[Docs] v3-->v4 migration guide#2613
akeimach wants to merge 7 commits into
v4-spikefrom
alyssamaruyama/stg-2685-do-a-migration-guide

akeimach commented Aug 5, 2026 •

edited by cubic-dev-ai Bot

Loading

Uh oh!

changeset-bot Bot commented Aug 5, 2026 •

edited

Loading

Uh oh!

Kylejeong2 Aug 6, 2026

Uh oh!

akeimach Aug 7, 2026

Uh oh!

cubic-dev-ai Bot left a comment •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cubic-dev-ai Bot left a comment

Uh oh!

cubic-dev-ai Bot Aug 7, 2026

Uh oh!

Kylejeong2 Aug 7, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

akeimach commented Aug 5, 2026 • edited by cubic-dev-ai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

why

what changed

test plan

Summary by cubic

Uh oh!

changeset-bot Bot commented Aug 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ No Changeset found

Uh oh!

Kylejeong2 Aug 6, 2026

Choose a reason for hiding this comment

Uh oh!

akeimach Aug 7, 2026

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cubic-dev-ai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai Bot Aug 7, 2026

Choose a reason for hiding this comment

Uh oh!

Kylejeong2 Aug 7, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

akeimach commented Aug 5, 2026 •

edited by cubic-dev-ai Bot

Loading

changeset-bot Bot commented Aug 5, 2026 •

edited

Loading

cubic-dev-ai Bot left a comment •

edited

Loading