Автоматизация браузера со Stagehand

Автоматизация браузера со Stagehand состоит из двух уровней: Stagehand предоставляет примитивы для работы со страницей, а launcher выбирает исполняемый файл Chromium и аргументы запуска. В документации Stagehand v4 описаны act, extract и observe, а подключение выполняется через Chrome DevTools Protocol (CDP) к уже запущенному Chromium. BotBrowser позволяет запустить Chromium с выбранным оператором исполняемым файлом и флагом --bot-profile; Stagehand v4 может подключиться к этому браузеру по CDP. BotBrowser не предоставляет адаптер Stagehand, не задает политику агента и не гарантирует классификацию стороннего сайта. В настройке browser-use рассматривается другой framework, а руководство по прямому запуску Playwright описывает другой API управления.

Успешное подключение не доказывает, что запущен нужный процесс. URL CDP указывает на endpoint, но не подтверждает путь к бинарному файлу, аргумент профиля, сетевой маршрут или состояние страницы. Сохраняйте эти наблюдения отдельно и сверяйтесь со справочником флагов BotBrowser, чтобы использовать поддерживаемый аргумент профиля; вызов Stagehand не настраивает запуск браузера.

TL;DR

• observe() находит возможные действия, act() выполняет действие, а extract() возвращает данные по заданной схеме.
• Stagehand v4 подключается к Chromium через CDP; актуальная документация указывает, что зависимостей Playwright и Puppeteer нет.
• Launcher, а не примитивы страницы Stagehand, выбирает исполняемый файл и передает --bot-profile до запуска браузера.
• Ответ CDP доказывает, что endpoint ответил. Он не доказывает, какой исполняемый файл или профиль был использован.
• Оставляйте endpoint доступным только через loopback, отдельно проверяйте процесс и останавливайтесь при несовпадении. Та же проверка применима, когда запуском владеет сервер MCP, а не скрипт, и ключи, которые несут там исполняемый файл, разобраны в статье настройка Playwright MCP для собственной сборки Chromium.

Содержание

• Ответственность примитивов
• Запуск и подключение являются разными операциями
• Запустите контролируемый браузер до Stagehand
• Выполните три примитива на fixture
• Проверьте процесс и CDP target
• Таблица сбоев и восстановления
• Что остается вне Stagehand
• Практический вывод

Ответственность примитивов

Три именованных примитива Stagehand решают разные задачи. observe() находит доступные элементы и возвращает структурированные действия; act() выполняет инструкцию или действие, полученное от observe(); extract() читает содержимое страницы в запрошенной форме. Официальные справочники observe, act и extract описывают их входы и результаты. Это операции Stagehand, а не параметры выбора исполняемого файла.

Различие ограничивает утверждения, которые можно сделать по trace. Результат observe() означает, что Stagehand нашел кандидатов на действие для текущей страницы и инструкции; это не согласие пользователя. Результат act() фиксирует попытку взаимодействия, но удаленное приложение еще может ее отклонить или применить другое изменение. Результат extract() содержит данные, соответствующие схеме запроса; это не копия серверной базы и не независимая проверка истинности страницы.

Примитив	Работа со страницей	Что полезно сохранить
observe()	Найти элементы-кандидаты для ограниченной инструкции	Origin страницы, ID инструкции, число кандидатов и выбранное действие
act()	Выполнить инструкцию или выбранное действие	ID действия и возвращенный результат, но не утверждение об удаленном принятии
extract()	Прочитать данные по заданной схеме	Версию схемы и только нужные поля

Эти операции можно объединить в последовательность, но их результаты не следует сводить к единому флагу success. Подключение к браузеру может пройти успешно, а извлечение данных завершиться ошибкой; извлечение может сработать, пока последующая отправка остается неподтвержденной. Храните состояния отдельно, чтобы было видно, какой уровень требует проверки. Элемент, найденный ранее, может устареть после навигации, диалога или изменения origin.

