Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.stagehand.dev/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks you through integrating Stagehand with LangChain JS to build powerful web automation workflows using natural language instructions.

​
Step 1: Install Dependencies

Install the required packages for LangChain JS and Stagehand integration: 
npm install @langchain/langgraph @langchain/community @langchain/core @browserbasehq/stagehand

​
Step 2: Configure Environment Variables

For remote browser automation, set up your Browserbase credentials: 
BROWSERBASE_API_KEY="your-browserbase-api-key"
BROWSERBASE_PROJECT_ID="your-browserbase-project-id"

​
Step 3: Create a Stagehand Instance

Initialize Stagehand with your preferred configuration: 
import { Stagehand } from "@browserbasehq/stagehand";

// For local development
const stagehand = new Stagehand({
    env: "LOCAL",
    verbose: 2,
    enableCaching: false,
});

// For production with Browserbase
const stagehand = new Stagehand({
    env: "BROWSERBASE",
    verbose: 1,
    enableCaching: true,
});

​
Step 4: Generate the StagehandToolkit

Create the toolkit that provides LangChain-compatible tools: 
import { StagehandToolkit } from '@langchain/community/agents/toolkits/stagehand';

const stagehandToolkit = await StagehandToolkit.fromStagehand(stagehand);

​
Step 5: Use Individual Tools

The toolkit provides four specialized tools for web automation:

​
Available Tools

  • stagehand_navigate: Navigate to specific URLs
  • stagehand_act: Perform browser actions (clicking, typing, etc.)
  • stagehand_extract: Extract structured data using schemas
  • stagehand_observe: Analyze page elements and possible actions

​
Basic Tool Usage

import { z } from "zod";

// Navigate to a website
const navigateTool = stagehandToolkit.tools.find(
    (t) => t.name === "stagehand_navigate"
);
await navigateTool.invoke("https://www.google.com");

// Perform an action
const actionTool = stagehandToolkit.tools.find(
    (t) => t.name === "stagehand_act"
);
await actionTool.invoke('Search for "OpenAI"');

// Observe the page
const observeTool = stagehandToolkit.tools.find(
    (t) => t.name === "stagehand_observe"
);
const result = await observeTool.invoke(
    "What actions can be performed on the current page?"
);
console.log(JSON.parse(result));

// Extract structured data
const extractTool = stagehandToolkit.tools.find(
    (t) => t.name === "stagehand_extract"
);
const extractResult = await extractTool.invoke({
    instruction: "Extract the main heading and description",
    schema: z.object({
        heading: z.string(),
        description: z.string(),
    }),
});
console.log(extractResult);

​
Step 6: Build LangGraph Agents

Integrate with LangGraph for complex automation workflows: 
import { createReactAgent } from "@langchain/langgraph/prebuilt";

// Create an LLM
const llm = new ChatOpenAI({
    model: "gpt-4",
    temperature: 0,
});

// Create an agent with Stagehand tools
const agent = createReactAgent({
    llm,
    tools: stagehandToolkit.tools,
});

// Execute a complex workflow
const result = await agent.invoke({
    messages: [
        {
            role: "user", 
            content: "Go to example.com, find the contact form, and extract all the form fields"
        }
    ]
});

​
Advanced Configuration

​
Custom Stagehand Configuration

const stagehand = new Stagehand({
    env: "BROWSERBASE",
    verbose: 2,
    enableCaching: true,
    headless: true,
    domSettleTimeoutMs: 5000,
});

​
Error Handling

try {
    const result = await agent.invoke({
        messages: [{ role: "user", content: "Navigate to invalid-url.com" }]
    });
} catch (error) {
    console.error("Automation failed:", error);
} finally {
    // Clean up resources
    await stagehand.close();
}

​
Example Workflows

const extractionAgent = createReactAgent({
    llm,
    tools: stagehandToolkit.tools,
});

const result = await extractionAgent.invoke({
    messages: [{
        role: "user",
        content: `
            Go to news-website.com and extract:
            1. All article headlines
            2. Publication dates  
            3. Author names
            Format as structured JSON
        `
    }]
});

LangChain JS Documentation

Official LangChain JS documentation for the Stagehand integration