Stagehand

https://docs.stagehand.dev
Admin
Stagehand is a browser automation tool that allows users to automate web browsers with natural...
Tokens:313,947
Snippets:2,639
Trust Score:8.3
Update:1 month ago
Show doc for...
Tokens:
Raw
### Quickstart: clone, install, configure, and run the CrewAI example

Source: https://docs.stagehand.dev/v4/integrations/crewai

Clone and build Stagehand, install the CrewAI example, configure the agent model and browser, then run a browser task. The example uses an OpenAI model by default; set CREWAI_MODEL to use another model supported by CrewAI. Local Chrome is the default browser; set STAGEHAND_BROWSER and BROWSERBASE_API_KEY to use Browserbase.

```bash
git clone https://github.com/browserbase/stagehand.git
cd stagehand
pnpm install --frozen-lockfile
pnpm exec turbo run build \
  --filter @browserbasehq/stagehand-integrations
```

```bash
cd packages/integrations/crewai
uv sync --locked
```

```bash
export OPENAI_API_KEY="your-openai-api-key"
```

```bash
export STAGEHAND_BROWSER="browserbase"
export BROWSERBASE_API_KEY="your-browserbase-api-key"
```

```bash
uv run python agent.py \
  "Open https://example.com and report the page title."
```

--------------------------------

### Quick start: get context and create page

Source: https://docs.stagehand.dev/v4/reference/context

Quick start example for Python: gets the browser context and creates a new page. This is the initial setup for using the context API.

```python
context = browser.context
page = await context.new_page()
```

--------------------------------

### Quick start: create locator and click

Source: https://docs.stagehand.dev/v4/reference/locator

Quick start example showing how to create a locator and click the matched element.

```python
locator = page.locator("button[type=submit]")
await locator.click()
```

--------------------------------

### Quick start: create page and navigate

Source: https://docs.stagehand.dev/v4/reference/page

Quick start example: creates a new page in the browser context and navigates to a URL. The response from the navigation is stored in the variable.

```python
page = await browser.context.new_page()
response = await page.goto("https://example.com")
```

--------------------------------

### Clone and install Stagehand

Source: https://docs.stagehand.dev/v4/integrations/overview

Initial setup steps to clone the repository and install dependencies using pnpm.

```bash
git clone https://github.com/browserbase/stagehand.git
cd stagehand
pnpm install --frozen-lockfile
```

--------------------------------

### Go: Quick start - WriteText

Source: https://docs.stagehand.dev/v4/reference/clipboard

Quick start example for the Go clipboard API. It creates a clipboard instance and writes text. Every method takes a context.Context first; pass nil for options to use defaults.

```go
clipboard := browser.Context().Clipboard()
if err := clipboard.WriteText(ctx, "Hello", nil); err != nil {
    return err
}
```

--------------------------------

### Install OpenAI SDK (Go)

Source: https://docs.stagehand.dev/configuration/models

Installs the OpenAI Go SDK using go get.

```Go
go get github.com/openai/openai-go
```

--------------------------------

### Go quick start - Create context, page, and navigate

Source: https://docs.stagehand.dev/v4/reference/page

Quick start example for Go: creates a browser context, opens a new page, and navigates to example.com. Every method that talks to the browser takes a context.Context first and returns an error last; options are passed as pointer structs, pass nil for defaults.

```go
browserContext, err := browser.Context()
if err != nil {
    return err
}
page, err := browserContext.NewPage(ctx)
if err != nil {
    return err
}
if _, err := page.Goto(ctx, "https://example.com", nil); err != nil {
    return err
}
```

--------------------------------

### Install Bedrock SDK for Go

Source: https://docs.stagehand.dev/v4/configuration/models

Install the AWS Bedrock Runtime SDK for Go using go get.

```bash
go get github.com/aws/aws-sdk-go-v2/service/bedrockruntime
```

--------------------------------

### Quickstart: clone, configure, and run a browser task

Source: https://docs.stagehand.dev/v4/integrations/claude-code

Quickstart steps: clone and build Stagehand, set the Anthropic API key, choose the browser (Browserbase or local Chrome), and run a browser task. The example defaults to `claude-sonnet-5` unless `CLAUDE_STAGEHAND_MODEL` is set, and defaults to Browserbase when `BROWSERBASE_API_KEY` is set, otherwise local Chrome.

```bash
git clone https://github.com/browserbase/stagehand.git
cd stagehand
pnpm install --frozen-lockfile
pnpm exec turbo run build \
  --filter @browserbasehq/stagehand-integrations
```

```bash
export ANTHROPIC_API_KEY="your-anthropic-api-key"
```

