Stagehand

https://docs.stagehand.dev/v2
Admin
Stagehand is a browser automation framework that combines AI with code to reliably automate web...
Tokens:84,244
Snippets:675
Trust Score:8.3
Update:7 months ago
Show doc for...
Tokens:
Raw
### Run Stagehand Example Script

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

Commands to navigate into the created Stagehand project directory, set up environment variables by copying the example .env file, and start the example script using npm. This process requires the user to add API keys to the .env file.

```bash
cd my-stagehand-app
cp .env.example .env
npm start
```

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

### Stagehand TypeScript Example Script

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

An example TypeScript script demonstrating the core Stagehand functionalities: initializing Stagehand, navigating to a URL, extracting data, performing an action (clicking), observing elements, and interacting with an agent. It requires environment variables for API keys to be set in a .env file.

```typescript
import "dotenv/config";
import { Stagehand } from "@browserbasehq/stagehand";

async function main() {
  const stagehand = new Stagehand({
    env: "BROWSERBASE"
  });

  await stagehand.init();

  console.log(`Stagehand Session Started`);
  console.log(`Watch live: https://browserbase.com/sessions/${stagehand.browserbaseSessionID}`);

  const page = stagehand.page;

  await page.goto("https://stagehand.dev");

  const extractResult = await page.extract("Extract the value proposition from the page.");
  console.log(`Extract result:\n`, extractResult);

  const actResult = await page.act("Click the 'Evals' button.");
  console.log(`Act result:\n`, actResult);

  const observeResult = await page.observe("What can I click on this page?");
  console.log(`Observe result:\n`, observeResult);

  const agent = await stagehand.agent({
    instructions: "You're a helpful assistant that can control a web browser.",
  });

  const agentResult = await agent.execute("What is the most accurate model to use in Stagehand?");
  console.log(`Agent result:\n`, agentResult);

  await stagehand.close();
}

main().catch((err) => {
  console.error(err);
  process.exit(1);
});

```

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

### Stagehand Basic Usage (TypeScript)

Source: https://docs.stagehand.dev/v2/first-steps/installation

Demonstrates initializing Stagehand, navigating to a URL, performing an action ('Click the sign in button'), and extracting structured data (page title) using Zod schemas. Requires Node.js and Playwright browsers installed locally if not using cloud sessions.

```typescript
import "dotenv/config";
import { Stagehand } from "@browserbasehq/stagehand";
import { z } from "zod/v3";

async function main() {
  const stagehand = new Stagehand({
    env: "BROWSERBASE"
  });

  await stagehand.init();
  const page = stagehand.page;

  await page.goto("https://example.com");
  
  // Act on the page
  await page.act("Click the sign in button");
  
  // Extract structured data
  const { title } = await page.extract({
    instruction: "extract the page title",
    schema: z.object({
      title: z.string(),
    }),
  });

  console.log(title);
  await stagehand.close();
}

main().catch((err) => {
  console.error(err);
  process.exit(1);
});
```

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

### Create Stagehand Project with CLI

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

Scaffolds a new Stagehand project using npx. This command initializes a ready-to-run Stagehand application with default configurations and an example script. No specific inputs are required, and it outputs a new project directory.

```bash
npx create-browser-app
```

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

### Browserbase MCP Server Configuration Examples (JSON)

Source: https://docs.stagehand.dev/v2/integrations/mcp/configuration

Configuration examples for the Browserbase MCP server using JSON format. These examples demonstrate how to set up remote URLs, use the NPM package, and configure local STDIO or SHTTP connections.

```json
{
  "mcpServers": {
    "browserbase": {
      "url": "your-smithery-url.com"
    }
  }
}
```

```json
{
  "mcpServers": {
    "browserbase": {
      "command": "npx",
      "args": ["@browserbasehq/mcp-server-browserbase"],
      "env": {
        "BROWSERBASE_API_KEY": "your_api_key",
        "BROWSERBASE_PROJECT_ID": "your_project_id",
        "GEMINI_API_KEY": "your_gemini_api_key"
      }
    }
  }
}
```

```json
{
  "mcpServers": {
    "browserbase": {
      "command": "node",
      "args": ["/path/to/mcp-server-browserbase/cli.js"],
      "env": {
        "BROWSERBASE_API_KEY": "your_api_key",
        "BROWSERBASE_PROJECT_ID": "your_project_id",
        "GEMINI_API_KEY": "your_gemini_api_key"
      }
    }
  }
}
```

```json
{
  "mcpServers": {
    "browserbase": {
      "url": "http://localhost:8931/mcp",
      "env": {
        "BROWSERBASE_API_KEY": "your_api_key",
        "BROWSERBASE_PROJECT_ID": "your_project_id",
        "GEMINI_API_KEY": "your_gemini_api_key"
      }
    }
  }
}
```

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

### Stagehand Basic Usage (Python)

Source: https://docs.stagehand.dev/v2/first-steps/installation

Shows how to initialize Stagehand in Python, navigate to a URL, perform an action, and extract structured data using a dictionary-based schema. Requires Python 3.9+ and environment variables for API keys.

```python
import os
import asyncio
from stagehand import Stagehand

