browser-use → Stagehand на Browserbase (/browser-use-to-stagehand)

Преобразует скрипт browser-use (Python) в идиоматический скрипт Stagehand v3 (TypeScript) на Browserbase, выбирая на каждом шаге подходящий уровень детерминизма, а не создавая однозначную агентную копию.

Основной принцип: browser-use по умолчанию является агентивным (каждое действие определяет LLM). Stagehand позволяет выбрать степень использования ИИ. Удачная миграция заменяет непрозрачные агентские циклы на прозрачный, в основном детерминированный конвейер — с использованием ИИ только там, где поведение страницы действительно непредсказуемо. Это рефакторинг с применением суждения, а не просто транспайлинг.

Источник достоверности и версии. Долгосрочная ценность этого навыка заключается в суждении — в спектре детерминизма и решении «декомпозиция или агент» — а не в особенностях API, которые меняются с каждым выпуском. Приведённые здесь сопоставления кода представляют собой моментальный снимок, проверенный на совместимость с @browserbasehq/stagehand 3.6.x и browser-use 0.13.x (2026-06). В случае любого конфликта приоритет имеют актуальные документации — всегда проверяйте на соответствие установленному пакету и этим исходным кодам перед генерацией кода:

• Stagehand v3: https://docs.stagehand.dev/v3 · установленные типы: node_modules/@browserbasehq/stagehand
• Browserbase: https://docs.browserbase.com
• browser-use: https://docs.browser-use.com

Если основная версия установленного Stagehand не равна 3, рассматривайте этот навык как чисто концептуальный и следуйте актуальной документации для каждой сигнатуры.

Справочные файлы (читайте по мере необходимости)

• references/api-mapping.md — механическое сопоставление browser-use → Stagehand: обнаружение вариантов, полная таблица возможностей, код «до» и «после», параметры платформы Browserbase и особенности версии v3. Читайте это при работе с любой нетривиальной конструкцией.
• references/determinism.md — как выбрать agent() vs act/extract/observe vs кэшированный observe→act. Дерево принятия решений. Ознакомьтесь с этим при принятии решения о том, как перевести файл Agent(task=…).
• references/trace-assisted.md — опциональный рабочий процесс «запустить на Browserbase, прочитать логи, затем переписать» для непрозрачных/нестабильных скриптов.
• references/guide.md — руководство по миграции для людей: смена философии, сопоставление функций, спектр детерминизма и рекомендуемый путь миграции.
• references/prompt.md — автономная, независимая от инструментов версия этого навыка; вставьте её в любой ИИ-помощник вместе со скриптом для работы в браузере.
• EXAMPLES.md — пары скриптов «до» и «после».

Рабочий процесс

1. Получите исходный код

Получите скрипт(ы) использования браузера. Если пользователь описал только скрипт, попросите предоставить файл(ы). Обратите внимание на целевую платформу: TypeScript Stagehand на Browserbase, если не указано иное.

Сначала определите область применения — можно ли вообще выполнить миграцию? Не каждый файл «browser-use» является Agent(task=…) скриптом. Если исходный код — это «browser-use», работающий в качестве сервера MCP (uvx browser-use --mcp, mcpServers конфигурация), то эквивалента Stagehand для него нет — пометьте его как выходящий за пределы области применения, не придумывайте его (см. §3.7b раздела «Сопоставление API»). Если вызов browser-use встроен в более крупное приложение (обёртку класса/инструмента, веб-маршрут, задачу очереди), преобразуйте только поверхность взаимодействия с browser-use и сохраните связующий код окружающего приложения — см. §3.8 раздела «сопоставление API».

2. Определите вариант использования браузера