```bash
export STAGEHAND_BROWSER="browserbase"
export BROWSERBASE_API_KEY="your-browserbase-api-key"
```

```bash
pnpm --dir packages/integrations/claude-code start -- \
  "Open https://example.com and report the page title."
```

--------------------------------

### Basic local setup with localBrowser (TypeScript, Python, Go)

Source: https://docs.stagehand.dev/configuration/browser

Launch a local browser and create a Stagehand instance. The TypeScript and Python examples use the localBrowser/local_browser launch function, while the Go example uses stagehand.LaunchLocalBrowser with error handling and a deferred close. These are the basic setup snippets for running Stagehand locally.

```TypeScript
import { localBrowser, Stagehand } from "@browserbasehq/stagehand";

const browser = await localBrowser.launch();
const stagehand = await Stagehand.create({ browser });

```

```Python
from stagehand import Stagehand, local_browser

browser = await local_browser.launch()
stagehand = await Stagehand.create(browser=browser)

```

```Go
browser, err := stagehand.LaunchLocalBrowser(ctx, &stagehand.LocalBrowserLaunchOptions{})
if err != nil {
	return err
}

client, err := stagehand.Create(ctx, stagehand.CreateOptions{
	Browser: browser,
})
if err != nil {
	return err
}
defer func() { err = errors.Join(err, client.Close(ctx)) }()

```

--------------------------------

### Run structured-output agents2.py example

Source: https://docs.stagehand.dev/v4/integrations/deep-agents

Runs the structured-output form-filling example that uses mock data and does not submit the form. Requires the same environment setup as the main agent.

```bash
uv run --project examples/local --locked \
  python examples/local/agents2.py
```

--------------------------------

### Run a browser task

Source: https://docs.stagehand.dev/v4/integrations/vercel-ai-sdk

Starts the Vercel AI SDK example agent with a prompt to open a URL and report the page title.

```bash
pnpm --dir packages/integrations/vercel-ai start -- \
  "Open https://example.com and report the page title."
```

--------------------------------

### Start Eve integration

Source: https://docs.stagehand.dev/v4/integrations/eve

Starts the Eve integration development server. Run this after building the Stagehand integrations package.

```bash
pnpm --dir packages/integrations/eve dev
```

--------------------------------

### Metrics() example

Source: https://docs.stagehand.dev/v4/reference/stagehand

Retrieves token usage and inference timing metrics for the session. Each Stagehand instance starts at zero; successful operations return Metadata.Usage, while deterministic actions and cache hits report zero-valued usage. Reading metrics does not reset them.

```go
metrics, err := client.Metrics(ctx)
if err != nil {
	return err
}
fmt.Println(metrics)
```

--------------------------------

### Get all pages in a browser context in Go

Source: https://docs.stagehand.dev/v4/reference/context

Returns every open page in the browser context. The first block shows the method signature; the second shows a usage example that prints the number of pages.

```go
func (c *BrowserContext) Pages(ctx context.Context) ([]*Page, error)
```

```go
pages, err := browserContext.Pages(ctx)
if err != nil {
    return err
}
fmt.Println(len(pages))
```

--------------------------------

### Example result in Go

Source: https://docs.stagehand.dev/v4/basics/extract

Shows the expected output of the extract call for the price example.

```Go
result := price{Price: 19.99}
fmt.Println(result.Price)
```

--------------------------------

### Install and authenticate fx

Source: https://docs.stagehand.dev/v4/integrations/fx

Installs fx v0.0.3 and authenticates. You can export AI_GATEWAY_API_KEY instead of using fx login.

```bash
curl -fsSL https://fx.sh/setup.sh | bash -s -- v0.0.3
fx login
```

--------------------------------

### Install OpenAI SDK (Python)

Source: https://docs.stagehand.dev/configuration/models

Installs the OpenAI SDK using pip.

```Python
pip install openai
```

--------------------------------

### Get the active page with activePage()

Source: https://docs.stagehand.dev/v4/reference/context

Returns the currently active page. The example shows how to get the first page from the pages list.

```typescript
const [page] = await browser.context.pages();
```

--------------------------------

### Example info-level log output

Source: https://docs.stagehand.dev/configuration/logging

Example log output when the logging level is set to info. It shows INFO records for action and extraction start and completion.

```plaintext
[stagehand] INFO act started {"category":"action"}
[stagehand] INFO act completed successfully {"category":"action"}
[stagehand] INFO extract started {"category":"extraction"}
[stagehand] INFO extract completed {"category":"extraction"}

```

--------------------------------

### Python Quick Start: Launch Browser and Create Stagehand

