stagehand
v1.3.0
AI 웹 브라우징 프레임 워크는 단순성과 확장성에 중점을 둡니다.
메모
Stagehand 현재 조기 릴리스로 제공되며 커뮤니티의 피드백을 적극적으로 찾고 있습니다. Slack Community에 가입하여 최신 개발에 대한 업데이트를 유지하고 피드백을 제공하십시오.
Stagehand는 극작가의 AI 기반 후속 인으로 자연어 구동 웹 자동화를위한 빌딩 블록을 제공하는 3 개의 간단한 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이지만 Anthropic 또는 다른 사람들도 사용할 수도 있습니다. 지원되는 모델에 대한 자세한 내용은 API 참조를 참조하십시오.
지역 환경에서 OpenAI API 키 또는 인류 API 키에 액세스 할 수 있는지 확인하십시오.
export OPENAI_API_KEY=sk-...
export ANTHROPIC_API_KEY=sk-...
브라우저를 로컬로 실행하려는 경우 극작가의 브라우저 종속성을 설치해야합니다.
npm exec playwright install그런 다음 SO와 같은 스테이지 핸드 인스턴스를 만들 수 있습니다.
import { Stagehand } from "@browserbasehq/stagehand" ;
import { z } from "zod" ;
const stagehand = new Stagehand ( {
env : "LOCAL" ,
} ) ;브라우저를 원격으로 실행하려면 Browserbase API 키 및 프로젝트 ID를 설정해야합니다.
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 Repo로 이동 한 후 최상위 기고자를 기록합니다.
Stagehand()이 생성자는 Stagehand 인스턴스를 만드는 데 사용됩니다.
논쟁 :
env : 'LOCAL' 또는 'BROWSERBASE' . 기본값은 'BROWSERBASE' 입니다.modelName : (선택 사항) 사용할 수있는 기본 모델을 지정하려면 AvailableModel 문자열입니다.modelClientOptions : (선택 사항) 모델 클라이언트를위한 구성 옵션.enableCaching : LLM 응답을 캐싱 할 수있는 boolean . true 로 설정되면 LLM 요청은 디스크에 캐시되고 동일한 요청을 위해 재사용됩니다. 기본값으로 false .headless : 브라우저가 헤드리스 모드로 실행되는지 여부를 결정하는 boolean . 기본값으로 false . ENV가 BROWSERBASE 로 설정되면 무시됩니다.domSettleTimeoutMs : DOM이 정착되기를 기다리기 위해 시간 초과를 밀리 초 단위로 지정하는 integer . 기본값은 30000 (30 초)까지.apiKey : (선택 사항) Browserbase API 키. 기본값으로 BROWSERBASE_API_KEY 환경 변수.projectId : (선택 사항) BrowserBase Project ID. 기본값은 BROWSERBASE_PROJECT_ID 환경 변수로 나타납니다.browserBaseSessionCreateParams : 새로운 브라우저베이스 세션 생성을위한 구성 옵션.browserbaseResumeSessionID : 이력서에 대한 기존 BrowserBase 세션의 ID.logger : 로그 메시지를 처리하는 함수. 사용자 정의 로깅 구현에 유용합니다.verbose : 자동화 중에 여러 수준의 로깅을 가능하게하는 integer :0 : 벌목이없는 것으로 제한됩니다1 : SDK 레벨 로깅2 : LLM-Client 레벨 로깅 (대부분의 세분화)debugDom : 자동화 중에 LLM에 제시된 요소 주위에 경계 상자를 그린 boolean .보고:
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() stagehand 인스턴스를 비동기로 초기화합니다. 다른 방법보다 먼저 호출해야합니다.
논쟁 :
modelName : (선택 사항) 사용 할 모델을 지정하려면 AvailableModel 문자열입니다. 이것은 재정의하지 않는 한 다른 모든 방법에 사용됩니다.modelClientOptions : (선택 사항) 모델 클라이언트를위한 구성 옵션domSettleTimeoutMs : (선택 사항) DOM이 정착되기를 기다리는 밀리 초의 시간 초과보고:
Promise :debugUrl : 라이브 디버깅의 URL을 나타내는 string . 브라우저베이스 브라우저를 사용할 때만 사용할 수 있습니다.sessionUrl : 세션 URL을 나타내는 string . 브라우저베이스 브라우저를 사용할 때만 사용할 수 있습니다.예:
await stagehand . init ( { modelName : "gpt-4o" } ) ; act() act() 는 StageHand가 웹 페이지와 상호 작용할 수 있도록합니다. "search for 'x'" 또는 "select the cheapest flight presented" 과 같은 action 를 제공하십시오 (작은 원자 목표가 가장 잘 수행됨).
논쟁 :
action : 수행 할 동작을 설명하는 stringmodelName : (선택 사항) 사용 할 모델을 지정하려면 AvailableModel 문자열modelClientOptions : (선택 사항) 모델 클라이언트를위한 구성 옵션useVision : (선택 사항) 시력 기반 처리를 사용해야하는지 확인하기위한 boolean 또는 "fallback" . "fallback" 의 기본값variables : (선택 사항) 작업에 사용할 Record<string, string> 변수. 액션 문자열의 변수는 %variable_name% 사용하여 참조됩니다.domSettleTimeoutMs : (선택 사항) DOM이 정착되기를 기다리는 밀리 초의 시간 초과보고:
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 : 추출을위한 지침을 제공하는 stringschema : z.AnyZodObject 추출 할 데이터의 구조 정의modelName : (선택 사항) 사용 할 모델을 지정하려면 AvailableModel 문자열modelClientOptions : (선택 사항) 모델 클라이언트를위한 구성 옵션domSettleTimeoutMs : (선택 사항) DOM이 정착되기를 기다리는 밀리 초의 시간 초과보고:
schema 에 의해 정의 된대로 구조화 된 데이터로 해결되는 Promise .예:
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 : (선택 사항) DOM이 정착되기를 기다리는 밀리 초의 시간 초과보고:
Promise :selector : 요소 선택기를 나타내는 stringdescription : 가능한 조치를 설명하는 string예:
const actions = await stagehand . observe ( ) ; page 및 context page 와 context 각각 극작가 Page 와 BrowserContext 의 인스턴스입니다. 이 방법을 사용하여 Stagehand가 사용하는 극작가 인스턴스와 상호 작용하십시오. 가장 일반적으로 page.goto() 사용하여 URL로 이동합니다.
await stagehand . page . goto ( "https://github.com/browserbase/stagehand" ) ;log() log() 브라우저 콘솔에 메시지를 인쇄하는 데 사용됩니다. 이 메시지는 Browserbase 세션 로그에 유지되며 세션이 완료된 후에 세션을 디버그하는 데 사용할 수 있습니다.
로그 레벨이 Stagehand 인스턴스를 초기화 할 때 설정 한 장점 수준 이상인지 확인하십시오.
stagehand . log ( "Hello, world!" ) ; Stagehand는 일반적인 LLM 클라이언트 아키텍처를 활용하여 다른 공급자의 다양한 언어 모델을 지원합니다. 이 설계를 통해 유연성을 제공하여 핵심 시스템을 최소화하여 새로운 모델을 통합 할 수 있습니다. 다른 모델은 다른 작업에 더 잘 작동하므로 요구에 가장 적합한 모델을 선택할 수 있습니다.
Stagehand는 현재 Openai 및 Anthropic의 다음 모델을 지원합니다.
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 처리 단계는 다음과 같이 보입니다.
LLM은 컨텍스트 창 길이를 계속 증가시키고 대기 시간을 줄이려면 모든 추론 시스템을 적용 할 수있는 것들을 덜 생각하면 더 안정적으로 만들어야합니다. 결과적으로, DOM 처리는 추론 당 컨텍스트를 작게 유지하기 위해 청크로 수행됩니다. 청크를하기 위해 SDK는 뷰포트 섹션에서 시작하는 후보 요소를 해당 청크의 일부로 간주합니다. 앞으로, 패딩이 추가되어 개별 청크가 관련 컨텍스트가 부족하지 않도록합니다. 모양이 어떻게 보이는지이 다이어그램을 참조하십시오.
act() 및 observe() 메소드는 useVision 플래그를 취할 수 있습니다. 이것이 true 로 설정되면 LLM에는 현재 페이지의 주석이 달린 스크린 샷이 제공되어 수행 할 요소를 식별합니다. 이것은 LLM이 처리 및 청크 후에도 추론하는 데 어려움을 겪는 복잡한 DOM에 유용합니다. 기본적 으로이 플래그는 "fallback" 으로 설정되어 있습니다. 즉, LLM이 단일 요소를 성공적으로 식별하지 못하면 StageHand는 비전을 사용하여 시도를 다시 시도합니다.
이제 후보 요소 목록과이를 선택하는 방법이 있습니다. 추출 또는 행동을 위해 이러한 요소를 LLM에 추가 컨텍스트로 제시 할 수 있습니다. 대규모로 테스트되지는 않지만 "번호가 매겨진 요소 목록"을 제시하면 모델이 컨텍스트를 전체 DOM으로 취급하지 않고 관련이지만 독립적 인 요소의 목록으로 처리하도록 안내합니다.
행동의 경우, 우리는 LLM에 올바른 일을하기 위해 극작가 방법을 작성하도록 요청합니다. 제한된 테스트에서 극작가 구문은 토큰 화으로 인해 JavaScript API에 내장 된 것보다 훨씬 효과적입니다.
마지막으로, 우리는 LLM을 사용하여 미래의 지침을 작성하여 덩어리에서 운영 할 때 진행 상황과 목표를 관리하는 데 도움이됩니다.
아래는 Stagehand 및 Playwright를 사용하여 AI Grant 웹 사이트에서 회사 목록을 추출하는 방법의 예입니다.
Promping 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를 도구로 사용할 수있는 상위 수준의 에이전트 시스템에 에이전트 행동을 남겨 둡니다.
높은 수준에서 우리는 우선 순위의 신뢰성, 속도 및 비용을 개선하는 데 중점을 둡니다.
여기 로드맵을 볼 수 있습니다. 기여를 원하십니까? 계속 읽어!
메모
우리는 Stagehand에 대한 기여도를 높이 평가합니다! 지원 또는 코드 검토를 위해 슬랙 커뮤니티에 가입하십시오.
먼저 레포를 복제하십시오
git clone [email protected]:browserbase/stagehand.git그런 다음 종속성을 설치하십시오
npm install 시작 섹션에 위에서 문서화 된 .env 파일이 있는지 확인하십시오.
그런 다음 예제 스크립트 npm run example 실행하십시오.
좋은 개발 루프는 다음과 같습니다.
evals를 실행하려면 Braintrust API 키가 필요합니다
BRAINTRUST_API_KEY = " " 그런 다음 npm run evals 사용하여 Eval을 실행할 수 있습니다.
모든 eval을 실행하는 데 시간이 걸릴 수 있습니다. 우리는 편의 스크립트 example.ts 있습니다. 모든 EVAL 세트에 추가하기 전에 새로운 단일 평가를 개발할 수 있습니다.
npm run example 실행하여 현재 개발중인 평가를 실행하고 반복 할 수 있습니다.
StageHand에 새 모델을 추가하려면 다음을 수행하십시오.
모델 정의 : LLMProvider.ts 파일에서 AvailableModel 유형에 새 모델 이름을 추가하십시오. 이를 통해 모델이 시스템에 의해 인식되도록합니다.
모델을 제공자에게 매핑하십시오 : LLMProvider 클래스의 modelToProviderMap 업데이트하여 새 모델을 해당 제공자와 연결하십시오. 이 매핑은 사용할 클라이언트를 결정하는 데 중요합니다.
클라이언트 구현 : 새 모델에 새 클라이언트가 필요한 경우 LLMClient 인터페이스를 준수하는 클래스를 구현하십시오. 이 클래스는 createChatCompletion 과 같은 모든 필요한 방법을 정의해야합니다.
getClient 메소드 업데이트 : LLMProvider 클래스에서 getClient 메소드를 수정하여 새 모델이 요청되면 새 클라이언트의 인스턴스를 반환합니다.
Stagehand는 TSUP를 사용하여 SDK 및 Vanilla esbuild 구축하여 DOM에서 실행되는 스크립트를 작성합니다.
npm run build 실행하십시오npm pack 실행하여 배포를 위해 타르 볼을 얻습니다 이 프로젝트는 웹을 자동화하기위한 탄력적 인 백본으로 극작가에 크게 의존합니다. 또한 Tarsier와 Fuji-Web가 만든 멋진 기술과 발견 없이는 불가능합니다.
Jeremy Press는 Stagehand의 원래 MVP를 썼으며 프로젝트의 주요 동맹국입니다.
MIT 라이센스에 따라 라이센스.
저작권 2024 Browserbase, Inc.
