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。