Source: https://docs.stagehand.dev/v4/reference/stagehand

Launches a local browser, creates a Stagehand instance, navigates to example.com, and closes both in a nested try/finally to ensure cleanup.

```python
from stagehand import Stagehand, local_browser

browser = await local_browser.launch()
try:
    stagehand = await Stagehand.create(browser=browser)
    try:
        page = await browser.context.active_page()
        await page.goto("https://example.com")
    finally:
        await stagehand.close()
finally:
    await browser.close()
```

--------------------------------

### Advanced Browserbase configuration example (Go)

Source: https://docs.stagehand.dev/configuration/browser

Launches a Browserbase browser with proxies, region, timeout, keepAlive, browser settings (verified, blockAds, solveCaptchas, recordSession, viewport), and user metadata. Note: verified is a Scale Plan feature and keepAlive is available on Startup plan.

```go
apiKey := os.Getenv("BROWSERBASE_API_KEY")
region := stagehand.BrowserbaseRegionUSWest2
proxies := stagehand.BrowserbaseProxyEnabled(true)
timeout := 3600.0 // 1 hour session timeout
keepAlive := true // Available on Startup plan

// verified is a Scale Plan feature: contact support@browserbase.com to enable
verified := false
blockAds := true
solveCaptchas := true
recordSession := false
width, height := 1920.0, 1080.0

browser, err := stagehand.LaunchBrowserbase(ctx, stagehand.BrowserbaseLaunchOptions{
	APIKey:    apiKey,
	Proxies:   &proxies,
	Region:    &region,
	Timeout:   &timeout,
	KeepAlive: &keepAlive,
	BrowserSettings: &stagehand.BrowserbaseBrowserSettings{
		Verified:      &verified,
		BlockAds:      &blockAds,
		SolveCaptchas: &solveCaptchas,
		RecordSession: &recordSession,
		Viewport:      &stagehand.BrowserbaseViewport{Width: &width, Height: &height},
	},
	UserMetadata: map[string]json.RawMessage{
		"userId":      json.RawMessage(`"automation-user-123"`),
		"environment": json.RawMessage(`"production"`),
	},
})
if err != nil {
	return err
}

client, err := stagehand.Create(ctx, stagehand.CreateOptions{
	Browser: browser,
})
if err != nil {
	return err
}

defer func() { err = errors.Join(err, client.Close(ctx)) }()

```

--------------------------------

### Create a sample project with Stagehand SDK

Source: https://docs.stagehand.dev/v4/first-steps/quickstart

Create a sample project and install the Stagehand SDK for TypeScript, Python, or Go. Each tab shows the commands for its language.

```bash
mkdir my-stagehand-app && cd my-stagehand-app
pnpm init -y
pnpm install @browserbasehq/stagehand zod
```

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

```bash
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
```

--------------------------------

### Basic setup with browserbase.launch()

Source: https://docs.stagehand.dev/configuration/browser

Basic setup for launching a browser with Browserbase using default settings. Requires a Browserbase API key set in the environment. The Stagehand client is created after launching the browser.

```typescript
import { browserbase, Stagehand } from "@browserbasehq/stagehand";

const browser = await browserbase.launch({
  apiKey: process.env.BROWSERBASE_API_KEY,
});
const stagehand = await Stagehand.create({ browser });

```

```python
import os

from stagehand import Stagehand, browserbase

browser = await browserbase.launch(
    api_key=os.environ["BROWSERBASE_API_KEY"],
)
stagehand = await Stagehand.create(browser=browser)

```

```go
apiKey := os.Getenv("BROWSERBASE_API_KEY")

browser, err := stagehand.LaunchBrowserbase(ctx, stagehand.BrowserbaseLaunchOptions{APIKey: apiKey})
if err != nil {
	return err
}

client, err := stagehand.Create(ctx, stagehand.CreateOptions{
	Browser: browser,
})
if err != nil {
	return err
}
defer func() { err = errors.Join(err, client.Close(ctx)) }()

```

--------------------------------

### Bash: Set Browserbase API key and run Go example

Source: https://docs.stagehand.dev/v4/first-steps/quickstart

Sets the Browserbase API key and runs the Go example script. Model Gateway selects and authenticates the model automatically, so no model provider key is required.

```bash
export BROWSERBASE_API_KEY="bb_live_..." # Your Browserbase API key
go run .                                 # Run the example script
```

--------------------------------

### Clone Stagehand and install Python projects

Source: https://docs.stagehand.dev/v4/integrations/deep-agents

Clones the Stagehand repository and installs Python dependencies for the local Deep Agents example using uv. Requires Python 3.11–3.13, uv, a provider credential, and Google Chrome.

