Stagehand 快速上手教程：3 步搭出能自然语言操作的 AI 浏览器助手-平芜编程栈

Stagehand 快速上手教程：3 步搭出能自然语言操作的 AI 浏览器助手

【免费下载链接】stagehandThe SDK For Browser Agents项目地址: https://gitcode.com/GitHub_Trending/stag/stagehand

给网页写自动化脚本，大多逃不出一个循环：页面一改版，手写选择器就失效，脚本跟着报废，重新调试又是一轮。Stagehand 是 Browserbase 出品的、用于构建 AI 浏览器助手的 SDK——你把"点击登录按钮"写成一句自然语言，由 AI 自己定位元素并完成操作，页面结构变化后它能检测差异并自动恢复动作路径。TypeScript、Python、Go 三端 SDK 同步维护，本文带你用三步跑通一个能操作真实网页的 Demo。

传统做法里，"提取公司名和批次号"这类任务要手写evaluate遍历 DOM、靠正则从文本里抠字段，站点改一个 class 名整个解析链就断了。Stagehand 的解法是把"定位 + 解析"这一层整个替换掉，用三个原语覆盖几乎所有页面任务：

act：一句话描述操作（点击、填表、滚动），代替手写选择器和动作序列；
observe：让 AI 列出当前页面可交互的元素和建议动作，相当于给页面做"体检"；
extract：传入 zod schema，直接拿回类型化的结构化对象，替代正则解析。

为什么手写选择器总会坏

上面这张对比图很直观：右边是一堆querySelectorAll加文本判断的解析代码，站点稍有改动就要跟着改；左边一行extract指令加 schema 就完成了同样的提取。Stagehand 的 act 是"自愈"的——执行前会核对元素是否还在预期位置，站点改版后它会自动刷新操作方式，而不是抛一个"元素未找到"让你回去改选择器。另外它通过 CDP 协议驱动浏览器，且内置一个跑在浏览器扩展里的驱动进程，动作往返延迟比远程遥控方案更低。

三个原语：操作、观察、取数

三个原语都挂在stagehand实例上，接受自然语言指令：

await stagehand.act("Click the 'Evals' button."); // 操作 const { data } = await stagehand.observe("What can I click on this page?"); // 观察 const { data } = await stagehand.extract( "Extract the value proposition from the page.", z.object({ valueProposition: z.string() }) // 取数 );

对确定性的批量操作，也可以拿observe返回的 selector 走 Playwright 风格的page.locator(selector).click()，两条路径可以混用。

安装与环境准备

📦 环境要求：Node.js 22.18+（推荐 Node 运行时）。v4 版本通过 CDP 直接驱动浏览器，没有 Playwright 依赖，安装只有两个包：

# npm install @browserbasehq/stagehand zod 也可以 pnpm add @browserbasehq/stagehand zod

如果你打算用 Browserbase 云浏览器跑，本地什么都不用装；若要localBrowser.launch()在本机跑，则机器上需要装好 Chrome。Python 用户用pip install stagehand，Go 用户用go get获取 SDK。官方文档：packages/docs/v4/first-steps/installation.mdx

API 密钥怎么配

只需一个密钥：BROWSERBASE_API_KEY，在 Browserbase 官网 Dashboard 的 Project 设置里能同时看到 Project ID 和 API Key。模型侧不需要单独配 key——未指定模型时，Model Gateway 会为每次推理调用自动选择模型。

一个容易踩的点：Stagehand 不会替你读环境变量，也不自动加载.env。密钥要在你自己的代码里读出、显式传给浏览器工厂，示例代码即按此写法。浏览器来源、超时、日志等配置见：packages/docs/v4/configuration/browser.mdx

三步跑通 Demo

写脚本：新建index.ts，下面 14 行覆盖 goto、extract、act 全链路：

import { browserbase, Stagehand } from "@browserbasehq/stagehand"; import { z } from "zod/v4"; const browser = await browserbase.launch({ apiKey: process.env.BROWSERBASE_API_KEY, }); const stagehand = await Stagehand.create({ browser }); const [page] = await browser.context.pages(); await page.goto("https://stagehand.dev"); // extract：按 schema 提取结构化数据 const { data } = await stagehand.extract( "Extract the value proposition from the page.", z.object({ valueProposition: z.string() }) ); console.log(data); // act：一句话执行点击操作 await stagehand.act("Click the 'Evals' button.");

设密钥、运行：

export BROWSERBASE_API_KEY="bb_live_..." # 你的 Browserbase API 密钥 pnpm dlx tsx index.ts # 运行脚本

看结果：终端先打印 extract 拿到的valueProposition字符串，再看到页面里 "Evals" 按钮被 AI 点下去——这就是一个能操作真实网页的 AI 浏览器助手的完整闭环。

💡 开发期不想走云浏览器，把browserbase.launch()换成localBrowser.launch()即可在本地 Chrome 上调试。

▶️ 运行效果类似这样——左边是脚本，右边是助手在执行滚动、点击等指令：

完整分步流程参考：packages/docs/v4/first-steps/quickstart.mdx

从 Demo 到真实使用

仓库自带示例：act、extract、observe、caching、customLlm、webmcp 等场景都有可运行的 TypeScript 示例，照着改最快；
Python / Go 用户：三端 API 对齐，同一套原语在stagehand（pip）和 Go SDK 中同样可用；
接入 AI 工具链：仓库提供 Claude Code、Codex、CrewAI、LangChain 等集成包，可以把 AI 浏览器助手挂到你现有的 agent 框架里。

下一步建议：