Определите, что это за версию: устаревшая (до 0.12), стабильная или бета-версия Rust (только если импорты происходят из browser_use.beta) — см. раздел «api-mapping» §1. Примечание: классический интерфейс верхнего уровня from browser_use import Agent, ChatBrowserUse по-прежнему активно используется в версии 0.13.x — ChatBrowserUse само по себе не является признаком бета-версии; таковым является только browser_use.beta import является признаком бета-версии. Все варианты переводятся одинаково, поэтому в случае сомнений используйте стабильное сопоставление. Перед переводом приведите устаревшие имена к стандартной форме. Укажите, какой вариант вы обнаружили.

3. Составьте перечень скриптов

Перед написанием кода на TypeScript составьте структурированный перечень:

• Задача(и) — task= строка(и); разбейте каждую на подразумеваемые упорядоченные шаги.
• Модель — Chat* поставщик + идентификатор модели.
• Конфигурация браузера — локальная или cdp_url/Browserbase; безграфический режим; прокси; user_data_dir/storage_state.
• Структурированный вывод — любые output_model_schema модели Pydantic.
• Секретные данные — sensitive_data, использование переменных среды, процедуры входа.
• Защитные меры — allowed_domains, max_steps.
• Пользовательские действия — @tools.action / Controller функции и то, является ли каждая из них детерминированным побочным эффектом или возможностью агента.
• Настройка — initial_actions, вторичные модели (page_extraction_llm, planner_llm).

4. Определите уровень детерминированности для каждого шага

Для каждого шага из перечня примените дерево решений из файла determinism.md:

• Перейти по известному URL-адресу → page.goto(url) на странице Stagehand (без ИИ).
• Действие на странице → act("…"); если оно повторяется, observe() один раз, затем повторите act(action) (без вызова LLM).
• Чтение данных → extract("…", zodSchema).
• По-настоящему открытый формат → сохранить stagehand.agent().execute(...) (уточняется с помощью maxSteps/systemPrompt).

По умолчанию — декомпозиция, когда поток известен; сохранить agent() только там, где он неизвестен. Для первого «lift-and-shift» допустим точный agent() перевод — укажите это и отметьте путь оптимизации.

5. Создание переписанной версии Stagehand v3

Сначала проверьте API. Перед написанием убедитесь в точности сигнатур, которые вы собираетесь использовать, сверяя их с установленным пакетом (node_modules/@browserbasehq/stagehand типы) или на сайте https://docs.stagehand.dev/v3. Приведённые ниже сопоставления являются моментальным снимком версии 3.6.x; если в установленной версии что-либо отличается, приоритет имеет установленная версия. Затем сгенерируйте исполняемый код TypeScript. Всегда:

• import { Stagehand } from "@browserbasehq/stagehand"; и import { z } from "zod"; при извлечении.
• Получите страницу с помощью const page = stagehand.context.pages()[0];.
• Вызывайте методы AI на экземпляре: stagehand.act(...), stagehand.extract(...), stagehand.observe(...) — никогда page.act(...).
• не задавайте модель в качестве "provider/model" строку.
• По умолчанию env: "BROWSERBASE"; отобразить env: "LOCAL" в качестве опции разработчика.
• Передавайте секретные данные через variables и process.env, никогда не указывайте их в коде.
• await stagehand.init() в начале, await stagehand.close() в finally.

Включите настройку проекта, чтобы он запускался (см. шаблоны ниже).

6. Напишите краткое описание миграции

Наряду с кодом подготовьте краткую сводку:

• Обнаруженный вариант и сделанный выбор детерминизма (какие шаги стали детерминированными, а какие — AI или агентом), с обоснованием.
• Требуется проверка человеком — всё, что не сопоставилось 1:1: утраченные allowed_domains ограничительные меры, логика пользовательских действий, намерения вторичной модели, неоднозначные строки задач.
• Рекомендуемый следующий шаг — Browserbase Context для повторного использования авторизации, кэширование для производственной среды или путь с поддержкой трассировки, если поток был непрозрачным.

7. Предложите путь с использованием трассировки (только если это оправдано)