```bash
git clone https://github.com/browserbase/stagehand.git
cd stagehand/packages/integrations/deepagents
uv sync --locked
uv sync --project examples/local --locked
```

--------------------------------

### Basic advanced configuration with browserbase.launch() (Go)

Source: https://docs.stagehand.dev/configuration/browser

Launches a Browserbase browser with proxies, region, and browser settings (viewport and blockAds). Uses os.Getenv for the API key and handles errors.

```go
apiKey := os.Getenv("BROWSERBASE_API_KEY")
region := stagehand.BrowserbaseRegionUSWest2
proxies := stagehand.BrowserbaseProxyEnabled(true)
blockAds := true
width, height := 1920.0, 1080.0

browser, err := stagehand.LaunchBrowserbase(ctx, stagehand.BrowserbaseLaunchOptions{
	APIKey:   apiKey,
	Proxies:  &proxies,
	Region:   &region,
	BrowserSettings: &stagehand.BrowserbaseBrowserSettings{
		Viewport: &stagehand.BrowserbaseViewport{Width: &width, Height: &height},
		BlockAds: &blockAds,
	},
})
if err != nil {
	return err
}

client, err := stagehand.Create(ctx, stagehand.CreateOptions{
	Browser: browser,
})
if err != nil {
	return err
}
defer func() { err = errors.Join(err, client.Close(ctx)) }()

```

--------------------------------

### Get page URL with page.URL(ctx)

Source: https://docs.stagehand.dev/v4/reference/page

Returns the current URL of the page. The example prints the URL or returns an error if the operation fails.

```go
url, err := page.URL(ctx)
    if err != nil {
        return err
    }
    fmt.Println(url)
```

--------------------------------

### Get page title with page.Title(ctx)

Source: https://docs.stagehand.dev/v4/reference/page

Returns the current document title of the page. The example prints the title or returns an error if the operation fails.

```go
title, err := page.Title(ctx)
    if err != nil {
        return err
    }
    fmt.Println(title)
```

--------------------------------

### Create and monitor a Browserbase session (Go)

Source: https://docs.stagehand.dev/configuration/observability

Go example using the stagehand package to connect to a Browserbase session and retrieve session metadata. Requires BROWSERBASE_API_KEY and a pre-created session ID.

```go
// Create the session with your Browserbase client of choice so you hold the
// session ID, then attach Stagehand to it.
session, err := createBrowserbaseSession(ctx)
if err != nil {
	return err
}

browser, err := stagehand.ConnectBrowserbase(ctx, stagehand.BrowserbaseConnectOptions{
	APIKey:    os.Getenv("BROWSERBASE_API_KEY"),
	SessionID: session.ID,
})
if err != nil {
	return err
}

client, err := stagehand.Create(ctx, stagehand.CreateOptions{
	Browser: browser,
})
if err != nil {
	return err
}
defer func() { err = errors.Join(err, client.Close(ctx)) }()

info, err := retrieveBrowserbaseSession(ctx, session.ID)
if err != nil {
	return err
}

fmt.Println("Session status:", info.Status)
fmt.Println("Session region:", info.Region)
fmt.Println("CPU usage:", info.AvgCPUUsage)
fmt.Println("Memory usage:", info.MemoryUsage)
fmt.Println("Proxy bytes:", info.ProxyBytes)

```

--------------------------------

### Monitor Stagehand metrics in TypeScript, Python, and Go

Source: https://docs.stagehand.dev/configuration/observability

Use these examples to monitor token usage, execution time, and inference time during Stagehand automation. The metrics are cumulative for the session, so subtract the baseline metrics to get tokens used in the current segment. The TypeScript and Python examples use the awaited metrics() method, while the Go example uses client.Metrics(ctx) and requires error handling.

```TypeScript
import { browserbase, Stagehand } from "@browserbasehq/stagehand";
import { z } from "zod/v4";

const UserSchema = z.object({ name: z.string(), email: z.string() });

const browser = await browserbase.launch({
  apiKey: process.env.BROWSERBASE_API_KEY,
});
const stagehand = await Stagehand.create({ browser });

// Metrics are fetched from the runtime, so the call is awaited
const metrics = await stagehand.metrics();
console.log(metrics);

// Monitor during automation
const startTime = Date.now();
const initialMetrics = await stagehand.metrics();

// ... perform automation tasks
const [page] = await browser.context.pages();
await page.goto("https://example.com");
await stagehand.act("click the login button");
const { data } = await stagehand.extract("extract user info", UserSchema);
console.log(`Extracted ${data.name} <${data.email}>`);

const finalMetrics = await stagehand.metrics();
const executionTime = Date.now() - startTime;

// Metrics are cumulative for the session, so subtract the baseline
const tokensUsed =
  finalMetrics.totalPromptTokens + finalMetrics.totalCompletionTokens -
  (initialMetrics.totalPromptTokens + initialMetrics.totalCompletionTokens);

console.log("Automation Summary:", {
  tokensUsed,
  executionTime: `${executionTime}ms`,
  avgInferenceTime: `${finalMetrics.totalInferenceTimeMs / 3}ms`,
});
```

