stagehand
v1.3.0
Структура просмотра веб -сайта ИИ была сосредоточена на простоте и расширяемости.
Примечание
В настоящее время Stagehand доступен в качестве раннего релиза, и мы активно ищем отзывы сообщества. Пожалуйста, присоединяйтесь к нашему сообществу Slack, чтобы оставаться в курсе последних событий и предоставить обратную связь.
StageHand является преемником AI, преемником драматурга, предлагающим три простых API ( act , extract и observe ), которые предоставляют строительные блоки для веб-автоматизации, управляемой естественным языком.
Цель StageHand - обеспечить легкую, настраиваемую структуру, без чрезмерно сложных абстракций, а также модульной поддержки для различных моделей и поставщиков моделей. Это не закажет вам пиццу, но это поможет вам надежно автоматизировать сеть.
Каждая функция ступени принимает атомную инструкцию, такую как act("click the login button") или extract("find the red shoes") , генерирует соответствующий код драматурга для выполнения этой инструкции и выполняет ее.
Инструкции должны быть атомными для повышения надежности, и планирование шага должно рассматриваться агентом более высокого уровня. Вы можете использовать observe() , чтобы получить предложенный список действий, которые можно предпринять на текущей странице, а затем использовать их, чтобы заземлить ваши подсказки по планированию шага.
StageHand находится с открытым исходным кодом и поддерживается командой BrowserBase. Мы считаем, что, позволяя большему количеству разработчиков создавать надежные веб -автоматизации, мы расширим рынок разработчиков, которые извлекают выгоду из нашей безголовной инфраструктуры браузера. Это та структура, которую мы хотели бы иметь, во время разжигания наших собственных приложений, и мы рады поделиться ею с вами.
Мы также устанавливаем ZOD для питания
npm install @browserbasehq/stagehand zodВам нужно будет предоставить свой ключ API для поставщика моделей, которого вы хотели бы использовать. Поставщик моделей по умолчанию - OpenAI, но вы также можете использовать антропные или другие. Более подробную информацию о поддерживаемых моделях можно найти в ссылке API.
Убедитесь, что в вашей местной среде доступен ключ OpenAI или ключ API API.
export OPENAI_API_KEY=sk-...
export ANTHROPIC_API_KEY=sk-...
Если вы планируете запустить браузер локально, вам также необходимо установить зависимости браузера Playwright.
npm exec playwright installТогда вы можете создать сценический экземпляр, как:
import { Stagehand } from "@browserbasehq/stagehand" ;
import { z } from "zod" ;
const stagehand = new Stagehand ( {
env : "LOCAL" ,
} ) ;Если вы планируете удаленно запустить браузер, вам нужно будет установить ключ API BrowserBase и идентификатор проекта.
export BROWSERBASE_API_KEY=...
export BROWSERBASE_PROJECT_ID=... import { Stagehand } from "@browserbasehq/stagehand" ;
import { z } from "zod" ;
const stagehand = new Stagehand ( {
env : "BROWSERBASE" ,
enableCaching : true ,
} ) ; await stagehand . init ( ) ;
await stagehand . page . goto ( "https://github.com/browserbase/stagehand" ) ;
await stagehand . act ( { action : "click on the contributors" } ) ;
const contributor = await stagehand . extract ( {
instruction : "extract the top contributor" ,
schema : z . object ( {
username : z . string ( ) ,
url : z . string ( ) ,
} ) ,
} ) ;
console . log ( `Our favorite contributor is ${ contributor . username } ` ) ;Этот простой фрагмент откроет браузер, перейти к репо сценическому репо и зарегистрирует главного участника.
Stagehand()Этот конструктор используется для создания экземпляра StageHand.
Аргументы:
env : 'LOCAL' или 'BROWSERBASE' . По умолчанию в 'BROWSERBASE' .modelName : (необязательно) Строка AvailableModel для указания модели по умолчанию для использования.modelClientOptions : (необязательно) Параметры конфигурации для клиента модели.enableCaching : boolean , который позволяет кэшировать ответы LLM. При установке true запросы LLM будут кэшированы на диске и повторно используются для идентичных запросов. По умолчанию false .headless : boolean , который определяет, работает ли браузер в режиме без головы. По умолчанию false . Когда Env установлен в BROWSERBASE , это будет игнорировано.domSettleTimeoutMs : целое integer , которое указывает тайм -аут в миллисекундах для ожидания дома. По умолчанию до 30000 (30 секунд).apiKey : (необязательно) Ваш ключ API BrowserBase. По умолчанию в BROWSERBASE_API_KEY Enviration Variable.projectId : (необязательно) идентификатор проекта вашего браузербазы. По умолчанию в BROWSERBASE_PROJECT_ID переменную среды.browserBaseSessionCreateParams : Параметры конфигурации для создания новых сеансов BrowserBase.browserbaseResumeSessionID : идентификатор существующего сеанса браузербазы для возобновления.logger : функция, которая обрабатывает сообщения журнала. Полезно для пользовательских реализаций ведения журнала.verbose : целое integer , которое обеспечивает несколько уровней регистрации во время автоматизации:0 : ограничено отсутствием регистрации1 : журнал на уровне SDK2 : LLM-клиентdebugDom : boolean , которая привлекает ограничивающие ящики вокруг элементов, представленных в LLM во время автоматизации.Возвращает:
Stagehand , настроенный с указанными параметрами.Пример:
// Basic usage
const stagehand = new Stagehand ( ) ;
// Custom configuration
const stagehand = new Stagehand ( {
env : "LOCAL" ,
verbose : 1 ,
headless : true ,
enableCaching : true ,
logger : ( logLine ) => {
console . log ( `[ ${ logLine . category } ] ${ logLine . message } ` ) ;
} ,
} ) ;
// Resume existing Browserbase session
const stagehand = new Stagehand ( {
env : "BROWSERBASE" ,
browserbaseResumeSessionID : "existing-session-id" ,
} ) ;init() init() асинхронно инициализирует экземпляр сцены. Это должно быть вызвано перед любыми другими методами.
Аргументы:
modelName : (необязательно) Строка AvailableModel для указания модели для использования. Это будет использоваться для всех других методов, если только переопределить.modelClientOptions : (необязательно) параметры конфигурации для клиента моделиdomSettleTimeoutMs : (необязательно) тайм -аут в миллисекундах для ожидания домаВозвращает:
Promise , которое разрешается объекту, содержащим:debugUrl : string представляющая URL для живой отладки. Это доступно только при использовании браузера браузербазы.sessionUrl : string представляющая URL сеанса. Это доступно только при использовании браузера браузербазы.Пример:
await stagehand . init ( { modelName : "gpt-4o" } ) ; act() act() позволяет StageHand взаимодействовать с веб -страницей. Предоставьте такое action , как "search for 'x'" , или "select the cheapest flight presented" (малые атомные цели выполняют лучшее).
Аргументы:
action : string , описывающая действие для выполненияmodelName : (необязательно) Строка AvailableModel для указания модели для использованияmodelClientOptions : (необязательно) параметры конфигурации для клиента моделиuseVision : (необязательно) boolean или "fallback" чтобы определить, следует ли использовать обработку на основе зрения. По умолчанию "fallback"variables : (необязательно) Record<string, string> переменных для использования в действии. Переменные в строке действия ссылаются с использованием %variable_name%domSettleTimeoutMs : (необязательно) тайм -аут в миллисекундах для ожидания домаВозвращает:
Promise , которое разрешается объекту, содержащим:success : boolean указывающий, было ли действие успешно завершено.message : string предоставляющая подробную информацию о выполнении действия.action : string , описывающая выполненное действие.Пример:
// Basic usage
await stagehand . act ( { action : "click on add to cart" } ) ;
// Using variables
await stagehand . act ( {
action : "enter %username% into the username field" ,
variables : {
username : "[email protected]" ,
} ,
} ) ;
// Multiple variables
await stagehand . act ( {
action : "fill in the form with %username% and %password%" ,
variables : {
username : "john.doe" ,
password : "secretpass123" ,
} ,
} ) ; extract() extract() захватывает структурированный текст с текущей страницы с использованием ZOD. Учитывая инструкции и schema , вы получите структурированные данные. В отличие от некоторых библиотек извлечения, StageHand может извлечь любую информацию на странице, а не только основное содержимое статьи.
Аргументы:
instruction : string , предоставляющая инструкции для извлеченияschema : z.AnyZodObject определяющий структуру данных для извлеченияmodelName : (необязательно) Строка AvailableModel для указания модели для использованияmodelClientOptions : (необязательно) параметры конфигурации для клиента моделиdomSettleTimeoutMs : (необязательно) тайм -аут в миллисекундах для ожидания домаВозвращает:
Promise , которое разрешается структурированным данным, как определено предоставленной schema .Пример:
const price = await stagehand . extract ( {
instruction : "extract the price of the item" ,
schema : z . object ( {
price : z . number ( ) ,
} ) ,
} ) ; observe()Примечание
observe() в настоящее время оценивает только первый кусок на странице.
observe() используется для получения списка действий, которые можно предпринять на текущей странице. Это полезно для добавления контекста к своему этапу планирования, или если вы не уверены в том, на какой странице вы.
Если вы ищете определенный элемент, вы также можете пройти в инструкции для наблюдения через: observe({ instruction: "{your instruction}"}) .
Аргументы:
instruction : (необязательно) string , предоставляющая инструкции для наблюдения. По умолчанию «найти действия, которые можно выполнить на этой странице».modelName : (необязательно) Строка AvailableModel для указания модели для использованияmodelClientOptions : (необязательно) параметры конфигурации для клиента моделиuseVision : (необязательно) boolean , чтобы определить, следует ли использовать обработку на основе зрения. По умолчанию falsedomSettleTimeoutMs : (необязательно) тайм -аут в миллисекундах для ожидания домаВозвращает:
Promise , которое разрешается множеством объектов, содержащих:selector : string , представляющая селектор элементовdescription : string , описывающая возможное действиеПример:
const actions = await stagehand . observe ( ) ; page и context page и context - это случаи Page Playwright и BrowserContext соответственно. Используйте эти методы для взаимодействия с экземпляром драматурга, который использует StageHand. Чаще всего вы используете page.goto() для перемещения в URL.
await stagehand . page . goto ( "https://github.com/browserbase/stagehand" ) ;log() log() используется для печати сообщения в консоли браузера. Эти сообщения будут сохраняться в журналах сеанса браузербазы и могут использоваться для отладки сеансов после их завершения.
Убедитесь, что уровень журнала выше уровня словеса, который вы устанавливаете при инициализации экземпляра StageHand.
stagehand . log ( "Hello, world!" ) ; StageHand использует общую клиентскую архитектуру LLM для поддержки различных языковых моделей от разных поставщиков. Эта конструкция обеспечивает гибкость, что позволяет интеграции новых моделей с минимальными изменениями в основную систему. Различные модели работают лучше для разных задач, поэтому вы можете выбрать модель, которая наилучшим образом соответствует вашим потребностям.
StageHand в настоящее время поддерживает следующие модели от Openai и Anpropic:
Openai модели:
gpt-4ogpt-4o-minigpt-4o-2024-08-06Антропические модели:
claude-3-5-sonnet-latestclaude-3-5-sonnet-20240620claude-3-5-sonnet-20241022 Эти модели могут быть указаны при инициализации экземпляра Stagehand или при вызовах таких методов, как act() и extract() .
SDK имеет две основные этапы:
StageHand использует комбинацию методов для подготовки DOM.
Шаги обработки DOM выглядят следующим образом:
В то время как LLMS продолжит увеличивать длину окна контекста и уменьшать задержку, предоставление любой системе рассуждений меньше, чтобы думать, чтобы сделать ее более надежным. В результате обработка DOM выполняется в кусках, чтобы сохранить контекст небольшим вызовом для вывода. Для того, чтобы купить, SDK считает элемент кандидата, который начинается в разделе Viewport, является частью этого куски. В будущем будет добавлена заполнение, чтобы убедиться, что отдельный кусок не испытывает недостатка в соответствующем контексте. Посмотрите на эту диаграмму, как она выглядит:
Методы act() и observe() могут занять флаг useVision . Если это установлено в true , LLM будет предоставлен аннотированный скриншот текущей страницы, чтобы определить, какие элементы действовать. Это полезно для сложных DOMS, о котором LLM испытывает трудности с рассуждением, даже после обработки и блюд. По умолчанию этот флаг устанавливается на "fallback" , что означает, что если LLM не сможет успешно идентифицировать один элемент, StageHand повторяет попытку с использованием зрения.
Теперь у нас есть список элементов кандидатов и способ их выбрать. Мы можем представить эти элементы с дополнительным контекстом в LLM для извлечения или действия. Несмотря на то, что он в больших масштабах представлял «пронумерованный список элементов», направляет модель не рассматривать контекст как полный DOM, а как список связанных, но независимых элементов для работы.
В случае действия мы просим LLM написать метод драматурга, чтобы сделать правильное дело. В нашем ограниченном тестировании синтаксис драматурга гораздо более эффективен, чем полагаться на встроенные API -интерфейсы JavaScript, возможно, из -за токенизации.
Наконец, мы используем LLM, чтобы написать будущие инструкции, чтобы помочь управлять своим прогрессом и целями при работе в кусках.
Ниже приведен пример того, как извлечь список компаний с веб -сайта AI Grant, используя как StageHand, так и драматург.
Подсказка сцены является более буквальным и атомным, чем другие рамки более высокого уровня, включая агентские рамки. Вот несколько рекомендаций, которые помогут вам создать эффективные подсказки:
await stagehand . act ( { action : "click the login button" } ) ;
const productInfo = await stagehand . extract ( {
instruction : "find the red shoes" ,
schema : z . object ( {
productName : z . string ( ) ,
price : z . number ( ) ,
} ) ,
} ) ;Вместо того, чтобы объединять действия:
// Avoid this
await stagehand . act ( { action : "log in and purchase the first item" } ) ;Разделите их на отдельные шаги:
await stagehand . act ( { action : "click the login button" } ) ;
// ...additional steps to log in...
await stagehand . act ( { action : "click on the first item" } ) ;
await stagehand . act ( { action : "click the purchase button" } ) ;observe() , чтобы получить действенные предложения с текущей страницы const actions = await stagehand . observe ( ) ;
console . log ( "Possible actions:" , actions ) ; // Too vague
await stagehand . act ( { action : "find something interesting on the page" } ) ; // Avoid combining actions
await stagehand . act ( { action : "fill out the form and submit it" } ) ; // Outside Stagehand's scope
await stagehand . act ( { action : "book the cheapest flight available" } ) ;Следуя этим руководящим принципам, вы повысите надежность и эффективность ваших веб -автоматов с StageHand. Помните, что сцены превосходны в выполнении точных, четко определенных действий, поэтому поддержание атомных инструкций приведет к наилучшим результатам.
Мы оставляем агентское поведение в агентских системах более высокого уровня, которые могут использовать StageHand в качестве инструмента.
На высоком уровне мы сосредоточены на повышении надежности, скорости и стоимости в этом порядке приоритета.
Вы можете увидеть дорожную карту здесь. Хотите внести свой вклад? Читайте!
Примечание
Мы высоко ценим вклад в StageHand! Для поддержки или обзора кода, пожалуйста, присоединяйтесь к нашему сообществу Slack.
Во -первых, клонировать репо
git clone [email protected]:browserbase/stagehand.gitЗатем установите зависимости
npm install Убедитесь, что у вас есть файл .env , как задокументирован выше в разделе «Начало работы».
Затем запустите пример сценария npm run example .
Хороший цикл развития:
Вам понадобится ключ API Braintrust для запуска Evals
BRAINTRUST_API_KEY = " " После этого вы можете запустить Eval, используя npm run evals
Запуск всех Evals может занять некоторое время. У нас есть удобный сценарий example.ts
Вы можете запустить npm run example для выполнения и итерации на оценке, которую вы в настоящее время разрабатываете.
Чтобы добавить новую модель в StageHand, следуйте этим шагам:
Определите модель : добавьте новое имя модели в тип AvailableModel в файле LLMProvider.ts . Это гарантирует, что модель распознается системой.
Сопоставьте модель поставщику : обновите modelToProviderMap в классе LLMProvider , чтобы связать новую модель с соответствующим поставщиком. Это отображение имеет решающее значение для определения того, какой клиент использовать.
Реализуйте клиента : если новая модель требует нового клиента, реализуйте класс, который придерживается интерфейса LLMClient . Этот класс должен определять все необходимые методы, такие как createChatCompletion .
Обновите метод getClient : изменить метод getClient в классе LLMProvider , чтобы вернуть экземпляр нового клиента, когда запрошенная новая модель.
StageHand использует TSUP для построения SDK и Vanilla esbuild для создания сценариев, которые работают в DOM.
npm run buildnpm pack , чтобы получить тарбол для распространения Этот проект в значительной степени полагается на драматурга как устойчивую основу для автоматизации Интернета. Это также было бы невозможно без удивительных техник и открытий, сделанных Tarsier и Fuji-Web.
Джереми Пресс написал оригинальный MVP StageHand и продолжает оставаться главным союзником проекта.
Лицензирован по лицензии MIT.
Copyright 2024 Browserbase, Inc.