Если исходный код представлял собой один большой непрозрачный agent(task=…), нестабильным или если ваше переписание нельзя с уверенностью сопоставить, предложите рабочий процесс с поддержкой трассировки (trace-assisted.md): запустите исходный код на Browserbase, извлеките sessions.logs.list, а затем перепишите код на основе наблюдаемого поведения. Не запускайте ничего без согласия пользователя.

Шаблоны вывода

package.json

{
  "name": "stagehand-migration",
  "type": "module",
  "scripts": { "start": "tsx index.ts" },
  "dependencies": {
    "@browserbasehq/stagehand": "^3.0.0",
    "dotenv": "^16.0.0",
    "zod": "^3.25.0"
  },
  "devDependencies": { "tsx": "^4.0.0", "typescript": "^5.0.0" }
}

Добавьте "ai": "^5.0.0" (Vercel AI SDK) только в том случае, если пользовательское действие «использование браузера» сопоставляется с агентом tool. Закрепите версию v5, а не v4 — Stagehand 3.6.x включает ai v5 и типы agent({ tools }) как v5 ToolSet, где поле схемы инструмента — inputSchema. Вспомогательная функция v4 tool() выдает parameters вместо этого и не пройдет проверку типов по сравнению с v5 от Stagehand ToolSet. Если вы не можете контролировать поднятую ai версию, пропустите tool() помощник и передайте простой объект { description, inputSchema: zodSchema, execute } — он удовлетворяет требованиям v5 ToolSet независимо от того, какое ai из основных резолверов будет выполнен.

.env

BROWSERBASE_API_KEY=...
BROWSERBASE_PROJECT_ID=...
ANTHROPIC_API_KEY=...   # or the provider matching your model string

index.ts каркас (разбитый на части, предпочтительный вариант)

import "dotenv/config";
import { Stagehand } from "@browserbasehq/stagehand";
import { z } from "zod";

async function main() {
  const stagehand = new Stagehand({
    env: "BROWSERBASE",
    model: "anthropic/claude-sonnet-4-6",
  });
  await stagehand.init();
  try {
    const page = stagehand.context.pages()[0];

    await page.goto("https://example.com");          // deterministic skeleton
    await stagehand.act("…");                          // AI where the page varies
    const data = await stagehand.extract("…", z.object({ /* … */ }));  // structured reads

    console.log(data);
  } finally {
    await stagehand.close();
  }
}

main().catch((err) => { console.error(err); process.exit(1); });

Контрольный список проверки (перед объявлением о завершении)

• Методы ИИ применяются к экземпляру (stagehand.act/extract/observe), а не на странице.
• Страница получена с помощью stagehand.context.pages()[0].
• Model представляет собой "provider/model" строка; соответствующий ключ провайдера находится в .env.
• extract использует схему Zod; zod находится в списке зависимостей.
• Секреты используют variables + process.env; ничего не записано жестко в коде.
• init() / close() присутствует; close() в finally.
• Каждый этап использования браузера учтён и целенаправленно размещён на спектре детерминированности.
• В сводке по миграции перечислены варианты детерминизма и пункты, «требующие проверки человеком».

Распространённые ошибки, которых следует избегать

• Копирование синтаксиса v2 (page.act(), stagehand.page, modelName/modelClientOptions, enableCaching) из старых записей в блоге. Используйте версию v3 — см. раздел «Примечания по версиям» в документации по сопоставлению API.
• Перевод каждого шага в формат act() — перемещайтесь с помощью page.goto и кэшируйте повторяющиеся шаги с помощью observe→act; не тратьте вызов LLM на каждое действие.
• Установка всего по умолчанию в agent() — это просто воспроизводит недетерминизм использования браузера в новом фреймворке. Декомпозируйте там, где поток известен.
• Тихое исключение allowed_domains — у Stagehand нет доменного брандмауэра; пометьте это для проверки.
• Придумывание опций Browserbase/Stagehand — если не уверены в значении поля, проверьте https://docs.stagehand.dev/v3 / https://docs.browserbase.com, а не гадайте.