@meetopenbot/stagehand

Stagehand AI-browser-automation plugin for OpenBot.

Give the agent a natural-language task ("Go to news.ycombinator.com and grab the top 3 AI stories") and the plugin will spin up a browser, drive it with an LLM-powered agent, and return the result.

What is included

• plugin registry export compatible with OpenBot
• agent:invoke handler that runs a Stagehand agent (stagehand.agent().execute(...)) for the user's prompt
• client:ui:widget:response handler that captures missing API keys from the UI form and persists them via OpenBot storage
• Per-step progress streaming back to the chat (one line per agent step)

Install & build

npm install
npm run build

npm install will also try to install the Playwright Chromium browser binary via the postinstall script. If that fails (e.g. firewall, headless server), run it manually:

npx playwright install chromium

Then load dist/index.js from your OpenBot plugin registry.

Configuration

Required: one LLM key

Set one of the following so Stagehand can drive the browser:

• OPENAI_API_KEY — default; uses openai/gpt-4o-mini
• ANTHROPIC_API_KEY — uses anthropic/claude-sonnet-4-5-20250929
• GOOGLE_GENERATIVE_AI_API_KEY — uses google/gemini-2.5-flash
• BROWSERBASE_API_KEY — enables Browserbase Model Gateway (only when running with env: "BROWSERBASE")

If no key is set, the plugin will pop up a form widget to capture and persist one.

Optional: Browserbase (cloud browser)

If both BROWSERBASE_API_KEY and BROWSERBASE_PROJECT_ID are set (or you pass env: "BROWSERBASE" in plugin options), the plugin will run against Browserbase's cloud browsers instead of local Chromium.

Plugin options

{
  apiKey?: string;                  // overrides env LLM key
  provider?: "openai" | "anthropic" | "google"; // overrides auto-detect
  model?: string;                   // full "provider/model" or short id, overrides default
  env?: "LOCAL" | "BROWSERBASE";    // default: LOCAL
  browserbaseApiKey?: string;
  browserbaseProjectId?: string;
  headless?: boolean;               // default: true (LOCAL mode)
  maxSteps?: number;                // default: 25
  mode?: "dom" | "hybrid" | "cua";  // default: auto
  systemPrompt?: string;            // optional system prompt override
  storage?: { createVariable: (...) => Promise<unknown> };
}

Notes

• The plugin starts a fresh browser for each invocation and closes it when done. This is the most stable mode — no leaked Chromium processes between turns.
• Local mode requires the Playwright Chromium binary (~150MB). Use Browserbase if you don't want to ship Chromium locally.
• dist/index.js is intentionally tiny — runtime deps (@browserbasehq/stagehand, playwright, zod) stay external and are resolved from the plugin's local node_modules.