Stagehand — SDK от Browserbase для браузерных агентов

Stagehand — это SDK от Browserbase для браузерных агентов. Библиотека с открытым исходным кодом (MIT, около 25,4 тысячи звёзд на GitHub) добавляет к обычному браузерному драйверу три операции на естественном языке — observe, act и extract, — а всё остальное (goto, click, locator, screenshot) продолжает работать как в Playwright. Написана на трёх языках: TypeScript, Python и Go.

Главная идея в том, что агент не получает скриншот целиком и не пишет CSS-селекторы по памяти. Вместо этого он спрашивает библиотеку словами, а та возвращает проверенные результаты: observe даёт реальные селекторы, act выполняет действие и переучивается, если сайт поменялся, extract возвращает данные, уже проверенные по схеме.

Три метода, на которых держится всё

Важная деталь, на которую стоит обратить внимание: observe возвращает настоящие селекторы, а не координаты и не скриншот. Поэтому логин и пароль можно подставить в поле самому кодом — секреты вообще не уходят в модель.

Пример на TypeScript

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

// Cookies persist in ./browser-data, so the next run starts already signed in
const browser = await localBrowser.launch({ userDataDir: "./browser-data" });
const stagehand = await Stagehand.create({
  browser,
  model: { modelName: "openai/gpt-5.4-mini", apiKey: process.env.OPENAI_API_KEY },
});

const [page] = await browser.context.pages();
await page.goto("https://app.example.com/login");

// observe() returns real selectors, so credentials never reach the model
const { data: email } = await stagehand.observe("find the email input");
const { data: password } = await stagehand.observe("find the password input");
await page.locator(email[0].selector).fill(process.env.APP_EMAIL!);
await page.locator(password[0].selector).fill(process.env.APP_PASSWORD!);

// act() self-heals when the site redesigns its form
await stagehand.act("click the sign in button");
await stagehand.act("open the billing page");

// extract() returns schema-validated data
const { data } = await stagehand.extract(
  "extract every invoice in the table",
  z.object({
    invoices: z.array(z.object({ number: z.string(), amount: z.number(), paid: z.boolean() })),
  }),
);

console.log(data.invoices);

await stagehand.close();
await browser.close();

Обратите внимание на userDataDir: "./browser-data": cookies лежат на диске, поэтому следующий запуск стартует уже авторизованным. Никакой отдельной системы хранения сессий не нужно.

Установка

pnpm add @browserbasehq/stagehand 'zod@~4.4.3'

Python и Go ставятся так же:

pip install stagehand
go get github.com/browserbase/stagehand/packages/sdk-go/v4@v4.0.0

Локальные запуски требуют установленный Chrome. Полная настройка — в Quickstart.

Почему это удобно

Документация по методам: act, observe, extract. Обзор API страницы и локаторов — в разделах page и locator.

Облако Browserbase

Тот же скрипт можно направить в Browserbase и получить, по заявлению авторов, вдвое более быстрое выполнение по сравнению с облачными аналогами Playwright. Плюс в комплекте идут verified mode, резидентные прокси, персистентные контексты и записи сессий.

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

const browser = await browserbase.launch({ apiKey: process.env.BROWSERBASE_API_KEY! });

// No model configuration: the Model Gateway picks the cheapest model for each action
// cache: true: identical calls come back from Browserbase, no tokens spent
const stagehand = await Stagehand.create({ browser, cache: true });

Два момента, которые экономят деньги и нервы:

• Model Gateway — можно вообще не задавать модель, шлюз сам подберёт самую дешёвую под конкретное действие.
• Серверный кэш — одинаковые повторяющиеся вызовы возвращаются из кэша Browserbase, токены не тратятся.

Настройка браузера описана в этом разделе документации, а сам API key берётся здесь.

Браузер для кодинг-агента через MCP

Если писать скрипт не хочется, у Browserbase есть хостинговый MCP-сервер: он отдаёт navigate, act, observe и extract любому MCP-клиенту — без установки и без локального браузера.

claude mcp add --transport http browserbase https://mcp.browserbase.com/mcp \
  --header "Authorization: Bearer $BROWSERBASE_API_KEY"

Для Cursor, Codex и остальных MCP-клиентов настройка выглядит так:

{
  "mcpServers": {
    "browserbase": {
      "url": "https://mcp.browserbase.com/mcp",
      "headers": { "Authorization": "Bearer YOUR_BROWSERBASE_API_KEY" }
    }
  }
}

То есть Stagehand вполне можно использовать и как обычный инструмент внутри Claude Code или Codex — тот же набор методов, только без лишнего кода.

Поиск и загрузка без браузера

Отдельные аддоны позволяют обойтись вообще без запуска браузера. Fetch отдаёт содержимое любого URL в виде markdown, Search даёт быстрые и экономные по токенам результаты веб-поиска.

import { browserbase } from "@browserbasehq/stagehand";

const { results } = await browserbase.search({
  apiKey: process.env.BROWSERBASE_API_KEY!,
  query: "browser agent frameworks",
  numResults: 5,
});

const fetched = await browserbase.fetch({
  apiKey: process.env.BROWSERBASE_API_KEY!,
  url: results[0].url,
  format: "markdown",
});

console.log(fetched.content);

Если уже есть тесты на Playwright

Отдельная страница документации посвящена миграции с Playwright — существующий набор можно переносить постепенно, а не переписывать. Есть и обзор интеграций: CrewAI, Mastra, Deep Agents, Vercel AI SDK, Claude Code, Codex. Отдельно стоит посмотреть WebMCP — механизм, позволяющий находить и вызывать инструменты, которые веб-страница отдаёт сама.

Разработка

Репозиторий — монорепо на TypeScript, Python и Go, сборка на just:

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

export OPENAI_API_KEY="your-openai-api-key"
just example act # runs packages/sdk-ts/examples/act.ts

Подробная инструкция по настройке всех трёх языков лежит в CONTRIBUTING.md, ответы по архитектуре — на DeepWiki. Сайт проекта — stagehand.dev, лицензия — MIT.