```Python
import os
from time import perf_counter

from pydantic import BaseModel

from stagehand import Stagehand, browserbase

class User(BaseModel):
    name: str
    email: str

browser = await browserbase.launch(
    api_key=os.environ["BROWSERBASE_API_KEY"],
)
stagehand = await Stagehand.create(browser=browser)

# Metrics are fetched from the runtime, so the call is awaited
metrics = await stagehand.metrics()
print(metrics)

# Monitor during automation
start_time = perf_counter()
initial_metrics = await stagehand.metrics()

# ... perform automation tasks
page = (await browser.context.pages())[0]
await page.goto("https://example.com")
await stagehand.act("click the login button")
data = (await stagehand.extract("extract user info", User)).data
print(f"Extracted {data.name} <{data.email}>")

final_metrics = await stagehand.metrics()
execution_time = (perf_counter() - start_time) * 1000

# Metrics are cumulative for the session, so subtract the baseline
tokens_used = (
    final_metrics.total_prompt_tokens
    + final_metrics.total_completion_tokens
    - initial_metrics.total_prompt_tokens
    - initial_metrics.total_completion_tokens
)
print("Automation Summary:", {
    "tokens_used": tokens_used,
    "execution_time": f"{execution_time:.0f}ms",
    "avg_inference_time": f"{final_metrics.total_inference_time_ms / 3}ms",
})
```

```Go
type user struct {
	Name  string `json:"name"`
	Email string `json:"email"`
}


apiKey := os.Getenv("BROWSERBASE_API_KEY")
browser, err := stagehand.LaunchBrowserbase(ctx, stagehand.BrowserbaseLaunchOptions{APIKey: apiKey})
if err != nil {
	return err
}

client, err := stagehand.Create(ctx, stagehand.CreateOptions{
	Browser: browser,
})
if err != nil {
	return err
}
// Metrics are fetched from the runtime, so the call takes a context
metrics, err := client.Metrics(ctx)
if err != nil {
	return err
}
fmt.Printf("%+v\n", metrics)

// Monitor during automation
startTime := time.Now()
initialMetrics, err := client.Metrics(ctx)
if err != nil {
	return err
}

// ... perform automation tasks
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://example.com", nil); err != nil {
	return err
}
if _, err := client.Act(ctx, stagehand.ActInstruction("click the login button"), nil); err != nil {
	return err
}
extracted, err := stagehand.Extract[user](ctx, client, "extract user info", nil)
if err != nil {
	return err
}
fmt.Printf("Extracted %s <%s>\n", extracted.Data.Name, extracted.Data.Email)

finalMetrics, err := client.Metrics(ctx)
if err != nil {
	return err
}
executionTime := time.Since(startTime)

// Metrics are cumulative for the session, so subtract the baseline
tokensUsed := (finalMetrics.TotalPromptTokens + finalMetrics.TotalCompletionTokens) -
	(initialMetrics.TotalPromptTokens + initialMetrics.TotalCompletionTokens)

fmt.Printf(
	"Automation Summary: tokensUsed=%.0f executionTime=%dms avgInferenceTime=%.0fms\n",
	tokensUsed,
	executionTime.Milliseconds(),
	finalMetrics.TotalInferenceTimeMs/3,
)
```

--------------------------------

### Get WebMCP tools with Tools()

Source: https://docs.stagehand.dev/v4/reference/page

Return the WebMCP tools registered on the page by calling the Tools method. The example shows how to call it with nil options and handle errors.

```go
tools, err := page.Tools(ctx, nil)
if err != nil {
    return err
}
```

--------------------------------

### Launch Browserbase with API key (Go)

Source: https://docs.stagehand.dev/configuration/models

Initializes a Stagehand client using Browserbase with an API key from the environment. The client is closed with error joining on defer.