async def main():
    stagehand = Stagehand(
        env="BROWSERBASE",
        model_api_key=os.getenv("MODEL_API_KEY")
    )
    await stagehand.init()
    page = stagehand.page
    
    await page.goto("https://example.com")
    
    # Act on the page
    await page.act("Click the sign in button")
    
    # Extract structured data
    result = await page.extract({
        "instruction": "extract the page title",
        "schema": {
            "title": {
                "type": "string"
            }
        }
    })
    
    print(result["title"])
    await stagehand.close()

if __name__ == "__main__":
    asyncio.run(main())
```

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

### Example Replay Script for Stock Price Query (TypeScript)

Source: https://docs.stagehand.dev/v2/best-practices/build-agent

An example of a generated Stagehand script file ('replay.ts') that replays agent actions for a specific query, such as getting a stock price. It demonstrates how to use Playwright actions directly and includes fallback to Stagehand AI for self-healing if Playwright actions fail. Imports necessary types from '@browserbasehq/stagehand'.

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

export async function main({
  page,
  context,
  stagehand,
}: {
  page: Page; // Playwright Page with act, extract, and observe methods
  context: BrowserContext; // Playwright BrowserContext
  stagehand: Stagehand; // Stagehand instance
}) {
  await page.goto("https://www.google.com");

  // Replay will default to Playwright first to avoid unnecessary LLM calls!
  // If the Playwright action fails, Stagehand AI will take over and self-heal
  await page.act({
    description: "The search combobox where users can type their queries.",
    method: "fill",
    arguments: ["NVDA stock price"],
    selector:
      "xpath=/html/body[1]/div[1]/div[3]/form[1]/div[1]/div[1]/div[1]/div[1]/div[2]/textarea[1]",
  });
  await page.extract(
    "the displayed NVDA stock price in the search suggestions",
  );
  await stagehand.close();
}
```

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

### Install Browserbase NPM Package for Local STDIO (JSON)

Source: https://docs.stagehand.dev/v2/integrations/mcp/setup

Configure your MCP client to use the Browserbase server installed locally as an NPM package. This method uses STDIO for communication and requires API keys and project ID to be set as environment variables.

```json
{
  "mcpServers": {
    "browserbase": {
      "command": "npx",
      "args": ["@browserbasehq/mcp-server-browserbase"],
      "env": {
        "BROWSERBASE_API_KEY": "your_api_key",
        "BROWSERBASE_PROJECT_ID": "your_project_id",
        "GEMINI_API_KEY": "your_gemini_api_key"
      }
    }
  }
}
```

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

### Start Local SHTTP Server (Bash)

Source: https://docs.stagehand.dev/v2/integrations/mcp/configuration

Command to start the local Browserbase MCP server using SHTTP. This command listens on port 8931 for incoming connections.

```bash
# Start server
node cli.js --port 8931
```

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

### Local Development: Run Browserbase via SHTTP (Bash)

Source: https://docs.stagehand.dev/v2/integrations/mcp/setup

Steps to run the Browserbase MCP server locally using Streamable HTTP (SHTTP) transport. This involves starting the server on a specific port.

```bash
node cli.js --port 8931
```

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

### Install Vercel CLI

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

Commands to install the Vercel Command Line Interface (CLI) globally using different package managers like pnpm, yarn, npm, and bun.

```bash
pnpm i -g vercel
```

```bash
yarn global add vercel
```

```bash
npm i -g vercel
```

```bash
bun add -g vercel
```

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

### Verify Stagehand CLI Installation

Source: https://docs.stagehand.dev/v2/configuration/evals

Verifies that the Stagehand Evals CLI has been successfully installed and is accessible. Running 'evals help' should display the available commands and options.

```bash
evals help
```

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

### Implement Smart Caching in TypeScript and Python

Source: https://docs.stagehand.dev/v2/best-practices/cost-optimization

Cache successful actions to avoid repeated LLM calls and reduce costs. This example demonstrates caching an action to sign in and reusing it if available, otherwise performing the action.

```typescript
const [action] = await page.observe("Click the sign in button");
await setCache("sign_in_button", action);

const cachedAction = await getCache("sign_in_button");
if (cachedAction) {
  await page.act(cachedAction);
} else {
  await page.act(action);
}
```

