Skip to main content

Stagehand Toolkit

The Stagehand Toolkit equips your AI agent with the following capabilities:

  • navigate(): Navigate to a specific URL.
  • act(): Perform browser automation actions like clicking, typing, and navigation.
  • extract(): Extract structured data from web pages using Zod schemas.
  • observe(): Get a list of possible actions and elements on the current page.

Setup​

  1. Install the required packages:
npm install @langchain/langgraph @langchain/community @langchain/core
  1. Create a Stagehand Instance If you plan to run the browser locally, you'll also need to install Playwright's browser dependencies.
npx playwright install
  1. Set up your model provider credentials:

For OpenAI:

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

For Anthropic:

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

Usage, Standalone, Local Browser​

import { StagehandToolkit } from "langchain/community/agents/toolkits/stagehand";
import { ChatOpenAI } from "@langchain/openai";
import { Stagehand } from "@browserbasehq/stagehand";

// Specify your Browserbase credentials.
process.env.BROWSERBASE_API_KEY = "";
process.env.BROWSERBASE_PROJECT_ID = "";

// Specify OpenAI API key.
process.env.OPENAI_API_KEY = "";

const stagehand = new Stagehand({
  env: "LOCAL",
  headless: false,
  verbose: 2,
  debugDom: true,
  enableCaching: false,
});

// Create a Stagehand Toolkit with all the available actions from the Stagehand.
const stagehandToolkit = await StagehandToolkit.fromStagehand(stagehand);

const navigateTool = stagehandToolkit.tools.find(
  (t) => t.name === "stagehand_navigate"
);
if (!navigateTool) {
  throw new Error("Navigate tool not found");
}
await navigateTool.invoke("https://www.google.com");

const actionTool = stagehandToolkit.tools.find(
  (t) => t.name === "stagehand_act"
);
if (!actionTool) {
  throw new Error("Action tool not found");
}
await actionTool.invoke('Search for "OpenAI"');

const observeTool = stagehandToolkit.tools.find(
  (t) => t.name === "stagehand_observe"
);
if (!observeTool) {
  throw new Error("Observe tool not found");
}
const result = await observeTool.invoke(
  "What actions can be performed on the current page?"
);
const observations = JSON.parse(result);

// Handle observations as needed
console.log(observations);

const currentUrl = stagehand.page.url();
expect(currentUrl).toContain("google.com/search?q=OpenAI");

Usage with LangGraph Agents​

import { Stagehand } from "@browserbasehq/stagehand";
import {
  StagehandActTool,
  StagehandNavigateTool,
} from "@langchain/community/agents/toolkits/stagehand";
import { ChatOpenAI } from "@langchain/openai";
import { createReactAgent } from "@langchain/langgraph/prebuilt";

async function main() {
  // Initialize Stagehand once and pass it to the tools
  const stagehand = new Stagehand({
    env: "LOCAL",
    enableCaching: true,
  });

  const actTool = new StagehandActTool(stagehand);
  const navigateTool = new StagehandNavigateTool(stagehand);

  // Initialize the model
  const model = new ChatOpenAI({
    modelName: "gpt-4",
    temperature: 0,
  });

  // Create the agent using langgraph
  const agent = createReactAgent({
    llm: model,
    tools: [actTool, navigateTool],
  });

  // Execute the agent using streams
  const inputs1 = {
    messages: [
      {
        role: "user",
        content: "Navigate to https://www.google.com",
      },
    ],
  };

  const stream1 = await agent.stream(inputs1, {
    streamMode: "values",
  });

  for await (const { messages } of stream1) {
    const msg =
      messages && messages.length > 0
        ? messages[messages.length - 1]
        : undefined;
    if (msg?.content) {
      console.log(msg.content);
    } else if (msg?.tool_calls && msg.tool_calls.length > 0) {
      console.log(msg.tool_calls);
    } else {
      console.log(msg);
    }
  }

  const inputs2 = {
    messages: [
      {
        role: "user",
        content: "Search for 'OpenAI'",
      },
    ],
  };

  const stream2 = await agent.stream(inputs2, {
    streamMode: "values",
  });

  for await (const { messages } of stream2) {
    const msg =
      messages && messages.length > 0
        ? messages[messages.length - 1]
        : undefined;
    if (msg?.content) {
      console.log(msg.content);
    } else if (msg?.tool_calls && msg.tool_calls.length > 0) {
      console.log(msg.tool_calls);
    } else {
      console.log(msg);
    }
  }
}

main();

API Reference:

Usage on Browserbase - remote headless browser​

If you want to run the browser remotely, you can use the Browserbase platform.

You need to set the BROWSERBASE_API_KEY environment variable to your Browserbase API key.

export BROWSERBASE_API_KEY="your-browserbase-api-key"

You also need to set BROWSERBASE_PROJECT_ID to your Browserbase project ID.

export BROWSERBASE_PROJECT_ID="your-browserbase-project-id"

Then initialize the Stagehand instance with the BROWSERBASE environment.

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

Was this page helpful?


You can also leave detailed feedback on GitHub.