```go
apiKey := os.Getenv("BROWSERBASE_API_KEY")

browser, err := stagehand.LaunchBrowserbase(ctx, stagehand.BrowserbaseLaunchOptions{
	APIKey: apiKey,
})
if err != nil {
	return err
}

client, err := stagehand.Create(ctx, stagehand.CreateOptions{
	Browser:  browser,
	Generate: generateWithYourProvider,
})
if err != nil {
	return err
}
defer func() { err = errors.Join(err, client.Close(ctx)) }()
```

--------------------------------

### Observe candidate actions on the active page

Source: https://docs.stagehand.dev/v4/first-steps/ai-rules

Use stagehand.observe to get candidate actions for a given instruction. The example logs the selector, method, and arguments of the first action.

```typescript
// Get candidate actions on the current active page
const { data: actions } = await stagehand.observe("Click the sign in button");
const [action] = actions;

if (action) {
  console.log(action.selector, action.method, action.arguments);
}
```

--------------------------------

### Configure Stagehand logging with level, format, and onLog callback

Source: https://docs.stagehand.dev/configuration/logging

Configure Stagehand logging with a level, format, and optional callback. The TypeScript and Python examples define development, production, and testing configurations, then pass one to Stagehand.create(). The Go example includes environment-based selection and full client setup with error handling.

```TypeScript
import { localBrowser, Stagehand } from "@browserbasehq/stagehand";

// Development: full debug output, human-readable
const development = { level: "debug", format: "pretty" } as const;

// Production: standard logging, machine-readable, forwarded to your platform
const production = {
  level: "info",
  format: "json",
  onLog: yourProductionLogger, // Send to Sentry, DataDog, or similar
} as const;

// Testing: warnings and errors only, no console noise
const testing = { level: "warn", onLog: yourTestLogger } as const;

// Create one instance with the configuration for this environment
const stagehand = await Stagehand.create({
  browser: await localBrowser.launch(),
  logging: development,
  // restOfYourConfiguration...
});
```

```Python
from stagehand import Stagehand, local_browser

# Development: full debug output, human-readable
development = {"level": "debug", "format": "pretty"}

# Production: standard logging, machine-readable, forwarded to your platform
production = {
    "level": "info",
    "format": "json",
    "on_log": your_production_logger,  # Send to Sentry, DataDog, or similar
}

# Testing: warnings and errors only, no console noise
testing = {"level": "warn", "on_log": your_test_logger}

# Create one instance with the configuration for this environment
browser = await local_browser.launch()

stagehand = await Stagehand.create(
    browser=browser,
    logging=development,
    # rest_of_your_configuration...
)
```

```Go
// Development: full debug output, human-readable
development := &stagehand.StagehandClientLoggingConfig{
	Level:  stagehand.StagehandClientLogLevelDebug,
	Format: stagehand.StagehandClientLogFormatPretty,
}

// Production: standard logging, machine-readable, forwarded to your platform
production := &stagehand.StagehandClientLoggingConfig{
	Level:  stagehand.StagehandClientLogLevelInfo,
	Format: stagehand.StagehandClientLogFormatJSON,
	OnLog:  yourProductionLogger, // Send to Sentry, DataDog, or similar
}

// Testing: warnings and errors only, no console noise
testing := &stagehand.StagehandClientLoggingConfig{
	Level: stagehand.StagehandClientLogLevelWarn,
	OnLog: yourTestLogger,
}

// Pick the configuration that matches the environment you are running in
logging := development
switch os.Getenv("APP_ENV") {
case "production":
	logging = production
case "test":
	logging = testing
}

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,
	Logging: logging,
	// restOfYourConfiguration...
})
if err != nil {
	return err
}
defer func() { err = errors.Join(err, client.Close(ctx)) }()
```

--------------------------------

### Go Quick Start: Launch Local Browser and Create Stagehand

Source: https://docs.stagehand.dev/v4/reference/stagehand

Initializes a Stagehand instance with a local browser. The browser handle is created with `LaunchLocalBrowser`, then passed to `stagehand.Create`; both are deferred for cleanup. Every Stagehand call takes a `context.Context` as its first parameter and returns an `error` as its last result.

```go
package main

import (
	"context"
	"log"

	stagehand "github.com/browserbase/stagehand/packages/sdk-go/v4"
)

func main() {
	if err := run(context.Background()); err != nil {
		log.Fatal(err)
	}
}

func run(ctx context.Context) error {
	browser, err := stagehand.LaunchLocalBrowser(ctx, nil)
	if err != nil {
		return err
	}
	defer browser.Close(ctx)

	client, err := stagehand.Create(ctx, stagehand.CreateOptions{Browser: browser})
	if err != nil {
		return err
	}
	defer client.Close(ctx)

	return nil
}
```

--------------------------------

### Run fx from integration directory

Source: https://docs.stagehand.dev/v4/integrations/fx

