Stagehand

Stagehand 是由 Browserbase 构建的开源浏览器自动化 SDK，它弥合了脆弱的 CSS 选择器脚本与不可预测的全自主智能体之间的差距。该工具于 2024 年 10 月发布，目前已更新至 v3 版本，为 TypeScript 和 Python 开发者提供了三个可组合的原语：act()、extract() 和 observe()，外加一个自主的 agent() 模式，每个原语均由您选择的 LLM 提供支持。传统的 Playwright 脚本会硬编码 page.click('#submit-btn')，一旦设计师重命名了类名就会崩溃，而 Stagehand 则会在运行时针对实时 DOM 解析 act("click the submit button")，因此脚本能够经受住季度的 UI 更新，实现零维护。

该框架采用 MIT 许可，可针对任何 Chromium 实例在本地免费运行。它可与 Browserbase 的托管云运行时（可选，付费）配合使用，以实现住宅代理、隐身浏览、验证码破解和会话记录。Stagehand 通过 Vercel AI SDK 支持 OpenAI、Anthropic Claude 和 Google Gemini，并且 v3 的直接 Chrome DevTools Protocol (CDP) 架构使其与模型和驱动程序无关。截至 2026 年 4 月，其 GitHub 仓库已获得 22,400 颗星、1,500 次分叉和 57 个版本，其 Python 移植版与 Browserbase 在 2025 年 6 月的 4000 万美元 B 轮融资一同发布。

Stagehand 在 2026 年 4 月的实际功能

于 2025 年 10 月 29 日发布的 Stagehand v3 完全移除了对 Playwright 的硬依赖，并在直接 CDP 通信的基础上重建了框架。这一架构变化意义重大：Stagehand 不再继承 Playwright 测试优先的假设，并且支持将 Puppeteer、Playwright、Bun 或任何其他兼容 CDP 的驱动程序作为模块化后端。在基于选择器的工具最难处理的 iframe 和 shadow-root 交互方面，v3 比 v2 快 44.11%。

这四个原语各自承担不同的工作。act() 根据纯英语指令（“点击下一页按钮”、“在电子邮件字段中填写 [email protected]”）执行浏览器操作。extract() 从页面中提取结构化数据，并根据 Zod 模式对其进行验证，因此您返回的是类型化对象，而不是原始 HTML。observe() 在您执行操作之前显示页面上存在哪些交互元素，这对于条件逻辑和安全检查非常有用。在 v2 中添加的 agent() 可以在您希望进行端到端执行而无需手动编排每个步骤时，自主运行多步工作流。

V3 还引入了一个上下文构建器，每次操作只向模型提供相关的 DOM 子集，而不是转储整个页面。这大大减少了 token 浪费，并使每次操作的成本更具可预测性。在 v3.1.0（2026 年 2 月）中添加的服务器端缓存可存储 act/extract/observe 的结果，因此一旦工作流稳定下来，重复运行相同流程将完全跳过 LLM 推理。

“与 v2 并排运行时，我们的 Stagehand v3 工作流明显更加轻快。我们现在可以获得详细的可观测性和每次操作的 token 级别报告。” - Steve Austin，Benny 联合创始人兼 CTO，Stagehand v3 发布博客，2025 年 10 月

模型支持涵盖 GPT-4o、Claude 3.7 Sonnet、Gemini 2.0 以及各个系列中的较新版本。团队的内部发现是：Claude 能更好地处理需要大量推理的步骤，GPT-4o 变体能更可靠地执行精确操作，而 Gemini 则适合观察任务。该框架与模型无关的设计允许您在单个脚本中将不同的原语路由到不同的模型，尽管大多数团队会选择一个并保持一致。

Stagehand 与 Playwright 和 Browser-Use 的定位对比

