Migrate all Stagehand templates to V4

README.md

@@ -1,5 +1,7 @@
 # Stagehand + Browserbase Templates
 
+Stagehand is the SDK for browser agents.
+
 Ready-to-use automation templates for Stagehand and Browserbase. Each template has its own README with setup instructions.
 
 > All templates also live on [browserbase.com/templates](https://www.browserbase.com/templates)
@@ -15,20 +17,20 @@ Ready-to-use automation templates for Stagehand and Browserbase. Each template h
 | basic-recaptcha                  | [TS](typescript/basic-recaptcha)                  | [PY](python/basic-recaptcha)                  | -                   | Automatic reCAPTCHA solving using Browserbase's built-in captcha solving capabilities                          |
 | browser-agent-demo               | [TS](typescript/browser-agent-demo)               | -                                             | -                   | Browser agent that searches the web, fetches page content, and autonomously extracts information               |
 | browserbase-reducto              | [TS](typescript/browserbase-reducto)              | [PY](python/browserbase-reducto)              | -                   | Download financial PDFs from websites and extract structured data using AI-powered document parsing            |
-| business-lookup                  | [TS](typescript/business-lookup)                  | [PY](python/business-lookup)                  | -                   | Automate business registry searches using an autonomous AI agent with computer-use capabilities                |
+| business-lookup                  | [TS](typescript/business-lookup)                  | [PY](python/business-lookup)                  | -                   | Research business registry records with a bring-your-own agent and Stagehand code mode                         |
 | cartesia-form-filling            | -                                                 | [PY](python/cartesia-form-filling)            | -                   | Voice agent that conducts phone questionnaires while automatically filling out web forms                       |
 | cerebras-docs-checker            | -                                                 | [PY](python/cerebras-docs-checker)            | -                   | Crawl documentation sites, discover source repos, and verify docs accuracy against actual codebase             |
 | company-address-finder           | [TS](typescript/company-address-finder)           | [PY](python/company-address-finder)           | -                   | Discover company legal information and physical addresses from Terms of Service and Privacy Policy pages       |
 | company-value-prop-generator     | [TS](typescript/company-value-prop-generator)     | [PY](python/company-value-prop-generator)     | -                   | Extract and format website value propositions into concise one-liners for email personalization                |
 | context                          | [TS](typescript/context)                          | [PY](python/context)                          | -                   | Persistent authentication using Browserbase contexts that survive across sessions                              |
 | council-events                   | [TS](typescript/council-events)                   | [PY](python/council-events)                   | -                   | Automate event information extraction from Philadelphia Council                                                |
 | download-financial-statements    | [TS](typescript/download-financial-statements)    | [PY](python/download-financial-statements)    | -                   | Download Apple's quarterly financial statements (PDFs) from their investor relations site                      |
-| dynamic-form-filling             | [TS](typescript/dynamic-form-filling)             | -                                             | -                   | Intelligent form filling using a Stagehand AI agent that understands form context and uses semantic matching   |
+| dynamic-form-filling             | [TS](typescript/dynamic-form-filling)             | -                                             | -                   | Fill dynamic forms with a Vercel AI SDK agent and Stagehand's code_execute browser tool                        |
 | exa-browserbase                  | [TS](typescript/exa-browserbase)                  | [PY](python/exa-browserbase)                  | -                   | Automate job applications with AI that writes smart, tailored responses for each role                          |
 | extend-browserbase               | [TS](typescript/extend-browserbase)               | [PY](python/extend-browserbase)               | -                   | Download receipts from an expense portal and extract structured receipt data using AI-powered document parsing |
 | form-filling                     | [TS](typescript/form-filling)                     | [PY](python/form-filling)                     | -                   | Automate form filling with Stagehand and Browserbase                                                           |
-| gemini-3-flash                   | [TS](typescript/gemini-3-flash)                   | -                                             | -                   | Autonomous web browsing using Google's Gemini 3 Flash with Stagehand and Browserbase                           |
-| gemini-cua                       | [TS](typescript/gemini-cua)                       | [PY](python/gemini-cua)                       | -                   | Autonomous web browsing using Google's Computer Use Agent with Stagehand and Browserbase                       |
+| gemini-3-flash                   | [TS](typescript/gemini-3-flash)                   | -                                             | -                   | Browser research with a Gemini 3 Flash agent and Stagehand code mode                                           |
+| gemini-cua                       | [TS](typescript/gemini-cua)                       | [PY](python/gemini-cua)                       | -                   | Browser research with a bring-your-own Gemini agent and Stagehand code mode                                    |
 | getting-started-with-browserbase | [TS](typescript/getting-started-with-browserbase) | [PY](python/getting-started-with-browserbase) | -                   | Demo all three core Browserbase capabilities: Search API, Fetch API, and Browser Sessions                      |
 | gift-finder                      | [TS](typescript/gift-finder)                      | [PY](python/gift-finder)                      | -                   | Find personalized gift recommendations using AI-generated search queries and intelligent product scoring       |
 | google-trends                    | [TS](typescript/google-trends)                    | [PY](python/google-trends)                    | -                   | Extract trending search keywords from Google Trends for any country with structured JSON output                |
@@ -38,7 +40,7 @@ Ready-to-use automation templates for Stagehand and Browserbase. Each template h
 | license-verification             | [TS](typescript/license-verification)             | [PY](python/license-verification)             | -                   | Extract structured, validated data from websites using Stagehand + Zod                                         |
 | manual-mfa-with-contexts         | [TS](typescript/manual-mfa-with-contexts)         | [PY](python/manual-mfa-with-contexts)         | -                   | Persist authentication across sessions using Browserbase Contexts, eliminating MFA friction                    |
 | mfa-handling                     | [TS](typescript/mfa-handling)                     | [PY](python/mfa-handling)                     | -                   | Automate MFA completion using TOTP (Time-based One-Time Password) code generation                              |
-| microsoft-cua                    | [TS](typescript/microsoft-cua)                    | -                                             | -                   | Autonomous web browsing using Microsoft's Computer Use Agent with Stagehand and Browserbase                    |
+| microsoft-cua                    | [TS](typescript/microsoft-cua)                    | -                                             | -                   | Browser research with a bring-your-own OpenAI agent and Stagehand code mode                                    |
 | nurse-verification               | [TS](typescript/nurse-verification)               | [PY](python/nurse-verification)               | -                   | Automate verification of nurse licenses by filling forms and extracting structured results                     |
 | pickleball                       | [TS](typescript/pickleball)                       | [PY](python/pickleball)                       | -                   | Automate tennis and pickleball court bookings in San Francisco Recreation & Parks system                       |
 | playwright                       | [TS](typescript/playwright)                       | [PY](python/playwright)                       | -                   | Raw Playwright usage with Browserbase (no Stagehand)                                                           |
@@ -54,9 +56,9 @@ Ready-to-use automation templates for Stagehand and Browserbase. Each template h
 
 ## Model Gateway
 
-Templates use the Model Gateway to route LLM requests -- you only need your `BROWSERBASE_API_KEY`. No separate OpenAI, Anthropic, or Google API keys required. Supported models include OpenAI, Anthropic, and Google (Gemini).
+Stagehand primitives use the Browserbase Model Gateway, so they need only `BROWSERBASE_API_KEY`. Bring-your-own-agent templates also use Vercel AI Gateway for the outer agent loop and require `AI_GATEWAY_API_KEY`; no provider-specific OpenAI, Anthropic, or Google key is required.
 
-> **Note**: CUA (Computer Use Agent) models are not yet supported through the Model Gateway. Templates using CUA models still require a separate model provider API key.
+> **Stagehand V4 note**: V4 does not expose the V3 `agent()` orchestration API. TypeScript agent templates use Vercel AI SDK with Stagehand's `code_execute` tool. Python agent templates use LangChain Deep Agents with Stagehand's `run`, `snapshot`, and `screenshot` tools. Other templates call V4 browser primitives directly.
 
 ## Getting Started
 
@@ -77,7 +79,7 @@ Each template's README contains detailed installation steps, environment variabl
 
 ### Documentation
 
-- **Stagehand Docs**: https://docs.stagehand.dev/v3/first-steps/introduction
+- **Stagehand Docs**: https://docs.stagehand.dev/v4/first-steps/introduction
 - **Browserbase Docs**: https://docs.browserbase.com
 
 ### Support

go/hackernews/README.md

@@ -1,77 +1,63 @@
 # Stagehand + Browserbase: Hacker News Automation
 
+Stagehand is the SDK for browser agents.
+
 ## AT A GLANCE
 
-- Goal: Demonstrate Stagehand's core browser automation features through a complete Hacker News workflow.
-- Comprehensive Example: Shows navigate, observe, act, extract, and execute (autonomous agent) in a single workflow.
-- Real-world Scenario: Navigates to Hacker News, clicks on top post comments, extracts structured data, and uses an autonomous agent to find the newest post.
-- Docs → https://docs.stagehand.dev/v3/sdk/go
+- Goal: demonstrate Stagehand V4's core browser automation primitives through a complete Hacker News workflow.
+- Complete workflow: launch a Browserbase browser, attach Stagehand, navigate, observe, act, and extract typed data.
+- Real-world outcome: open the top story's comments, verify its first comment, then extract the newest visible story.
+- Docs → https://docs.stagehand.dev/v4/first-steps/quickstart
 
 ## GLOSSARY
 
-- navigate: Load a web page in the browser session
-  Docs → https://docs.stagehand.dev/v3/references/page
-- observe: Analyze page elements and generate actionable steps based on natural language instructions
-  Docs → https://docs.stagehand.dev/v3/basics/observe
-- act: Execute actions on web pages using natural language instructions
-  Docs → https://docs.stagehand.dev/v3/basics/act
-- extract: Extract structured data from pages using JSON schema definitions
-  Docs → https://docs.stagehand.dev/v3/basics/extract
-- execute: Run an autonomous agent to complete multi-step tasks automatically
-  Docs → https://docs.stagehand.dev/v3/basics/act
+- `LaunchBrowserbase`: create a Browserbase browser owned by the application.
+- `Create`: attach Stagehand V4 to that browser.
+- `Observe`: find possible page actions from a natural-language instruction.
+- `Act`: execute either an observed action or a natural-language instruction.
+- `Extract`: return typed structured data together with result metadata.
 
 ## QUICKSTART
 
-1. Ensure Go 1.22+ is installed (`go version`)
-2. Set required environment variables:
-   ```bash
-   export BROWSERBASE_API_KEY="your-api-key"
-   export MODEL_API_KEY="your-model-api-key"
-   ```
-3. Run the example:
-   ```bash
-   go run main.go
-   ```
+1. Install Go 1.26 or newer (`go version`).
+2. Set `BROWSERBASE_API_KEY` in your environment.
+3. Run `go mod download`.
+4. Run `go run .`.
+
+The V4 Go SDK is temporarily pinned to an exact Stagehand source commit. Replace it with the published V4 Go module once that package is released.
 
 ## EXPECTED OUTPUT
 
-- Session initialization with Browserbase
-- Navigation to Hacker News homepage
-- Observation of page to find comment links for the top post
-- Action execution to click on the comment link
-- Structured data extraction (title, top comment, author)
-- Autonomous agent execution to navigate back and find the newest post
-- Session cleanup and termination
-- Live session recording link displayed in console
+- Launches a real Browserbase browser and attaches Stagehand V4.
+- Navigates to Hacker News and verifies the main-document HTTP response.
+- Observes and opens the comments link for the top-ranked story.
+- Extracts and validates the story title, first comment, and commenter.
+- Navigates to `/newest` and validates the newest story title and URL.
+- Explicitly closes Stagehand before closing the browser.
 
 ## COMMON PITFALLS
 
-- Missing Go installation: Ensure Go 1.22+ is installed (`go version`)
-- Missing environment variables: Verify BROWSERBASE_API_KEY and MODEL_API_KEY are set
-- Module not found: Run `go mod download` if dependencies aren't resolved
-- Network issues: Check internet connection and website accessibility
-- Session errors: Verify API keys are valid in Browserbase dashboard
-- Find more information on your Browserbase dashboard -> https://www.browserbase.com/sign-in
+- Missing Go installation: ensure Go 1.26+ is installed.
+- Missing credentials: verify `BROWSERBASE_API_KEY` is set.
+- Module not found: run `go mod download` if dependencies are not resolved.
+- No `MODEL_API_KEY` is needed: Stagehand primitives use Browserbase Model Gateway.
+- Stagehand V4 does not expose an agent API. Bring your own agent framework when orchestration is required.
 
 ## USE CASES
 
-• Content aggregation: Automate data extraction from news sites, forums, and social platforms for monitoring and analysis.
-• Research automation: Collect structured information from multiple pages using autonomous agents for competitive intelligence.
-• Testing workflows: Validate web interactions, form submissions, and navigation flows across different pages.
-• Data scraping: Extract structured data from dynamic websites that require JavaScript execution and user interactions.
+- Content aggregation: extract structured records from news sites, forums, and social platforms.
+- Research automation: combine deterministic navigation with AI-guided actions and typed extraction.
+- Workflow testing: validate page interaction and navigation outcomes in a real cloud browser.
 
 ## NEXT STEPS
 
-• Add error handling: Implement retry logic for failed actions and better error messages for debugging.
-• Extend extraction schema: Add more fields to extract (upvotes, comment count, post date, etc.).
-• Multi-page workflows: Chain multiple navigations and extractions to build comprehensive data collection pipelines.
-• Customize agent instructions: Modify the execute instruction to perform different tasks (e.g., find posts by keyword, filter by score).
+- Add retries for transient site or model failures.
+- Extend the extraction types with points, comment count, and post age.
+- Add an external Go agent framework if the workflow needs autonomous planning.
 
 ## HELPFUL RESOURCES
 
-📚 Stagehand Go Docs: https://docs.stagehand.dev/v3/sdk/go
-🎮 Browserbase: https://www.browserbase.com
-💡 Try it out: https://www.browserbase.com/playground
-🔧 Templates: https://www.browserbase.com/templates
-📧 Need help? support@browserbase.com
-💬 Discord: http://stagehand.dev/discord
+- Stagehand Docs: https://docs.stagehand.dev/v4/first-steps/quickstart
+- Browserbase: https://www.browserbase.com
+- Templates: https://www.browserbase.com/templates
+- Discord: http://stagehand.dev/discord

go/hackernews/go.mod

@@ -1,12 +1,18 @@
 module stagehand-example
 
-go 1.22
+go 1.26.0
 
-require github.com/browserbase/stagehand-go v0.16.1
+// TODO: Replace this commit pin with the published Stagehand V4 Go module after it is released.
+require github.com/browserbase/stagehand/packages/sdk-go v0.0.0-20260810174315-a46676658b4f
 
 require (
-	github.com/tidwall/gjson v1.18.0 // indirect
-	github.com/tidwall/match v1.1.1 // indirect
-	github.com/tidwall/pretty v1.2.1 // indirect
-	github.com/tidwall/sjson v1.2.5 // indirect
+	github.com/bahlo/generic-list-go v0.2.0 // indirect
+	github.com/buger/jsonparser v1.1.2 // indirect
+	github.com/coder/websocket v1.8.13 // indirect
+	github.com/invopop/jsonschema v0.14.0 // indirect
+	github.com/pb33f/ordered-map/v2 v2.3.1 // indirect
+	go.opentelemetry.io/otel v1.35.0 // indirect
+	go.opentelemetry.io/otel/trace v1.35.0 // indirect
+	go.yaml.in/yaml/v4 v4.0.0-rc.2 // indirect
+	golang.org/x/mod v0.38.0 // indirect
 )