Starts fx from the integration directory so it loads the included limits, project instructions, and Stagehand skill.

```bash
cd packages/integrations/fx
fx
```

--------------------------------

### Choose the browser

Source: https://docs.stagehand.dev/v4/integrations/mastra

By default, the example uses local Chrome. To use Browserbase instead, set STAGEHAND_BROWSER to 'browserbase' and provide your Browserbase API key.

```bash
export STAGEHAND_BROWSER="browserbase"
export BROWSERBASE_API_KEY="your-browserbase-api-key"
```

--------------------------------

### Create a new page and navigate to a URL

Source: https://docs.stagehand.dev/v4/reference/page

Creates a new page in the browser context and navigates to example.com. The goto method returns a Response object for the main document.

```typescript
const page = await browser.context.newPage();
const response = await page.goto("https://example.com");
```

--------------------------------

### Test locally with Vercel dev server

Source: https://docs.stagehand.dev/v4/best-practices/deployments

Commands to test the Vercel Function locally before deploying. Run from the project root. Each variant installs dependencies for the respective language and starts the local Vercel dev server on port 5005.

```bash
# ensure dependencies are installed
pnpm install

# start the local Vercel dev server
vercel dev --listen 5005
```

```bash
# ensure dependencies are installed
pip install -r requirements.txt

# start the local Vercel dev server
vercel dev --listen 5005
```

```bash
# ensure dependencies are installed
go mod tidy

# start the local Vercel dev server
vercel dev --listen 5005
```

--------------------------------

### Get the active page in a browser context in Go

Source: https://docs.stagehand.dev/v4/reference/context

Returns the active page in the browser context. The first block shows the method signature; the second shows a usage example that checks for errors. Returns nil when no page is active.

```go
func (c *BrowserContext) ActivePage(ctx context.Context) (*Page, error)
```

```go
if err := browserContext.ActivePage(ctx); err != nil {
    return err
}
```

--------------------------------

### Advanced Browserbase configuration example (Python)

Source: https://docs.stagehand.dev/configuration/browser

Launches a Browserbase browser with proxies, region, timeout, keep_alive, browser settings (verified, block_ads, solve_captchas, record_session, viewport), and user_metadata. Note: verified is a Scale Plan feature and keep_alive is available on Startup plan.

```python
browser = await browserbase.launch(
    api_key=os.environ["BROWSERBASE_API_KEY"],
    proxies=True,
    region="us-west-2",
    timeout=3600,  # 1 hour session timeout
    keep_alive=True,  # Available on Startup plan
    browser_settings=BrowserbaseBrowserSettings.model_validate({
        # verified is a Scale Plan feature: contact support@browserbase.com to enable
        "verified": False,
        "block_ads": True,
        "solve_captchas": True,
        "record_session": False,
        "viewport": {"width": 1920, "height": 1080},
    }),
    user_metadata={
        "user_id": "automation-user-123",
        "environment": "production",
    },
)

stagehand = await Stagehand.create(browser=browser)

```

--------------------------------

### Replay observed actions with observe() and act()

Source: https://docs.stagehand.dev/v4/basics/act

Use observe() to get candidate actions, then pass the returned action directly to act() to replay it without model inference. The TypeScript, Python, and Go examples show the same pattern for each language.

```typescript
const { data: actions } = await stagehand.observe("click the login button");
const [action] = actions;

if (action?.method === "click") {
  // No inference: Stagehand replays the observed action
  await stagehand.act(action);
}
```

```python
result = await stagehand.observe("click the login button")

if result.data and result.data[0].method == "click":
    # No inference: Stagehand replays the observed action
    await stagehand.act(result.data[0])
```

```go
instruction := "click the login button"
observed, err := client.Observe(ctx, &instruction, nil)
if err != nil {
	return err
}

if len(observed.Data) > 0 && observed.Data[0].Method != nil && *observed.Data[0].Method == "click" {
	// No inference: Stagehand replays the observed action
	if _, err := client.Act(ctx, stagehand.ObservedAction(observed.Data[0]), nil); err != nil {
		return err
	}
}
```

--------------------------------

### Bash: Set Browserbase API key and run Python example

Source: https://docs.stagehand.dev/v4/first-steps/quickstart

Sets the Browserbase API key and runs the Python example script. Model Gateway selects and authenticates the model automatically, so no model provider key is required.

```bash
export BROWSERBASE_API_KEY="bb_live_..." # Your Browserbase API key
python main.py                           # Run the example script
```

--------------------------------

### Python create() Example

Source: https://docs.stagehand.dev/v4/reference/stagehand