В Stagehand также есть привычные методы страницы, например переходы и locators. Это не превращает Stagehand v4 в Playwright: текущая вводная документация описывает управление через CDP и сообщает об отсутствии зависимости от Playwright и Puppeteer. Если проекту нужен жизненный цикл BrowserType.launch() из Playwright, используйте руководство по настройке Playwright и отдельный код запуска. Для примитивов Stagehand применяется его контракт подключения к браузеру.

Запуск и подключение являются разными операциями

Запуск создает процесс операционной системы. Launcher передает путь исполняемого файла, аргумент профиля, каталог пользовательских данных, endpoint отладки и сетевые параметры, которые получит процесс. Последующее CDP-подключение присоединяет клиент к уже работающему браузеру. В справочнике конфигурации браузера Stagehand описан localBrowser.launch() для локального процесса и localBrowser.connect() для существующего Chromium. В примере подключения используется URL CDP, а полученный браузер передается в Stagehand.create().

В BotBrowser профиль выбирается при старте процесса через --bot-profile. Это не инструкция Stagehand, не значение page.evaluate() и не настройка, которую может применить observe() после запуска. В документации BotBrowser для Playwright показано, где исполняемый файл и аргумент профиля попадают в запуск Playwright; принцип ответственности одинаков для любого launcher: процесс получает настройки до подключения Stagehand. В руководстве по профилям описаны выбор и обработка файлов.

Решение	Путь запуска	Путь подключения
Кто запускает Chromium?	Локальная фабрика Stagehand или внешний launcher	Сначала его запускает launcher под контролем оператора
Где выбирается исполняемый файл?	В параметрах запуска, поддерживаемых зафиксированной версией	В аргументах внешнего процесса до подключения Stagehand
Где передается --bot-profile?	Только если поддерживаемый API запуска передает аргументы браузеру	В аргументах процесса до открытия endpoint CDP
Что получает Stagehand?	Браузер, возвращенный локальным вызовом запуска	Браузер, подключенный к указанному URL CDP
Что проверяется отдельно?	Фактический процесс и его аргументы	Идентификатор процесса, endpoint и аргумент профиля

Подключение подходит, когда в окружении уже работает контролируемый процесс Chromium или отдельный supervisor управляет его созданием. При этом появляется строгая зависимость: Stagehand не подключится до готовности endpoint. Локальный запуск бывает проще, если параметры закрепленной версии покрывают все требования. Нельзя считать, что локальный helper принимает произвольный бинарный файл или флаг профиля лишь потому, что умеет запустить Chrome; проверьте типы конкретной версии.

Запустите контролируемый браузер до Stagehand

Запуск под контролем оператора делает конфигурацию явной. В форме shell ниже используются подстановочные переменные; это не запись о запуске и не доказательство, что конкретная сборка BotBrowser приняла параметры. Задайте значения в конфигурации окружения, выделяйте свободный loopback-порт для каждого запуска и передавайте одинаковый STAGEHAND_CDP_PORT лаунчеру и клиенту:

"$BOTBROWSER_EXEC_PATH" \
  --user-data-dir="$STAGEHAND_USER_DATA_DIR" \
  --remote-debugging-port="$STAGEHAND_CDP_PORT" \
  --bot-profile="$BOT_PROFILE_PATH"

--bot-profile выбирает файл профиля BotBrowser. --user-data-dir является отдельным каталогом данных Chromium, а не заменой зашифрованного профиля BotBrowser. Используйте новый отдельный каталог, если версия браузера требует его для удаленной отладки; не используйте клиентские данные для тестового запуска. CDP endpoint предоставляет привилегированное управление браузером, поэтому ограничьте его loopback, не публикуйте в общей сети и закройте процесс по окончании. В документации Chrome по удаленной отладке описаны интерфейс и граница безопасности.

После готовности процесса документированная форма подключения Stagehand остается короткой:

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

const cdpPort = process.env.STAGEHAND_CDP_PORT;
if (!cdpPort || !/^\d+$/.test(cdpPort)) {
  throw new Error('The launcher must assign a numeric CDP port');
}