```python
actions = await page.observe("Click the sign in button")
action = actions[0]
await set_cache("sign_in_button", action)

cached_action = await get_cache("sign_in_button")
if cached_action:
    await page.act(cached_action)
else:
    await page.act(action)
```

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

### Install Stagehand CLI Dependencies

Source: https://docs.stagehand.dev/v2/configuration/evals

Installs the necessary dependencies for the Stagehand CLI from the project's root directory. This is a prerequisite for building and using the CLI.

```bash
# From the stagehand root directory
pnpm install
```

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

### Install Stagehand Dependencies (TypeScript)

Source: https://docs.stagehand.dev/v2/first-steps/installation

Installs the necessary Stagehand, Playwright, and Zod packages for TypeScript projects using npm, pnpm, or yarn. Ensure Node.js is used for runtime.

```bash
npm install @browserbasehq/stagehand playwright zod
```

```bash
pnpm add @browserbasehq/stagehand playwright zod
```

```bash
yarn add @browserbasehq/stagehand playwright zod
```

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

### Example of Good Agent Instructions (TypeScript)

Source: https://docs.stagehand.dev/v2/best-practices/mcp-integrations

This TypeScript code snippet provides an example of well-written agent instructions for Stagehand. It clearly outlines the available tools (web search, database, browser automation) and provides guidance on when to use them, emphasizing the importance of searching for current information before making decisions and storing important data.

```typescript
instructions: `You have access to:
1. Web search tools - Use to find current information
2. Database tools - Use to store/retrieve data
3. Browser automation - Use for web interactions

Always search for current information before making decisions.
Store important data for later reference.`
```

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

### Local Development: Run Browserbase via STDIO (Bash)

Source: https://docs.stagehand.dev/v2/integrations/mcp/setup

Steps to clone, build, and run the Browserbase MCP server locally for development using STDIO transport. This involves cloning the repository, installing dependencies, building the project, and configuring the MCP client.

```bash
# Clone the Repo
git clone https://github.com/browserbase/mcp-server-browserbase.git
cd mcp-server-browserbase

# Install the dependencies and build the project
npm install && npm run build
```

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

### Agent Best Practices Examples (TypeScript)

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

Illustrates best practices for using Stagehand agents, emphasizing specific instructions over vague ones. This helps ensure predictable and accurate task execution.

```typescript
// Good: Specific instructions
await agent.execute("Navigate to products page and filter by 'Electronics'");

// Avoid: Vague instructions  
await agent.execute("Do some stuff on this page");
```

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

### Stagehand Primitives: TypeScript and Python Examples

Source: https://docs.stagehand.dev/v2/first-steps/introduction

Demonstrates the core Stagehand primitives (Act, Extract, Observe, Agent) in both TypeScript and Python. These examples showcase how to execute natural language actions, pull structured data, discover available page actions, and automate workflows autonomously. Ensure necessary libraries and API keys are configured.

```typescript
import { z } from "zod";
import stagehand from "stagehand";

// Act - Execute natural language actions
await page.act("click the login button");

// Extract - Pull structured data
const { price } = await page.extract({
  schema: z.object({ price: z.number() })
});

// Observe - Discover available actions
const actions = await page.observe("find submit buttons");

// Agent - Automate entire workflows
const agent = stagehand.agent({
    provider: "anthropic",
    model: "claude-sonnet-4-20250514",
    options: {
      apiKey: process.env.ANTHROPIC_API_KEY,
    },
});
await agent.execute("apply for this job");
```

```python
# Act - Execute natural language actions
await page.act("click the login button")

# Extract - Pull structured data
result = await page.extract(
  schema={"price": float}
)

# Observe - Discover available actions
actions = await page.observe("find submit buttons")

# Agent - Automate entire workflows
await agent.execute("apply for this job")
```

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

### Agent Navigation Commands in Python

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

Demonstrates effective and ineffective ways to instruct an agent for navigation and data extraction. The 'good' example provides specific instructions, while the 'avoid' example is too vague. This function relies on an 'agent' object with an 'execute' method.

```python
# Good: Specific instructions
await agent.execute("Navigate to products page and filter by 'Electronics'")

# Avoid: Vague instructions
await agent.execute("Do some stuff on this page")
```

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

### Example Act() Response

Source: https://docs.stagehand.dev/v2/references/act

Provides an example of the expected JSON response structure when the act() method is called successfully. This includes the success status, a message detailing the outcome, and the action performed.

```json
{
  success: true,
  message: 'Action [scrollTo] performed successfully on selector: /html[1]',
  action: 'Scrollable area of the page where user can navigate to the pricing section or other parts of the page'
}
```

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

### Install Vercel AI SDK Packages (Bash)

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