Shows the minimal usage of Stagehand.create() to initialize a Stagehand instance with a launched browser. The returned instance is already initialized.

```python
browser = await local_browser.launch()
stagehand = await Stagehand.create(browser=browser)
```

--------------------------------

### Basic advanced configuration with browserbase.launch() (Python)

Source: https://docs.stagehand.dev/configuration/browser

Launches a Browserbase browser with proxies, region, and browser settings (viewport and blockAds). Uses os.environ for the API key.

```python
import os

from stagehand import BrowserbaseBrowserSettings, Stagehand, browserbase

browser = await browserbase.launch(
    api_key=os.environ["BROWSERBASE_API_KEY"],
    proxies=True,
    region="us-west-2",
    browser_settings=BrowserbaseBrowserSettings.model_validate({
        "viewport": {"width": 1920, "height": 1080},
        "block_ads": True,
    }),
)
stagehand = await Stagehand.create(browser=browser)

```

--------------------------------

### List and invoke page tools with page.tools() in Python

Source: https://docs.stagehand.dev/v4/basics/webmcp

Use page.tools() to get the tools registered by the current page. The example selects the first tool (checkout) and invokes it with input quantity 2, then awaits the result and prints the status and output.

```python
tools = await page.tools()
checkout = tools[0]

invocation = await checkout.invoke(input={"quantity": 2})
response = await invocation.result()

print(response.status, response.output)
```

--------------------------------

### List and invoke page tools with page.tools() in TypeScript

Source: https://docs.stagehand.dev/v4/basics/webmcp

Use page.tools() to get the tools registered by the current page. The example selects the first tool (checkout) and invokes it with input quantity 2, then awaits the result and logs the status and output.

```typescript
const tools = await page.tools();
const [checkout] = tools;

const invocation = await checkout.invoke({ input: { quantity: 2 } });
const response = await invocation.result();

console.log(response.status, response.output);
```

--------------------------------

### Create Go project structure

Source: https://docs.stagehand.dev/v4/best-practices/deployments

Create the directory structure and files for a Go Vercel function, and initialize the Go module.

```bash
mkdir -p api
touch api/run.go vercel.json
go mod init example.com/bb-stagehand-on-vercel
```

--------------------------------

### Use Playwright-style page APIs in TypeScript, Python, and Go

Source: https://docs.stagehand.dev/

Shows deterministic Playwright-style page methods (goto, locator, fill, keyPress/key_press, screenshot) in TypeScript, Python, and Go. The Go example assumes page comes from the quickstart (pages[0]).

```typescript
const page = await stagehand.browser.context.activePage();

await page.goto("https://example.com");
await page.locator('textarea[name="q"]').fill("Browserbase");
await page.keyPress("Enter");
await page.screenshot();
```

```python
page = await stagehand.browser.context.active_page()

await page.goto("https://example.com")
await page.locator('textarea[name="q"]').fill("Browserbase")
await page.key_press("Enter")
await page.screenshot()
```

```go
// page comes from the quickstart (pages[0])

if _, err := page.Goto(ctx, "https://example.com", nil); err != nil {
	return err
}
if err := page.Locator(`textarea[name="q"]`).Fill(ctx, "Browserbase"); err != nil {
	return err
}
if err := page.KeyPress(ctx, "Enter", nil); err != nil {
	return err
}
if _, err := page.Screenshot(ctx, nil); err != nil {
	return err
}
```

--------------------------------

### Create and monitor a Browserbase session (Python)

Source: https://docs.stagehand.dev/configuration/observability

Equivalent Python example using the browserbase and stagehand packages. Creates a session, connects Stagehand, and prints session metadata. Requires BROWSERBASE_API_KEY and BROWSERBASE_PROJECT_ID environment variables.

```python
import os

from browserbase import Browserbase

from stagehand import Stagehand
from stagehand import browserbase as stagehand_browserbase

bb = Browserbase(api_key=os.environ["BROWSERBASE_API_KEY"])

# Create the session yourself so you hold the session ID
session = bb.sessions.create(
    project_id=os.environ["BROWSERBASE_PROJECT_ID"],
)

browser = await stagehand_browserbase.connect(
    api_key=os.environ["BROWSERBASE_API_KEY"],
    session_id=session.id,
)
stagehand = await Stagehand.create(browser=browser)

session_info = bb.sessions.retrieve(session.id)

print("Session status:", session_info.status)
print("Session region:", session_info.region)
print("CPU usage:", session_info.avg_cpu_usage)
print("Memory usage:", session_info.memory_usage)
print("Proxy bytes:", session_info.proxy_bytes)

```
Tokens:
Raw