stagehand
v1.3.0
AI Web瀏覽框架的重點是簡單性和可擴展性。
筆記
Stagehand目前可作為早期版本提供，我們正在積極尋求社區的反饋。請加入我們的Slack社區，以了解最新發展並提供反饋。
StageHand是劇作家的AI驅動的繼任者，提供了三個簡單的API（ act ， extract和observe ），可為自然語言驅動的Web自動化提供構建塊。
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-...
如果您打算本地運行瀏覽器，則還需要安裝劇作家的瀏覽器依賴項。
npm exec playwright install然後，您可以創建一個類似的舞台實例：
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()該構造函數用於創建一個舞台的實例。
參數：
env ： 'LOCAL'或'BROWSERBASE' 。默認為'BROWSERBASE' 。modelName ：（可選）一個AvailableModel字符串來指定要使用的默認模型。modelClientOptions ：（可選）模型客戶端的配置選項。enableCaching ：一個boolean ，可以緩存LLM響應。設置為true時，LLM請求將在磁盤上緩存，並重新用於相同的請求。默認為false 。headless ：確定瀏覽器是否在無頭模式下運行的boolean 。默認為false 。當設置設置為BROWSERBASE時，這將被忽略。domSettleTimeoutMs ：一個integer指定毫秒中的超時，以等待DOM沉降。默認為30000（30秒）。apiKey ：（可選）您的BrowserBase API鍵。默認為BROWSERBASE_API_KEY環境變量。projectId ：（可選）您的BrowserBase項目ID。默認為BROWSERBASE_PROJECT_ID環境變量。browserBaseSessionCreateParams ：用於創建新的BrowserBase會話的配置選項。browserbaseResumeSessionID ：現有的browserbase會話的ID。logger ：處理日誌消息的函數。對於自定義記錄實現有用。verbose ：一個integer ，可以在自動化過程中進行幾個級別的記錄：0 ：不限於記錄1 ：SDK級記錄2 ：LLM-CLIENT級記錄（最精細）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 ：（可選的）毫秒中的超時等待DOM沉降返回：
Promise ：debugUrl ：代表現場調試URL的string 。僅當使用BrowserBase瀏覽器時才可用。sessionUrl ：代表會話URL的string 。僅當使用BrowserBase瀏覽器時才可用。例子：
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分別是Playwright的Page和BrowserContext的實例。使用這些方法與StageHand使用的劇作家實例進行交互。最常見的是，您將使用page.goto()導航到URL。
await stagehand . page . goto ( "https://github.com/browserbase/stagehand" ) ;log() log()用於將消息打印到瀏覽器控制台。這些消息將在BrowserBase會話日誌中持續存在，並且可以在完成後進行調試。
在初始化舞台的實例時，請確保日誌級別高於您設置的詳細級別。
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將使用Vision重試嘗試。
現在，我們有了候選元素的列表和選擇它們的方法。我們可以向LLM提出提取或動作的其他上下文提供這些元素。儘管未經大規模測試，但提出了“編號的元素列表”指導該模型不將上下文視為完整的DOM，而是將上下文視為相關但獨立的元素列表。
在行動的情況下，我們要求LLM編寫劇作家方法以做正確的事情。在我們有限的測試中，劇作家語法比依賴內置的JavaScript API要有效得多，這可能是由於令牌化所致。
最後，我們使用LLM為自己編寫未來的說明，以幫助管理跨塊運行時的進度和目標。
以下是如何使用StageHand和playwright從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提高Web自動化的可靠性和有效性。請記住，StageHand擅長執行精確的，定義明確的動作，因此保留您的指示原子會帶來最佳結果。
我們將代理行為留給可以使用StageHand作為工具的高級代理系統。
在高水平上，我們專注於以優先順序提高可靠性，速度和成本。
您可以在這裡看到路線圖。想要貢獻？繼續閱讀！
筆記
我們高度重視對舞台的貢獻！有關支持或代碼審查，請加入我們的Slack社區。
首先，克隆倉庫
git clone [email protected]:browserbase/stagehand.git然後安裝依賴項
npm install確保您在“入門”部分中有上述記錄的.env文件。
然後，運行示例腳本npm run example 。
一個良好的開發循環是：
您需要一個腦形想像的API鍵來運行EVALS
BRAINTRUST_API_KEY = " "之後，您可以使用npm run evals
運行所有Evals可能需要一些時間。我們有一個便利的腳本example.ts 。
您可以運行npm run example以執行和迭代您當前正在開發的評估。
要添加新模型到舞台手，請按照以下步驟：
定義模型：將新的模型名稱添加到LLMProvider.ts文件中的AvailableModel類型中。這樣可以確保該模型被系統識別。
將模型映射到提供商：更新LLMProvider類中的modelToProviderMap ，以將新模型與其相應的提供商相關聯。該映射對於確定要使用哪個客戶端至關重要。
實現客戶端：如果新模型需要新客戶端，請實現遵守LLMClient接口的類。此類應定義所有必要的方法，例如createChatCompletion 。
更新getClient方法：在請求新模型時，在LLMProvider類中修改getClient方法以返回新客戶端的實例。
StageHand使用TSUP來構建SDK和Vanilla esbuild來構建在DOM中運行的腳本。
npm run buildnpm pack以獲取用於分配的油粉這個項目在很大程度上依靠劇作家作為自動化網絡的彈性骨幹。如果沒有Tarsier和Fuji-Web的出色技術和發現，也將不可能。
傑里米出版社（Jeremy Press）撰寫了《舞台》（Stagehand）的原始MVP，並繼續是該項目的主要盟友。
根據MIT許可獲得許可。
版權2024 Browserbase，Inc。