Installs the necessary Vercel AI SDK packages for integrating with LLMs, specifically including the Amazon Bedrock provider. This command is for package managers like npm, pnpm, or yarn.

```bash
npm install ai @ai-sdk/amazon-bedrock
```

```bash
pnpm install ai @ai-sdk/amazon-bedrock
```

```bash
yarn add ai @ai-sdk/amazon-bedrock
```

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

### Plan Actions with Observe (Python)

Source: https://docs.stagehand.dev/v2/best-practices/speed-optimization

Use a single observe() call to plan multiple actions, then execute them efficiently. This avoids multiple LLM calls and is 2-3x faster than direct act() calls for multi-step workflows.

```python
import asyncio

# Instead of sequential operations with multiple LLM calls
await page.act("Fill name field")        # LLM call #1
await page.act("Fill email field")       # LLM call #2  
await page.act("Select country dropdown") # LLM call #3

# Use single observe to plan all form fields - one LLM call
form_fields = await page.observe("Find all form fields to fill")

# Execute all actions without LLM inference
for field in form_fields:
    await page.act(field) # No LLM calls!
```

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

### Precise Element Targeting in Python

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

This Python example illustrates how to refine element selection by adding specific contextual details to instructions or by utilizing the `observe` function to verify the intended element before executing an action. This prevents actions from being performed on incorrect elements.

```python
# More precise element targeting
# Instead of:
# await page.act("click the button")

# Use specific context:
# await page.act("click the red 'Delete' button next to the user John Smith")

# Or preview with observe first:
results = await page.observe("click the submit button in the checkout form")
if results and "checkout" in results[0].description:
    await page.act(results[0])
```

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

### Define Product and E-commerce Schemas

Source: https://docs.stagehand.dev/v2/references/extract

Demonstrates defining data schemas with descriptions and validation rules. Includes examples for product details and nested e-commerce structures.

```typescript
import { z } from 'zod';

// Schema with descriptions and validation
const ProductSchema = z.object({
  price: z.number().describe("Product price in USD"),
  rating: z.number().min(0).max(5).describe("Customer rating out of 5"),
  available: z.boolean().describe("Whether product is in stock"),
  tags: z.array(z.string()).optional()
});

// Nested schema
const EcommerceSchema = z.object({
  product: z.object({
    name: z.string(),
    price: z.object({
      current: z.number(),
      original: z.number().optional()
    })
  }),
  reviews: z.array(z.object({
    rating: z.number(),
    comment: z.string()
  }))
});
```

```python
from pydantic import BaseModel, Field
from typing import Optional, List

# Schema with descriptions and validation
class Product(BaseModel):
    price: float = Field(description="Product price in USD")
    rating: float = Field(ge=0, le=5, description="Customer rating out of 5")
    available: bool = Field(description="Whether product is in stock")
    tags: Optional[List[str]] = None

# Nested schema
class Price(BaseModel):
    current: float
    original: Optional[float] = None

class Review(BaseModel):
    rating: int
    comment: str

class ProductDetails(BaseModel):
    name: str
    price: Price

class EcommerceData(BaseModel):
    product: ProductDetails
    reviews: List[Review]
```

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

### Agent Execution: Set Appropriate Step Limits in TypeScript and Python

Source: https://docs.stagehand.dev/v2/best-practices/prompting-best-practices

Guides on setting `maxSteps` for `agent.execute` based on task complexity. Simple tasks require fewer steps, while complex ones need more.

```typescript
// Simple task - fewer steps
await agent.execute({
  instruction: "Subscribe to the newsletter with email 'user@example.com'",
  maxSteps: 10
});

// Complex task - more steps  
await agent.execute({
  instruction: "Research and compare 5 project management tools with pricing and features",
  maxSteps: 50
});
```

```python
# Simple task - fewer steps
await agent.execute(
  instruction="Subscribe to the newsletter with email 'user@example.com'",
  max_steps=10
)

# Complex task - more steps
await agent.execute(
  instruction="Research and compare 5 project management tools with pricing and features",
  max_steps=50
)
```

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

### Run External Benchmarks with Stagehand CLI

Source: https://docs.stagehand.dev/v2/configuration/evals

Examples of running different industry-standard benchmarks using the Stagehand CLI. Supports filtering by various criteria like difficulty, category, level, and source. The CLI allows specifying the number of trials and concurrency.

```bash
# WebBench with filters
evals run benchmark:webbench -l 10 -f difficulty=easy -f category=READ

# GAIA benchmark
evals run b:gaia -s 100 -l 25 -f level=1

# WebVoyager
evals run b:webvoyager -l 50

# OnlineMind2Web
evals run b:onlineMind2Web

# OSWorld
evals run b:osworld -f source=Mind2Web
```

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

### Install Stagehand Dependencies (Python)