const browser = await localBrowser.connect({
  cdpUrl: `http://127.0.0.1:${cdpPort}`,
});
const stagehand = await Stagehand.create({ browser });

const { data: actions } = await stagehand.observe('Find the read-only build marker');
if (actions.length !== 1) {
  throw new Error(`Expected one build-marker action; found ${actions.length}`);
}

await stagehand.act(actions[0]);
const { data } = await stagehand.extract({
  instruction: 'Read the build marker from the current page',
  schema: z.object({ build: z.string() }),
});
console.log(data.build);

Подключение и вызовы примитивов соответствуют текущей документации Stagehand v4; endpoint, fixture и установка пакетов зависят от окружения. Зафиксируйте версию Stagehand и сверяйте импорты и поля результата с ее справочником. Пример читает собственный fixture и не отправляет форму, не входит в учетную запись и не меняет удаленную запись. Это форма локальной интеграции, а не свидетельство, что код запускался здесь.

Выделяйте endpoint для одного запуска, а не используйте постоянный порт, который может принадлежать чужому браузеру. Если порт занят, нельзя незаметно подключаться к нему: адрес может вести к другому Chromium. Пусть launcher назначает и записывает endpoint, привязанный к localhost. Не выставляйте CDP на публичный интерфейс: любой доступный клиент получает управление браузером.

Выполните три примитива на fixture

Собственный fixture делает уровни наблюдаемыми без зависимости от публичного сайта. Он может показывать фиксированный идентификатор сборки и один безвредный элемент управления. Первая инструкция observe() должна указывать на этот элемент; выбранное действие только показывает маркер, а extract() возвращает его в небольшой схеме. Не используйте fixture с учетными данными, покупками, изменением учетной записи или удалением: это превратит проверку интеграции в поток авторизации.

Сохраняйте лишь несколько ожидаемых и наблюдаемых значений. Fixture может возвращать build: "stagehand-fixture-7"; запись может содержать эту строку, версию fixture, origin и имя схемы. Не нужно сохранять весь DOM, снимок с посторонним содержимым, cookies, локальное хранилище или полный trace модели. Короткая запись снижает случайное раскрытие данных и упрощает классификацию ошибки.

Fixture должен быть достаточно стабильным, чтобы отличать сбой подключения от проблемы страницы. Известный маркер подтверждает, что навигация достигла нужного локального origin. Кнопка только для чтения позволяет проверить observe() и act() без изменения состояния сервера. Небольшой JSON-объект проверяет extract() и схему. Версионируйте эти элементы вместе: если атрибут маркера изменился, а Chromium остался прежним, изменился контракт fixture, а не launcher.

Не используйте видимый странице user-agent как доказательство выбранного процесса или профиля. Видимое значение может быть полезно для собственной проверки, но не устанавливает, какой исполняемый файл открыл вкладку. И наоборот, путь процесса не доказывает, что нужный fixture отобразился. Процесс launcher, endpoint CDP и ответ fixture отвечают на разные вопросы и должны оставаться разными полями.

Fixture также помогает разделить состояние страницы и доступность действия. Если маркер появляется после выбора согласия, инструкция observe() не должна превращать это решение в обычный подготовительный клик. Зафиксируйте требование одобрения или создайте отдельный путь только для чтения. Стабильный тестовый контракт не оправдывает автоматическое изменение разрешений или данных.

Проверьте процесс и CDP target

Три проверки устанавливают разные факты. Сначала проверьте процесс launcher и сравните исполняемый файл и очищенные от секретов аргументы с объявленными значениями. Затем запросите локальный endpoint CDP и убедитесь, что отвечает ожидаемая служба отладки. В завершение откройте собственный fixture и прочитайте маркер сборки. Успех одной строки не заменяет остальные.

