stagehand

环境要求

• Node.js 环境与 pnpm 包管理器（用于 TypeScript 版 SDK）
• 本地运行时需要安装 Chrome 浏览器
• 若使用云端执行，需要 Browserbase 账号与 API Key
• 可选：Python 或 Go 运行环境（使用对应语言 SDK）

安装与启动步骤

1. 1安装 TS SDK

   在项目目录下用 pnpm 安装 Stagehand 主包，并按 README 要求同时锁定 zod 版本，避免依赖冲突。

   pnpm add @browserbasehq/stagehand 'zod@~4.4.3'

   复制

2. 2安装 Python SDK

   如果使用 Python 调用，直接 pip 安装 stagehand 包，包名与 TS 版不同，不要混用。

   pip install stagehand

   复制

3. 3安装 Go SDK

   Go 项目通过 go get 拉取指定版本 v4.0.0 的 SDK 模块，注意版本号需与仓库路径一致。

   go get github.com/browserbase/stagehand/packages/sdk-go/v4@v4.0.0

   复制

4. 4准备本地 Chrome

   本地运行 Stagehand 依赖已安装的 Chrome 浏览器，请先在本机安装好再运行脚本。

5. 5接入 Browserbase

   把同一个脚本指向 Browserbase 云端执行，使用环境变量中的 API Key，并开启 cache 复用重复动作、无需手动配置模型。

   import { browserbase, Stagehand } from "@browserbasehq/stagehand";
   
   const browser = await browserbase.launch({ apiKey: process.env.BROWSERBASE_API_KEY! });
   
   const stagehand = await Stagehand.create({ browser, cache: true });

   复制

关键配置

如何确认成功

脚本能正常启动并完成浏览器动作、无依赖或模型配置报错；本地模式需确认 Chrome 已安装。

常见问题

注意事项

• TypeScript 版必须与 zod@~4.4.3 一起安装，版本不匹配可能报错。
• README 未给出本地运行的完整示例代码，请以官方 Quickstart 文档为准。
• Browserbase 模式需额外配置 server-side caching 才能复用重复动作。
• 安装命令区分语言，误用其他语言的包名会导致依赖缺失。