Source: https://docs.stagehand.dev/v2/first-steps/installation

Installs the Stagehand Python package using either uv or pip. Python 3.9+ is required, and uv is recommended for virtual environment management.

```bash
uv add stagehand
```

```bash
pip install stagehand
```

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

### Configure Stagehand Environment Variables (Bash)

Source: https://docs.stagehand.dev/v2/first-steps/installation

Sets up essential environment variables for Stagehand, including API keys for OpenAI and Browserbase, and the Browserbase Project ID. These can be set directly or via a .env file.

```bash
OPENAI_API_KEY=your_api_key
BROWSERBASE_API_KEY=your_api_key
BROWSERBASE_PROJECT_ID=your_project_id
```

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

### Local Development: Configure Browserbase via STDIO (JSON)

Source: https://docs.stagehand.dev/v2/integrations/mcp/setup

Configure your MCP client to use a locally developed Browserbase server running via STDIO. This requires specifying the command to execute the local server and setting necessary environment variables.

```json
{
  "mcpServers": {
    "browserbase": {
      "command": "node",
      "args": ["/path/to/mcp-server-browserbase/cli.js"],
      "env": {
        "BROWSERBASE_API_KEY": "your_api_key",
        "BROWSERBASE_PROJECT_ID": "your_project_id",
        "GEMINI_API_KEY": "your_gemini_api_key"
      }
    }
  }
}
```

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

### Local Development: Configure Browserbase via SHTTP (JSON)

Source: https://docs.stagehand.dev/v2/integrations/mcp/setup

Configure your MCP client to connect to a locally developed Browserbase server running via SHTTP. This requires specifying the local server URL and setting necessary environment variables.

```json
{
  "mcpServers": {
    "browserbase": {
      "url": "http://localhost:8931/mcp",
      "env": {
        "BROWSERBASE_API_KEY": "your_api_key",
        "BROWSERBASE_PROJECT_ID": "your_project_id",
        "GEMINI_API_KEY": "your_gemini_api_key"
      }
    }
  }
}
```

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

### Optimize Browser Sessions with Timeouts and Keep-Alive in TypeScript and Python

Source: https://docs.stagehand.dev/v2/best-practices/cost-optimization

Configure browser sessions to optimize costs by setting appropriate timeouts and enabling keep-alive. This example shows how to set a 30-minute timeout and keep sessions alive between tasks.

```typescript
const stagehand = new Stagehand({
  env: "BROWSERBASE",
  browserbaseSessionCreateParams: {
    timeout: 1800, // 30 minutes instead of default 1 hour
    keepAlive: true, // Keep session alive between tasks
  }
});
```

```python
stagehand = Stagehand(
    env="BROWSERBASE",
    browserbase_session_create_params={
        "timeout": 1800,  # 30 minutes instead of default 1 hour
        "keep_alive": True,  # Keep session alive between tasks
    }
)
```

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

### Create Project Structure

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

Shell commands to create the necessary directory and file structure for a Stagehand deployment on Vercel.

```bash
mkdir -p api
touch api/run.ts package.json vercel.json tsconfig.json
```

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

### Observe Elements Before Acting (Python)

Source: https://docs.stagehand.dev/v2/best-practices/prompting-best-practices

Shows how to use the `observe()` method in Python to find actionable elements prior to executing an action. It includes a check for element existence to avoid potential errors, then proceeds to act on the first discovered element.

```python
# Check for elements first
login_buttons = await page.observe("Find the login button")

if len(login_buttons) > 0:
    await page.act(login_buttons[0])
else:
    print("No login button found")
```

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

### Initialize Stagehand with Async Context Manager or Manual Setup (Python)

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

Demonstrates how to initialize the Stagehand object using an asynchronous context manager for automatic resource management or through manual initialization and closing. It requires importing necessary libraries and setting up configuration with environment variables.

```python
from stagehand import Stagehand, StagehandConfig
import asyncio
import os
from dotenv import load_dotenv

load_dotenv()

async def main():
    config = StagehandConfig(
        env="BROWSERBASE",  # or "LOCAL"
        api_key=os.getenv("BROWSERBASE_API_KEY"),
        project_id=os.getenv("BROWSERBASE_PROJECT_ID"),
        model_name="google/gemini-2.5-flash-preview-05-20",
        model_api_key=os.getenv("MODEL_API_KEY"),
    )
    
    # Recommended: Use as async context manager
    async with Stagehand(config) as stagehand:
        page = stagehand.page
        # Your automation code here
        
    # Alternative: Manual initialization
    stagehand = Stagehand(config)
    await stagehand.init()
    page = stagehand.page
    # Your automation code here
    await stagehand.close()

if __name__ == "__main__":
    asyncio.run(main())
```

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