Проверка	Ожидаемое наблюдение	Чего это не устанавливает
Процесс launcher	Исполняемый файл совпадает с заданным путем BotBrowser и присутствует требуемый флаг профиля	Что зашифрованный профиль принят или породил ожидаемое значение страницы
Endpoint CDP	Указанный локальный URL возвращает метаданные браузера	Что endpoint принадлежит процессу из первой строки
Страница fixture	Stagehand видит ожидаемый origin и маркер сборки	Что сторонний сервис покажет ту же страницу или примет то же решение

Несовпадение останавливает поток. Если путь процесса другой, не продолжайте только потому, что endpoint отвечает. Если путь совпадает, но endpoint указывает на другой браузер, проверьте назначение порта и владельца процесса. Если оба совпадают, но маркера нет, проверьте маршрут fixture и жизненный цикл страницы, не меняйте значения профиля. Такой порядок не позволяет скрыть ошибку запуска повтором страницы.

Короткая запись может включать runId, зафиксированную версию Stagehand, очищенное имя исполняемого файла, несекретный ID профиля, локальный endpoint, сборку fixture, выбранный примитив и первую ошибку. Не записывайте содержимое зашифрованного профиля, токены, учетные данные прокси или абсолютный путь с ID клиента. Такая запись полезна, только если различает заданное и наблюдаемое значение.

Метаданные CDP не являются сертификатом идентичности браузера. Если несколько процессов могут слушать или перенаправлять endpoint, сопоставьте URL с PID и проверьте локальные аргументы процесса. Туннель, перенаправление порта контейнера, прокси разработки или старый браузер могут направить клиента к другому процессу. Выдавайте отдельный endpoint на запуск и завершайте устаревшие процессы до повторного использования порта.

Важно учитывать жизненный цикл браузера. Закройте соединение Stagehand после проверки только для чтения, а процесс браузера закрывайте лишь тогда, когда этот запуск им владеет. Документация Stagehand различает запущенные им браузеры и браузеры, к которым подключился вызывающий код. Подключенный клиент не должен считать, что вправе остановить процесс: supervisor может использовать его для другой контролируемой задачи.

Таблица сбоев и восстановления

Наблюдение	Вероятный уровень	Следующая проверка	Условие остановки
CDP отклоняет соединение	Запуск браузера или назначение порта	Проверьте статус launcher и назначенный порт	Не запускайте незаметно другой браузер
CDP подключается, но путь процесса неожиданный	Неверный endpoint или устаревший процесс	Сопоставьте endpoint с записанным PID	Завершите запуск до действий со страницей
Процесс верный, но аргумента профиля нет	Конфигурация launcher	Проверьте сборку аргументов до запуска	Не утверждайте, что профиль выбран
Флаг есть, но fixture отличается	Профиль, fixture или приложение	Сравните совместимость профиля и версию fixture отдельно	Не изменяйте значения страницы ради совпадения
observe() не возвращает кандидатов	Состояние страницы или инструкция	Проверьте fixture и видимый элемент	Не расширяйте инструкцию до другого действия
act() вернул результат, но fixture не изменился	Результат действия или состояние приложения	Прочитайте маркер повторно и проверьте результат	Не заявляйте удаленное изменение без доказательств
extract() не проходит схему	Вывод страницы или контракт схемы	Сравните видимые значения fixture с ожидаемой схемой	Не ослабляйте схему незаметно, сохраняйте минимум данных
Браузер отключился во время действия	Жизненный цикл процесса или удаленный результат	Проверьте fixture либо идемпотентный статус перед повтором	Не повторяйте вслепую действие с последствиями

Восстановление начинается с первого уровня отказа. Отклоненное соединение не исправляется изменением схемы извлечения. Верный endpoint, подключенный не к тому процессу, не исправляется расширением инструкции. Отсутствующий аргумент профиля исправляется в конфигурации launcher, после чего нужен новый процесс и новый ID запуска. Если удаленное изменение могло уйти до отключения, проверьте его через идемпотентный статус или передайте ответственному оператору; не запускайте действие заново автоматически.