Playwright（无 AI）是每个 AI 浏览器自动化工具竞争的基准。它是纯确定性的：每个操作都需要明确的选择器或角色定位器，每次操作的 LLM 成本为零，并且每步的执行速度低于 100 毫秒。在稳定的 UI 上，手写的 Playwright 脚本能以 92-98% 的成功率完成任务。这种可靠性的代价是维护：每次重大的 UI 重新设计都会破坏 15-25% 的选择器，需要工程师更新脚本。Playwright 拥有 70,000 多颗 GitHub 星星，一个将交互会话记录为脚本的成熟代码生成工具，以及一流的追踪和视频录制生态系统。它是 Stagehand 最初封装的底层基础，大多数团队仍然将其用于 80% 可预测的自动化步骤。目前出现的实用生产模式是：将 Playwright 用于确定性的导航和登录流程，将 Stagehand 用于中间的动态提取和操作步骤。

Browser-Use 是以 Python 为首选的替代方案，具有不同的理念。Stagehand 是混合型的（由您决定哪些步骤由 AI 驱动），而 Browser-Use 则运行一个完全自主的智能体循环，LLM 接收页面状态，决定下一步做什么，并不断迭代直到达到目标。它支持本地 Ollama 模型，这意味着对于愿意运行自己硬件的团队来说，推理成本为零。到 2026 年初，Browser-Use 的 GitHub 星星数突破了 80,000 颗，这在很大程度上是由 Python 开发者推动的，他们发现其更简单的 API 更易于使用。代价是可预测性：Browser-Use 在每次运行时都会从头开始重新推理，因此相同的目标在不同的日子可能会产生不同的执行路径。Stagehand 的缓存模型和显式原语使其在生产环境中更具可重复性，在生产环境中，您需要审计脚本做了什么以及为什么这样做。对于步骤顺序不固定的探索性、开放式 Web 任务，Browser-Use 通常是更好的选择。对于每天运行相同工作流 500 次且需要可靠、可调试执行的生产管道，Stagehand 胜出。

值得注意的第三个类别是 AgentQL，它采用查询语言方法而不是方法调用方法。AgentQL 使用受 GraphQL 启发的语法来声明性地描述页面元素，而 Stagehand 使用带有自然语言参数的命令式代码。两者都建立在相似的浏览器基础设施之上，但心智模型却大不相同。具有强大 TypeScript 模式的团队倾向于选择 Stagehand；希望将数据模式表达为查询的团队倾向于选择 AgentQL。在调试时，Stagehand 的 act/extract/observe API 更容易推理。

智能体工作流的现实情况

大多数生产环境中的 Stagehand 设置都遵循一种可预测的模式。确定性强、易于理解的步骤（身份验证、导航到目标页面、设置过滤器）使用纯 Playwright 或带有显式选择器的 Stagehand 调用。页面结构发生变化的步骤（动态加载的表格、shadow-DOM 组件、多步流程背后的经过身份验证的数据）则调用 Stagehand 的 AI 原语。这种混合方法使 LLM 成本保持在可控范围内：每次 act/extract 调用的成本为 $0.002-$0.02，包含五个 AI 步骤的工作流每次运行的成本不到 $0.10，这是可行的。如果每个步骤都通过 AI 运行，团队在规模化时就会遇到成本计算上的麻烦。

调试与调试纯 Playwright 不同。当 act() 调用失败或误解了模棱两可的指令时，错误会作为运行时异常浮现，并记录模型解释的操作，但阅读 AI 决策追踪与阅读选择器不匹配是不同的技能。Stagehand API（2026 年 6 月发布）将部分此类翻译工作转移到了托管基础设施中，提供人类可读的操作日志和每步的 token 级别可观测性，这直接解决了早期 Hacker News 帖子中关于“黑盒”的抱怨。

“我认为我无法合理地主张在工作中的测试套件里在运行时使用 LLM。正确的方法应该是使用 AI 来帮助编写 Playwright 测试代码，而不是取代确定性部分。” - mpalmer，Hacker News，2025 年 1 月 9 日

来自 Hacker News 发布帖子的这种怀疑被证明部分正确，部分错误。对于确定性不可妥协的 CI/CD 测试套件来说，Stagehand 在运行时使用 LLM 的方法仍然很难推销。但对于维护成本才是真正敌人的生产自动化管道来说，这种权衡已被证明对很大一部分团队是值得的。重要的架构区别在于，Stagehand 主要是一个恰好在测试环境中表现良好的浏览器自动化工具，而不是一个添加了 AI 功能的测试框架。