### AgentResult Example Response (JSON)

Source: https://docs.stagehand.dev/v2/references/agent

An example of a JSON response conforming to the AgentResult interface. This demonstrates a successful task completion with details on actions performed, metadata, and token usage.

```json
{
  "success": true,
  "message": "Task completed successfully",
  "actions": [
    {
      "action": "click",
      "selector": "button.primary",
      "text": "Submit"
    }
  ],
  "completed": true,
  "metadata": {
    "execution_time": 1000
  },
  "usage": {
    "input_tokens": 100,
    "output_tokens": 50,
    "reasoning_tokens": 12,
    "cached_input_tokens": 0,
    "inference_time_ms": 100
  }
}
```

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

### Install Stagehand and LangChain JS Dependencies

Source: https://docs.stagehand.dev/v2/integrations/langchain/configuration

Installs the necessary npm packages for integrating Stagehand with LangChain JS. This includes core LangChain libraries and the Stagehand package.

```bash
npm install @langchain/langgraph @langchain/community @langchain/core @browserbasehq/stagehand
```

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

### Install CrewAI and Stagehand Dependencies

Source: https://docs.stagehand.dev/v2/integrations/crew-ai/configuration

Installs the necessary Python packages for CrewAI and Stagehand integration. This includes the core CrewAI library, its tools, and the Stagehand Python package.

```bash
pip install stagehand-py crewai crewai-tools
```

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

### Extract Product Data with Descriptive Schemas (Python)

Source: https://docs.stagehand.dev/v2/best-practices/prompting-best-practices

Illustrates extracting product information using descriptive field names, correct types, and helpful descriptions in Python. This method enhances data extraction accuracy by providing clear context for the agent, unlike generic field definitions.

```python
from pydantic import BaseModel, Field

# Good - Descriptive names, correct types, and helpful descriptions
class ProductData(BaseModel):
    productTitle: str = Field(description="The main product name displayed on the page")
    priceInDollars: float = Field(description="Current selling price as a number, without currency symbol")
    isInStock: bool = Field(description="Whether the product is available for purchase")

productData = await page.extract(
  "Extract product information",
  schema=ProductData
)

# Bad - Generic names, wrong types, no descriptions
class Data(BaseModel):
    name: str      # Too generic, no context
    price: str     # Should be float, no context
    stock: str     # Should be bool, no context

data = await page.extract(
  "Get product details",
  schema=Data
)
```

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

### Extract Product Data with Descriptive Schemas (TypeScript)

Source: https://docs.stagehand.dev/v2/best-practices/prompting-best-practices

Demonstrates extracting product information using descriptive field names, correct types, and helpful descriptions in TypeScript. This approach ensures the agent understands the data to be extracted, contrasting with less descriptive methods.

```typescript
// Good - Descriptive names, correct types, and helpful descriptions
const productData = await page.extract({
  instruction: "Extract product information",
  schema: z.object({
    productTitle: z.string().describe("The main product name displayed on the page"),
    priceInDollars: z.number().describe("Current selling price as a number, without currency symbol"),
    isInStock: z.boolean().describe("Whether the product is available for purchase")
  })
});

// Bad - Generic names, wrong types, no descriptions
const data = await page.extract({
  instruction: "Get product details", 
  schema: z.object({
    name: z.string(), // Too generic, no context
    price: z.string(), // Should be number
    stock: z.string() // Should be boolean, no context
  })
});
```

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

### Act() Method Signatures and Parameters (Python)

Source: https://docs.stagehand.dev/v2/references/act

Illustrates the usage of the act() method in Python, showing calls with a string instruction, comprehensive parameters, or an ObserveResult. It outlines the available parameters for fine-tuning action execution.

```python
await page.act(instruction: str) -> ActResult

await page.act(
    instruction: str,
    variables: Dict[str, str] = None,
    dom_settle_timeout_ms: int = None,
    timeout_ms: int = None,
    model_name: AvailableModel = None,
    model_client_options: Dict = None,
    iframes: bool = None,
) -> ActResult

await page.act(observe_result: ObserveResult) -> ActResult
```

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

### Install Stagehand Dependencies in Next.js (npm, pnpm, yarn)

Source: https://docs.stagehand.dev/v2/integrations/vercel/configuration

Installs the required Stagehand, Browserbase SDK, Playwright, and Zod packages for a Next.js project. These dependencies are essential for enabling Stagehand's automation and data extraction capabilities within your application.

```bash
npm install @browserbasehq/stagehand @browserbasehq/sdk playwright zod
```

```bash
pnpm add @browserbasehq/stagehand @browserbasehq/sdk playwright zod
```

```bash
yarn add @browserbasehq/stagehand @browserbasehq/sdk playwright zod
```

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

