Quickstart

Build your first Stagehand automation with act, extract, and observe.

The quickest way to start with Stagehand is to install the SDK, point it at a browser, and write a script. This page gets you from an empty directory to a working automation in three steps, using a browser on your own machine.

1. Create a sample project

   TypeScript

   mkdir my-stagehand-app && cd my-stagehand-app
   pnpm init -y
   pnpm install @browserbasehq/stagehand 'zod@~4.4.3'
   

   Keep Zod on the 4.4.x minor version to match Stagehand’s supported types. Newer Zod minor versions can cause TypeScript errors when passing schemas to extract().

   Python

   mkdir my-stagehand-app && cd my-stagehand-app
   python3 -m venv .venv && source .venv/bin/activate
   pip install stagehand
   

   Go

   mkdir my-stagehand-app && cd my-stagehand-app
   go mod init example.com/my-stagehand-app
   go get github.com/browserbase/stagehand/packages/sdk-go/v4@v4.0.0
   

   Stagehand drives a local browser through the Chrome DevTools Protocol, so install Chrome on your machine before running the script.

2. Write the script

   Create the example script (index.ts, main.py, or main.go). It exercises all three primitives: act, extract, and observe.

   TypeScript

   import { localBrowser, Stagehand } from "@browserbasehq/stagehand";
   import { z } from "zod/v4";
   
   async function main() {
     const browser = await localBrowser.launch();
     try {
       const stagehand = await Stagehand.create({
         browser,
         model: {
           modelName: "openai/gpt-5.6-sol",
           apiKey: process.env.OPENAI_API_KEY,
         },
       });
       console.log("Stagehand session started");
       try {
         const [page] = await browser.context.pages();
   
         await page.goto("https://stagehand.dev");
   
         const extractResult = await stagehand.extract(
           "Extract the value proposition from the page.",
           z.object({ valueProposition: z.string() }),
         );
         console.log("Extract result:\n", extractResult.data);
   
         await stagehand.act("Click the 'Evals' button.");
   
         const observeResult = await stagehand.observe("What can I click on this page?");
         console.log("Observe result:\n", observeResult.data);
       } finally {
         await stagehand.close();
       }
     } finally {
       await browser.close();
     }
   }
   
   main().catch((err) => {
     console.error(err);
     process.exit(1);
   });
   

   Python

   import asyncio
   import os
   
   from pydantic import BaseModel
   from stagehand import Stagehand, local_browser
   
   
   class ValueProposition(BaseModel):
       value_proposition: str
   
   
   async def main() -> None:
       browser = await local_browser.launch()
       try:
           stagehand = await Stagehand.create(
               browser=browser,
               model="openai/gpt-5.6-sol",
               model_api_key=os.environ["OPENAI_API_KEY"],
           )
           print("Stagehand session started")
           try:
               page = (await browser.context.pages())[0]
   
               await page.goto("https://stagehand.dev")
   
               extract_result = await stagehand.extract(
                   "Extract the value proposition from the page.",
                   ValueProposition,
               )
               print("Extract result:\n", extract_result.data)
   
               await stagehand.act("Click the 'Evals' button.")
   
               observe_result = await stagehand.observe("What can I click on this page?")
               print("Observe result:\n", observe_result.data)
           finally:
               await stagehand.close()
       finally:
           await browser.close()
   
   
   asyncio.run(main())
   

   Go

   package main
   
   import (
   	"context"
   	"errors"
   	"fmt"
   	"log"
   	"os"
   
   	stagehand "github.com/browserbase/stagehand/packages/sdk-go/v4"
   )
   
   type valueProposition struct {
   	ValueProposition string `json:"value_proposition"`
   }
   
   func main() {
   	if err := run(context.Background()); err != nil {
   		log.Fatal(err)
   	}
   }
   
   func run(ctx context.Context) (err error) {
   	modelAPIKey := os.Getenv("OPENAI_API_KEY")
   	model := stagehand.ModelConfig{
   		ModelName: "openai/gpt-5.6-sol",
   		APIKey:    &modelAPIKey,
   	}
   
   	browser, err := stagehand.LaunchLocalBrowser(ctx, &stagehand.LocalBrowserLaunchOptions{})
   	if err != nil {
   		return err
   	}
   	defer func() { err = errors.Join(err, browser.Close(ctx)) }()
   
   	client, err := stagehand.Create(ctx, stagehand.CreateOptions{
   		Browser: browser,
   		Model:   &model,
   	})
   	if err != nil {
   		return err
   	}
   	defer func() { err = errors.Join(err, client.Close(ctx)) }()
   
   	fmt.Println("Stagehand session started")
   
   	browserContext, err := browser.Context()
   	if err != nil {
   		return err
   	}
   	pages, err := browserContext.Pages(ctx)
   	if err != nil {
   		return err
   	}
   	if len(pages) == 0 {
   		return errors.New("Stagehand initialized without an active page")
   	}
   	page := pages[0]
   
   	if _, err := page.Goto(ctx, "https://stagehand.dev", nil); err != nil {
   		return err
   	}
   
   	extracted, err := stagehand.Extract[valueProposition](
   		ctx,
   		client,
   		"Extract the value proposition from the page.",
   		nil,
   	)
   	if err != nil {
   		return err
   	}
   	fmt.Printf("Extract result:\n%+v\n", extracted)
   
   	if _, err := client.Act(ctx, stagehand.ActInstruction("Click the 'Evals' button."), nil); err != nil {
   		return err
   	}
   
   	instruction := "What can I click on this page?"
   	observeResult, err := client.Observe(ctx, &instruction, nil)
   	if err != nil {
   		return err
   	}
   	fmt.Printf("Observe result:\n%+v\n", observeResult.Data)
   
   	return nil
   }
   

   Stagehand never reads environment variables on your behalf. Read your model provider API key in your own code and pass it to Stagehand.create(), as the script above does. A local browser cannot use the Model Gateway, so Stagehand requires you to provide a model and its API key.

3. Run it

   Set your model provider API key, then run the script. Stagehand launches Chrome on your machine and opens a visible window, so you can watch each step as it happens.

   TypeScript

   export OPENAI_API_KEY="sk-..." # Your model provider API key
   pnpm dlx tsx index.ts          # Run the example script
   

   Python

   export OPENAI_API_KEY="sk-..." # Your model provider API key
   python main.py                 # Run the example script
   

   Go

   export OPENAI_API_KEY="sk-..." # Your model provider API key
   go run .                       # Run the example script
   

   Ready to run in the cloud, with stealth, proxies, and session recordings? Swap localBrowser.launch() for browserbase.launch() with your Browserbase API key, and the Model Gateway picks and authenticates a model for you. See Browser configuration.

Next steps

Learn about the Stagehand primitives: act, extract, and observe.

Act

Perform actions on web pages with natural language

Extract

Get structured data with typed schemas

Observe

Discover available elements and actions

Installation

Add Stagehand to an existing project