安装 Stagehand - 🤘 Stagehand

将 Stagehand 添加到新项目或现有项目中。

对于 TypeScript/Node.js：我们强烈建议使用 Node.js 运行时环境来运行 Stagehand 脚本，而不是 Deno 或 Bun 等较新的替代方案。Bun 不支持 Stagehand，因为它不支持 Playwright。对于 Python：需要 Python 3.9 或更高版本，并建议使用 uv 来管理虚拟环境。

TypeScript
Python

我们强烈推荐在新项目中使用 npx create-browser-app 来集成 Stagehand。请查阅我们的快速入门指南开始使用。若您已有现有项目，可通过安装 @browserbasehq/stagehand 包来引入 Stagehand。

npm
pnpm
yarn

npm install @browserbasehq/stagehand

pnpm add @browserbasehq/stagehand

yarn add @browserbasehq/stagehand

运行 Stagehand 脚本时可能需要安装 Playwright 浏览器，特别是在本地运行环境下。

playwright install

随后，您可以通过导入 Stagehand 类在项目中使用该工具。

import { Stagehand } from "@browserbasehq/stagehand";

async function main() {
	const stagehand = new Stagehand({
		// 使用 npx create-browser-app 时，该配置存放于
		// 单独的 stagehand.config.ts 文件中
		env: "LOCAL",
		modelName: "openai/gpt-4.1-mini",
		modelClientOptions: {
			apiKey: process.env.OPENAI_API_KEY,
		},
	});
	await stagehand.init();

	const page = stagehand.page;

	await page.goto("https://www.google.com");
	await page.act("在搜索栏输入'Browserbase'");

	const { title } = await page.extract({
		instruction: "首个搜索结果的标题",
		schema: z.object({
			title: z.string(),
		}),
	});
	

	await stagehand.close();
}

main();

开始前请确保已安装 Python 3.9+。推荐使用 uv 管理虚拟环境。

推荐：设置虚拟环境

uv venv
source .venv/bin/activate

安装 Stagehand Python 包

pip install stagehand

若使用 uv 虚拟环境，可通过以下命令安装：

uv add stagehand

配置环境变量

创建 .env 文件或导出环境变量：

export MODEL_API_KEY="your_model_api_key" # OpenAI, Anthropic 等
# 浏览器环境配置
# export BROWSERBASE_API_KEY="your_browserbase_api_key"
# export BROWSERBASE_PROJECT_ID="your_browserbase_project_id"

创建首个脚本

创建 main.py 文件：

import asyncio
import os
from stagehand import Stagehand, StagehandConfig
from dotenv import load_dotenv

load_dotenv()

async def main():
		config = StagehandConfig(
				env="LOCAL",
				model_name="openai/gpt-4.1-mini",
				model_api_key=os.getenv("MODEL_API_KEY")
		)
		
		stagehand = Stagehand(config)
		
		try:
				await stagehand.init()
				page = stagehand.page
				
				await page.goto("https://docs.stagehand.dev/")
				await page.act("点击快速入门链接")
				
				result = await page.extract("提取页面主标题")
				
				print(f"提取结果: {result.extraction}")
				
		finally:
				await stagehand.close()

if __name__ == "__main__":
		asyncio.run(main())

运行脚本

python main.py