### Configure Browserbase with Smithery (JSON)

Source: https://docs.stagehand.dev/v2/integrations/mcp/setup

Configure your MCP client to use the Browserbase server hosted remotely via Smithery. This method requires a remote hosted URL obtained from smithery.ai.

```json
{
  "mcpServers": {
    "browserbase": {
      "url": "your-smithery-url.com"
    }
  }
}
```

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

### Stagehand Inference Log File Structure Example (TypeScript)

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

This example shows the structure of a log file generated for the 'act_summary' operation when inference logging is enabled. It includes details like inference type, timestamps, input/output file names, token counts, and inference time.

```typescript
{
  "act_summary": [
    {
      "act_inference_type": "act",
      "timestamp": "20250329_080446068",
      "LLM_input_file": "20250329_080446068_act_call.txt",
      "LLM_output_file": "20250329_080447019_act_response.txt",
      "prompt_tokens": 3451,
      "completion_tokens": 45,
      "inference_time_ms": 951
    },
    ...
  ],
}
```

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

### Link Project and Set Environment Variables

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

Bash commands for linking a local directory to a Vercel project and adding necessary environment variables like API keys and project IDs using the Vercel CLI.

```bash
# authenticate if needed
vercel login

# link the current directory to a Vercel project (interactive)
vercel link
```

```bash
vercel env add BROWSERBASE_API_KEY
vercel env add BROWSERBASE_PROJECT_ID
# (and your model key if needed)
vercel env add GOOGLE_API_KEY
```

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

### Stagehand `act()` Method: Element Identification (TypeScript, Python)

Source: https://docs.stagehand.dev/v2/best-practices/prompting-best-practices

Illustrates how to correctly identify web page elements using their types and descriptive text within the `act()` method. It shows good examples focusing on element function and bad examples relying on visual attributes like color.

```typescript
// Good - Element types and descriptive text
await page.act("click the 'Sign In' button");
await page.act("type into the email input field");

// Bad - Color-based descriptions
await page.act("click the blue button");
await page.act("type into the white input");
```

```python
# Good - Element types and descriptive text
await page.act("click the 'Sign In' button")
await page.act("type into the email input field")

# Bad - Color-based descriptions
await page.act("click the blue button")
await page.act("type into the white input")
```

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

### browserbase_session_create

Source: https://docs.stagehand.dev/v2/integrations/mcp/tools

Creates or reuses a cloud browser session using Browserbase with fully initialized Stagehand.

```APIDOC
## POST /browserbase_session_create

### Description
Create or reuse a cloud browser session using Browserbase with fully initialized Stagehand.

### Method
POST

### Endpoint
/browserbase_session_create

### Parameters
#### Request Body
- **sessionId** (string) - Optional - Session ID to use/reuse. If not provided, creates a new session.

### Request Example
```json
{
  "sessionId": "my-unique-session-id"
}
```

### Response
#### Success Response (200)
- **sessionId** (string) - The ID of the created or reused session.

#### Response Example
```json
{
  "sessionId": "my-unique-session-id"
}
```
```

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

### Initialize Stagehand with Browserbase Environment

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

Initialize the Stagehand instance for the Browserbase environment. This setup is crucial for enabling cloud-managed browser infrastructure features.

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

const stagehand = new Stagehand({
  env: "BROWSERBASE",
});

await stagehand.init();
```

```python
import os
from stagehand import Stagehand

stagehand = Stagehand(
    env="BROWSERBASE",
)

await stagehand.init()
```

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

### multi_browserbase_stagehand_session_create

Source: https://docs.stagehand.dev/v2/integrations/mcp/tools

Creates a new independent Stagehand browser session with full web automation capabilities.

```APIDOC
## POST /multi_browserbase_stagehand_session_create

### Description
Create a new independent Stagehand browser session with full web automation capabilities.

### Method
POST

### Endpoint
/multi_browserbase_stagehand_session_create

### Parameters
#### Request Body
- **name** (string) - Optional - Human-readable name for tracking (e.g., 'login-flow', 'data-scraping').

### Request Example
```json
{
  "name": "data-scraping-session"
}
```

### Response
#### Success Response (200)
- **sessionId** (string) - The ID of the newly created session.

