Stagehand — Agents-OSS

概要

手順が分かっている部分は決定論的なPlaywrightで書き、ページの構造が予測できない箇所だけ自然言語に切り替えられます。この混在方式が現実的な中間解です。完全にAI任せの自動化は遅く不安定であり、完全にスクリプト化した自動化は画面刷新のたびに壊れます。

Stagehandで何ができますか？

自然言語とロケータの併用 — 構造が読めない操作はstagehand.act("click on the stagehand repo")のように自然言語で指示し、observe()が返すセレクタをpage.locator()に渡せば、同じ操作を決定論的に繰り返せます。
スキーマに沿った情報抽出 — extract()にZodスキーマを渡すと、宣言したフィールドだけが型の付いた値として返ります。ページ本文を受け取ってから自前で切り出す処理は不要です。
画面変更への自動追従 — act、observe、extractはself-healingで、サイト側の変更を検知して操作方法を組み直します。セレクタが1つ合わなくなっただけでスクリプト全体が止まる状況を避けられます。
入れ子になったDOMへの到達 — deep locatorがプロセス外iframeやclosed Shadow DOMの内側まで届き、通常の自動化では触れない要素を操作できます。クリップボード操作やバッチコマンドも用意されています。
TypeScript・Python・Goで書ける — 同一のブラウザドライバが3つのSDKとして提供されます。npmでは@browserbasehq/stagehand、PythonとGoは同じリポジトリのpackages/sdk-pythonとpackages/sdk-goにあり、just installとjust buildでまとめてビルドできます。

ドキュメント

browserbase/stagehand のREADMEより転載（MIT）。原文を読む ↗

What is Stagehand?

Stagehand is the SDK for browser agents. Playwright was built for testing, Stagehand is built for agents. Use familiar APIs, self-healing actions, and network-level security across TypeScript, Python, and Go.

Why Stagehand?

Stagehand gives browser agents an interface built for how they actually work. It combines familiar Playwright-style APIs with self-healing actions, agent-optimized page context, and native support for complex DOM structures like out-of-process iframes and closed Shadow DOMs.

Agents use fewer tokens, recover when websites change, and complete tasks more reliably. With a complete browser driver across TypeScript, Python, and Go, Stagehand delivers the flexibility of AI without sacrificing the speed, control, determinism, reliability, and observability required in production.

1. Familiar APIs

The Playwright-style methods you and your agents already know and love (goto, click, locator, screenshot).

2. Token efficiency as a priority

Stagehand’s hybrid accessibility tree trimming gives your agents exactly what they need to understand the page and nothing more.

3. Faster in production

Stagehand runs as an extension next to the browser, closing the distance and reducing round-trip latency for all actions on the page.

4. Self-healing primitives

Use act, observe, and extract with natural language to automate pages. When sites change, Stagehand detects it and refreshes how the actions happen on the page automatically.

5. Features agents need

WebMCP, clipboard support, self-healing actions, batch commands, deep locators for nested iframes, and OTel support.

Getting Started

Check out our Quickstart Guide for more information:

Example

Here’s how to build a sample browser automation with Stagehand:

import { browserbase, Stagehand } from "@browserbasehq/stagehand";
import { z } from "zod/v4";

const { BROWSERBASE_API_KEY, OPENAI_API_KEY } = process.env;

const browser = await browserbase.launch({
  apiKey: BROWSERBASE_API_KEY,
});

const stagehand = await Stagehand.create({
  browser,
  model: {
    modelName: "openai/gpt-5.4-mini",
    apiKey: OPENAI_API_KEY,
  },
});

// Stagehand's CDP engine provides an optimized, low level interface to the browser built for automation
const [page] = await browser.context.pages();
await page.goto("https://github.com/browserbase");

// Use act() to execute individual actions
await stagehand.act("click on the stagehand repo");

// Use observe() to see what's actionable on the page
const { data: actions } = await stagehand.observe("find the latest PR");

// Use locators for deterministic Playwright-style actions
await page.locator(actions[0].selector).click();

// Use extract() to get structured data from the page
const {
  data: { author, title },
} = await stagehand.extract(
  "extract the author and title of the PR",
  z.object({
    author: z.string().describe("The username of the PR author"),
    title: z.string().describe("The title of the PR"),
  }),
);

See the Python and Go READMEs for equivalent examples.

Documentation

Visit docs.stagehand.dev to view the full documentation.

Build and Run from Source

Stagehand is a TypeScript, Python, and Go monorepo. We use just to drive pnpm, uv, and go together.

git clone https://github.com/browserbase/stagehand.git
cd stagehand
just install
just generate
just build

Stagehand is best when you have an API key for an LLM provider and Browserbase credentials. Export them so they’re available on process.env:

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

Then run any of the scripts in packages/sdk-ts/examples:

just example act # runs packages/sdk-ts/examples/act.ts

See CONTRIBUTING.md for the full TypeScript, Python, and Go setup.