当您需要 Stagehand 原生不提供的浏览器基础设施功能时，真正的操作复杂性就来了。机器人检测、验证码破解、住宅代理、会话记录、多区域执行以及符合 HIPAA 标准的数据处理，都需要付费的 Browserbase 托管运行时或大量的自定义管道。构建简单内部自动化的团队可以针对本地 Chromium 实例运行 Stagehand，并且只需支付其 LLM API 成本。构建生产级 Web 智能体的团队通常两者都需要。

Stagehand 是为谁构建的

为生产自动化构建浏览器智能体的 TypeScript 开发者是主要受众。希望用人类可读的自然语言编写测试，而无需致力于 Playwright 选择器维护的 QA 工程师是强大的次要受众。已经拥有 Playwright 代码库并希望用 AI 推理增强特定步骤（而不是替换整个技术栈）的团队是 Stagehand 能够干净集成的第三个细分市场。

Stagehand 也能自然地融入 AI 智能体框架。它的 act/extract/observe 原语很好地映射了 OpenAI Agents SDK 风格架构中的工具调用，其中规划智能体决定采取哪些 Web 操作，而 Stagehand 负责执行它们。构建包含 Web 数据和结构化数据源的数据管道的团队，通常会将用于提取的 Stagehand 与 Firecrawl（用于干净的文档提取）或 Apify（用于可扩展的抓取基础设施）等工具结合使用。Stagehand 负责处理静态爬虫无法触及的经过身份验证、包含大量 JavaScript 以及需要填写表单的场景。

B 轮融资里程碑（2025 年 6 月）和每周 500,000 多次的 NPM 下载量证实，Stagehand 已经从一个充满希望的开源实验毕业，成为一个在生产环境中得到真正采用且背后有资金支持团队的框架。v3 CDP 架构消除了对特定上游（Playwright）的依赖，这降低了 Playwright 内部更改破坏 Stagehand 行为的风险。

Stagehand 不是什么

在大批量、对成本敏感的自动化中，Stagehand 并不是 Playwright 的替代品。每天进行 10,000 次提取，即使使用缓存，中端模型的 LLM 费用也高达每天 $50-200。对于具有稳定、易于理解的页面结构的这种体量，维护 Playwright 选择器更便宜。Stagehand 节省的维护成本超过其 LLM 成本的盈亏平衡点，在很大程度上取决于目标网站更改其 DOM 的频率以及工程师的时间成本。

Stagehand 不是本地优先或隐私优先的工具。它的每个 AI 驱动步骤都需要云 LLM API 凭证。Browser-Use 对 Ollama 的支持使其成为因数据驻留要求或安全策略而无法将页面内容发送到外部 API 的团队的更好选择。

它不是点击式的无代码工具。Stagehand 是一个开发者 SDK。您需要编写 TypeScript（或 Python）代码。自然语言位于方法调用内部，而不是在可视化工作流构建器中。没有工程能力的团队应该关注 Browserbase 的 Director.ai 产品（2025 年 6 月发布），以获取无代码浏览器智能体界面。

在敏感环境中，它不能完全替代人工监督的浏览。金融交易、医疗保健数据录入和法律文档工作流需要审批步骤、审计日志和合规工具，而 Stagehand 并不开箱即用提供这些功能。该框架是基础设施，而不是合规产品。

最后，Stagehand 不太适合探索性、开放式的研究任务，在这些任务中，浏览器操作的确切顺序无法提前预知。如果您的目标是“在这 12 个网站中找到 X 的最佳价格”且没有固定的工作流，那么 Browser-Use 的自主推理循环比 Stagehand 的可组合原语模型能更自然地处理目标导向的 Web 探索。对于具有明确步骤和可衡量结果的可重复生产工作流，Stagehand 的混合方法会带来回报。对于模糊的、多轮的研究任务，更具智能体特性的框架可能会更好地为您服务。