#### Response Example
```json
{
  "sessionId": "session_abc123"
}
```
```

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

### Build Stagehand CLI

Source: https://docs.stagehand.dev/v2/configuration/evals

Builds the Stagehand Command Line Interface (CLI) after dependencies have been installed. This step compiles the CLI tools, making them ready for execution.

```bash
pnpm run build:cli
```

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

### Create Computer Use Agent (Python)

Source: https://docs.stagehand.dev/v2/basics/agent

Initializes a Computer Use Agent in Python using a specified LLM model, custom instructions, and API key. This allows for autonomous browser workflows powered by AI.

```python
agent = stagehand.agent(
    model="claude-sonnet-4-20250514",
    instructions="You are a helpful assistant that can use a web browser.",
    options={
        "api_key": os.getenv("ANTHROPIC_API_KEY"),
    },
)
await agent.execute("apply for a job at Browserbase")
```

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

### Initialize Stagehand and Get Configuration (TypeScript, Python)

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

Initializes the Stagehand session and returns configuration details. This method is asynchronous and logs the result. It requires the stagehand library to be imported.

```typescript
const result = await stagehand.init();
console.log(result);
```

```python
result = await stagehand.init()
print(result)
```

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

### Agent Execution: Navigate First in TypeScript and Python

Source: https://docs.stagehand.dev/v2/best-practices/prompting-best-practices

Illustrates the correct way to use the `agent.execute` method by handling navigation separately before executing agent tasks. Avoid including navigation steps within the agent's instructions.

```typescript
// Good - Navigate first
await page.goto('https://amazon.com');
await agent.execute('Search for wireless headphones under $100 and add the best rated one to cart');

// Bad - Navigation in task
await agent.execute('Go to Amazon, search for headphones, and add one to cart');
```

```python
# Good - Navigate first
await page.goto('https://amazon.com')
await agent.execute('Search for wireless headphones under $100 and add the best rated one to cart')

# Bad - Navigation in task
await agent.execute('Go to Amazon, search for headphones, and add one to cart')
```

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

### Schema-less Extraction with TypeScript

Source: https://docs.stagehand.dev/v2/references/extract

Provides examples of schema-less data extraction in TypeScript. This includes extracting just the page title as a string or retrieving the entire raw page content.

```typescript
// String only extraction
const title = await page.extract("get the page title");
// Returns: { extraction: "Page Title" }

// Raw page content
const content = await page.extract();
// Returns: { pageText: "Accessibility Tree: ..." }
```

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

### Configure Browser Automation Environment Variables

Source: https://docs.stagehand.dev/v2/integrations/crew-ai/configuration

Sets up essential environment variables for Browserbase and LLM API keys. These keys are required for authenticating with Browserbase services and the chosen language model.

```bash
BROWSERBASE_API_KEY="your-browserbase-api-key"
BROWSERBASE_PROJECT_ID="your-browserbase-project-id"
OPENAI_API_KEY="your-openai-api-key"
ANTHROPIC_API_KEY="your-anthropic-api-key"
```

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

### Environment Variables Setup for LLM API Keys

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

Configure your environment variables by setting the appropriate API keys for the LLM providers you intend to use with Stagehand. This is a prerequisite for connecting to these services.

```bash
# Choose one or more providers
OPENAI_API_KEY=your_openai_key_here
ANTHROPIC_API_KEY=your_anthropic_key_here
GOOGLE_API_KEY=your_google_key_here
GROQ_API_KEY=your_groq_key_here
```

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

### Observe Actions with Stagehand `observe`

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

Shows how to use the `observe` method to plan actions and get selectors before execution. It can return the action to be executed and supports specific parameters for detailed observation.

```typescript
const results = await page.observe("Click the sign in button");
```

```typescript
await page.observe({
  instruction: "the instruction to execute",
  returnAction: true 
});
```

```typescript
const results = await page.observe({
  instruction: "the instruction to execute",
  returnAction: true, // return the action to execute
});

await page.act(results[0]);
```

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

### Create and Use OpenAI Computer Use Agent (TypeScript)

Source: https://docs.stagehand.dev/v2/best-practices/build-agent

This TypeScript code snippet demonstrates how to create and use an OpenAI Computer Use agent with Stagehand. It navigates to a GitHub repository and then uses the agent to execute a task, extracting the top contributor's username. This requires the Stagehand library and an OpenAI API key.

```typescript
await page.goto("https://github.com/browserbase/stagehand");

// Create a Computer Use agent with just one line of code!
const agent = stagehand.agent({
	provider: "openai",
	model: "computer-use-preview"
});

// Use the agent to execute a task
const result = await agent.execute("Extract the top contributor's username");
console.log(result);

```

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

### Set Appropriate Timeouts (Python)

Source: https://docs.stagehand.dev/v2/best-practices/speed-optimization

Use shorter timeouts for simple operations and longer ones for complex page loads. This helps prevent unnecessary delays and optimizes navigation efficiency.

```python
# Simple actions - reduce action timeout
await page.act("Click button", act_timeout=5000)


# Complex page loads - optimize navigation
await page.goto("https://heavy-spa.com", 
    wait_until="domcontentloaded",
    timeout=15000
)
```
Tokens:
Raw