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/tools/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

// 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));

​
Step 6: Build LangGraph Agents

Integrate with LangGraph for complex automation workflows: 
npm install @langchain/langgraph @langchain/community @langchain/core @langchain/openai @browserbasehq/stagehand
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