进阶

用 Stagehand 让 AI 动手操作网页：自然语言驱动浏览器（act/extract/observe/agent）

2026.07.26· 7 个步骤 · 20 分钟阅读· 🌐 Stagehand

写过 Playwright / Selenium 的人都有过这种崩溃：网站更新一次 DOM，几十个 CSS 选择器全崩，半夜被报警叫醒。2026 年最 production-ready 的浏览器自动化 SDK——Stagehand，就是把这件事终结掉的那个。它由 Browserbase 开源（MIT，23k+ Star），核心思路是「用自然语言代替脆弱选择器」：act 点击、extract 取数、observe 感知、agent 自主跑流程，页面改版也能自愈。本教程从安装到跑通一个「登录 → 下载报表」的端到端流程。

🌐 本教程适合：被选择器维护折磨的前端/测试/数据工程师，想用 AI 驱动浏览器但又要确定性和可调试性的开发者。需会一点 TypeScript 或 Python。

先搞懂：Stagehand 和普通爬虫有什么不同？

用一句话理解：Playwright 是「你写死每一步坐标」，Stagehand 是「你说干什么、它自己找按钮」。它把「代码的确定性」和「AI 的适应力」捏在一起：

能力	作用
act()	用大白话执行浏览器动作：点击、填表、导航、滚动
extract()	按 Zod 结构从页面取结构化数据，可直接对接下游
observe()	执行前先感知页面上「可操作元素」，更安全精确
agent()	最少监督下端到端跑多步浏览器任务

「选择器会坏，自然语言不会」。Stagehand 在运行时用 AI 把「点提交按钮」解析成真实点击，所以网站改版后指令仍能存活。它还能缓存动作、自修复，跨多次运行可预测又省钱。

Step 1：安装与初始化

1 一行起项目

Stagehand 同时支持 TypeScript 和 Python。新手用官方脚手架最快：

# 方式一：官方脚手架（推荐）
npx create-browser-app

# 方式二：手动装核心包
pnpm add @browserbasehq/stagehand
# 或 Python：
pip install stagehand

# 配置：复制环境变量模板，填入 LLM Key
cp .env.example .env
# .env 里至少要有：
#   OPENAI_API_KEY=xxx   或 ANTHROPIC_API_KEY=xxx
#   （经 Vercel AI SDK，支持 OpenAI/Anthropic/Gemini 等多家）

💡 模型从哪来？Stagehand 通过 Vercel AI SDK 接各大模型。本地跑也可接 Ollama。先把一个云端 Key 填好跑通，再考虑成本优化。

Step 2：启动浏览器，连上 Stagehand

2 本地就能跑，不强制上云

Stagehand 不需要 Browserbase 也能用——任意 Chromium 浏览器本地跑，四大原语开箱即用：

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

const stagehand = new Stagehand({ env: "LOCAL" });
await stagehand.init();
const page = stagehand.context.pages()[0];
await page.goto("https://github.com/browserbase");

本地 vs 云端。本地开发零成本；上线生产时再接 Browserbase 云浏览器（Agent Identity、session replay、验证码破解、零基础设施部署），代码一行不用改。先本地跑通最稳。

Step 3：act()——用自然语言点击和填表

3 告别 CSS 选择器

这就是 Stagehand 的招牌。你描述意图，它解析成真实操作：

// 以前（Playwright）：得写死选择器，一改版就崩
// await page.click("#root > div > form > button.submit")

// 现在（Stagehand）：说人话
await stagehand.act("点击 stagehand 仓库的 Star 按钮");
await stagehand.act("在搜索框输入 stagehand 并回车");
await stagehand.act("填写登录表单：账号填 user@example.com，密码填 ******");

🔑 关键认知：act 不是黑盒 Agent，它仍受你控制——AI 在运行时把自然语言解析成确定性动作。你得到的是「像人一样懂页面」+「像代码一样可预期」。

Step 4：extract()——用 Zod 取结构化数据

4 抓数直接变可用对象

extract 配合 Zod schema，把页面内容变成强类型结构，下游直接消费：

import { z } from "zod";

const { author, title } = await stagehand.extract(
  "提取这个 PR 的作者和标题",
  z.object({
    author: z.string().describe("PR 作者的用户名"),
    title: z.string().describe("PR 的标题"),
  }),
);
console.log(author, title);  // 直接是结构化对象

Zod 校验很重要。它既约束了输出格式，也等于给 AI 一份「要取什么」的清单，取数更准、下游更稳。别跳过 schema 直接拿自由文本。

Step 5：observe()——执行前先「看清楚」

5 安全与精确的双保险

observe 在执行动作前先列出页面上「可操作的元素」，让你确认再动手——特别适合敏感操作：

// 先感知，再决定点哪个
const elements = await stagehand.observe("找出页面上所有『提交』类按钮");
console.log(elements);
// => [{ description: "提交订单", selector: "...", method: "click" }, ...]

// 确认无误后，只对目标元素 act
await stagehand.act("点击『提交订单』按钮");

💡 observe 就像「出手前的瞄一眼」。在支付、删除、提交等关键路径前用它，能显著降低误点风险，也让自动化更可审计。

Step 6：agent()——多步自主流程

6 端到端跑一个完整任务

当任务步骤多、需要探索时，交给 agent 自主执行；关键路径仍可用单个原语精确控：

const agent = stagehand.agent();
await agent.execute(
  "登录供应商后台，进入 Monthly Reports，下载 2026-07 的 CSV 报表"
);
// agent 自己规划：打开站点 → 登录 → 导航 → 定位报表 → 点击下载

// 常见组合：agent 探路 + act/extract 走关键路径
// 例：agent 找到报表页，extract 精确取下载链接，act 触发下载

多数团队是混着用。探索性、长流程交给 agent；涉及钱/数据/不可逆的步骤，用 act+observe 精确卡死。别把所有事都丢给一个黑盒 agent。

Step 7：生产化——上云、缓存、自修复

7 从 Demo 到稳定服务

真要上线，把三件事加上，Stagehand 才「production-ready」：

# 1. 接 Browserbase 云浏览器（代码零改动）
#    env: "BROWSERBASE"，配 BROWSERBASE_API_KEY
#    → 拿到 Agent Identity、session replay、验证码破解

# 2. 开动作缓存（action caching）
#    重复动作不再调 LLM，跨运行可预测又省钱

# 3. 自修复（self-healing）
#    网站变了，Stagehand 自动重试/重新解析，不会一碰就挂

# 4. 可观测：用 session replay 回放「它点了哪、取了啥」，
#    出问题能复盘，不像黑盒 Agent 那样无从查起

🎉 到这步，你拥有了一套「自然语言驱动 + 确定性可控 + 页面改版自修复 + 可回放可审计」的浏览器自动化。最大收获：再也不用半夜起来修选择器。

常见问题速查

你遇到的现象	大概率原因 & 解决
act 点错元素	指令太模糊；用 observe 先列元素再精确 act
extract 取数不全	Zod schema 描述不清；补全 describe 字段
LLM 调用太贵	开 action caching，重复步骤不再调模型
页面大改后失败	开 self-healing；关键路径用 observe 兜底

📚 更多教程 📰 智能体资讯