В руководстве browser-use описаны точки одобрения для другого агентного цикла. Обзор обнаружения автоматизации посвящен общим сигналам. Ни один из них не заменяет специфичное для Stagehand различие между результатом примитива, подключением CDP и исполняемым файлом/профилем, выбранными до подключения.

Что остается вне Stagehand

Stagehand предоставляет API автоматизации браузера; приложение по-прежнему отвечает за разрешение задач, выбор учетной записи, сетевую маршрутизацию, секреты, хранение данных и одобрение значимых действий. Подключенный браузер может быть технически готов, хотя задача неуместна или ее назначение уже изменилось. Политика должна находиться в приложении, вызывающем Stagehand, а не в инструкции, которую агент способен переписать.

Выбор профиля оставляйте в проверенной конфигурации launcher. Агенту не следует перечислять произвольные файлы профилей, печатать их содержимое или выбирать учетную запись по тексту страницы. Launcher может разрешить одобренный ID и передать путь браузеру. В записи можно хранить несекретную метку профиля и версию конфигурации, не копируя зашифрованный файл или его содержимое.

Сетевой маршрут является отдельным параметром. Аргумент профиля не доказывает, по какому маршруту прошел запрос, а endpoint CDP не сообщает решение прикладного уровня о разрешениях. Если потоку нужен конкретный маршрут, настройте его во внешнем слое и проверяйте разрешенной диагностикой. Не приписывайте Stagehand маршрут, язык или состояние учетной записи, если окружающая система не передала это значение с указанием источника.

То же разделение относится к классификации сторонним сервисом. Успешный act() означает, что взаимодействие браузера вернуло результат; успешный extract() означает, что вернулась заданная форма данных. Ни один из результатов не гарантирует принятие сессии, категорию детектора или бизнес-результат приложения. BotBrowser предоставляет управляемый браузер, но не обещает результат стороннего сервиса.

Когда поток доходит до учетных данных, согласия, оплаты, удаления, изменения разрешений, публикации или необратимой отправки, приостановите его на уровне приложения для решения оператора. Для решения нужны origin назначения, тип действия и видимые параметры; секреты не должны попадать в trace модели. Это граница политики приложения, а не поведение observe(), act() или extract().

Вопросы

Использует ли Stagehand v4 Playwright внутри?

В актуальном введении Stagehand v4 описано управление браузером через CDP и сказано, что зависимости Playwright и Puppeteer нет. API страницы может быть знакомо пользователям Playwright, но это не то же самое, что жизненный цикл запуска BrowserType.

Может ли Stagehand выбрать профиль BotBrowser после подключения?

Нет. Профиль передается процессу при запуске. Примитивы страницы работают после подключения и не меняют аргументы задним числом. Передайте одобренный --bot-profile в конфигурацию launcher до открытия endpoint CDP.

Доказывает ли успешное CDP-подключение, что запущен нужный браузер?

Нет. Оно доказывает, что endpoint ответил. Сопоставьте его с PID и путем исполняемого файла, проверьте очищенные аргументы и отдельно прочитайте собственный fixture.

Гарантирует ли интеграция результат детектора или сайта?

Нет. Действия Stagehand и контролируемая конфигурация браузера не гарантируют классификацию, принятие или бизнес-результат стороннего сервиса. Эти результаты не входят в проверку запуска.

Источники

• Введение в Stagehand v4
• Stagehand act()
• Stagehand extract()
• Stagehand observe()
• Конфигурация браузера Stagehand
• Удаленная отладка Chrome
• Chrome DevTools Protocol
• Настройка Playwright в BotBrowser
• Флаги CLI BotBrowser

Практический вывод

Держите примитивы Stagehand отдельно от создания процесса. Выберите исполняемый файл BotBrowser и профиль в launcher, откройте только локальный endpoint CDP и подключите Stagehand к уже запущенному браузеру. Отдельно проверьте процесс, endpoint и собственный fixture; при расхождении остановитесь. Это ограниченная проверка интеграции, а не утверждение о действительности профиля, разрешении задачи или решении стороннего сервиса.