browser-use-to-stagehand

browser-use → Stagehand on Browserbase (/browser-use-to-stagehand)

将 browser-use（Python）脚本转换为符合习惯用法的 Stagehand v3（TypeScript） 脚本，并在 Browserbase 上运行；为每个步骤选择合适的确定性级别，而不是生成一对一的 Agent 式副本。

核心原则： browser-use 默认采用 Agent 模式（由大模型决定每个操作）。Stagehand 则允许你选择 AI 的使用程度。优秀的迁移会用可检查、基本确定性的流程替换不透明的 Agent 循环，只在页面确实难以预测时使用 AI。这是需要判断的重构，而不是转译。

权威来源与版本。 此技能的持久价值在于判断——确定性范围以及拆解任务还是使用 Agent 的决策——而不是 API 细节，因为这些会随每次发布而变化。此处的代码映射是基于 @browserbasehq/stagehand 3.6.x 和 browser-use 0.13.x（2026-06）验证的快照。如有冲突，以最新文档为准——生成代码前，务必根据已安装的软件包和以下来源进行核实：

• Stagehand v3：https://docs.stagehand.dev/v3 · 已安装的类型：node_modules/@browserbasehq/stagehand
• Browserbase：https://docs.browserbase.com
• browser-use：https://docs.browser-use.com

如果已安装的 Stagehand 主版本不是 3，请仅将此技能视为概念参考，并按照最新文档核对所有签名。

参考文件（按需阅读）

• references/api-mapping.md — browser-use → Stagehand 的机械映射：变体识别、完整功能表、前后代码对比、Browserbase 平台选项，以及 v3 版本注意事项。遇到任何非简单结构时都要阅读。
• references/determinism.md — 如何在 agent()、act/extract/observe 和缓存的 observe→act 之间做选择。决策树。决定如何转换 Agent(task=…) 时要阅读。
• references/trace-assisted.md — 针对不透明或不稳定脚本的可选工作流：“在 Browserbase 上运行、读取日志，然后重写”。
• references/guide.md — 面向开发者的迁移指南：理念转变、功能映射、确定性范围，以及推荐的迁移路径。
• references/prompt.md — 此技能的独立、与工具无关版本；可将其与 browser-use 脚本一同粘贴到任何 AI 助手中。
• EXAMPLES.md — 转换前后的脚本示例。

工作流

1. 获取源代码

获取 browser-use 脚本。如果用户只描述了脚本，请索要文件。注明目标：在 Browserbase 上运行的 TypeScript Stagehand，除非用户另有说明。

首先确认范围——这类脚本是否可以迁移？ 并非每个 browser-use 文件都是 Agent(task=…) 脚本。如果源代码是作为 MCP 服务运行的 browser-use（uvx browser-use --mcp、mcpServers 配置），则没有对应的 Stagehand 实现——请标明超出范围，不要凭空编造（参见 api-mapping §3.7b）。如果 browser-use 调用嵌入在更大的应用中（类/工具封装、Web 路由、队列任务），则只转换 browser-use 部分，并保留外围应用代码——参见 api-mapping §3.8。

2. 识别 browser-use 变体

识别其属于旧版（0.12 之前）、稳定版还是 Rust 测试版（仅当导入来自 browser_use.beta 时）——参见 api-mapping §1。注意：经典的顶层 from browser_use import Agent, ChatBrowserUse 接口在 0.13.x 中仍然正常可用——仅出现 ChatBrowserUse 并不意味着是测试版；只有从 browser_use.beta 导入才是。所有变体的转换方式都相同，因此不确定时，请使用稳定版映射。转换前先规范化旧版名称，并说明识别到的变体。

3. 梳理脚本清单

在编写任何 TypeScript 之前，先提取结构化清单：

• 任务 — task= 字符串；将每个字符串拆分为其隐含的有序步骤。
• 模型 — Chat* 提供方 + 模型 ID。
• 浏览器配置 — 本地配置还是 cdp_url/Browserbase；无头模式；代理；user_data_dir/storage_state。
• 结构化输出 — 任何 output_model_schema Pydantic 模型。
• 密钥 — sensitive_data、环境变量用法、登录流程。
• 防护措施 — allowed_domains、max_steps。
• 自定义操作 — @tools.action / Controller 函数，以及每个函数是确定性的副作用还是 Agent 能力。
• 设置 — initial_actions、辅助模型（page_extraction_llm、planner_llm）。

4. 确定每个步骤的确定性级别

对清单中的每个步骤，按照 determinism.md 中的决策树处理：

• 导航到已知 URL → 在 Stagehand 页面上执行 page.goto(url)（不使用 AI）。
• 页面内操作 → act("…")；如果操作会重复，先调用一次 observe()，然后重放 act(action)（不调用 LLM）。
• 读取数据 → extract("…", zodSchema)。
• 真正开放式的操作 → 保留 stagehand.agent().execute(...)（并通过 maxSteps/systemPrompt 收紧范围）。

流程已知时，默认采用拆解；仅在流程未知时保留 agent()。对于首次直接迁移，忠实地将其翻译为 agent() 也可以——请说明这一点并指出优化路径。

5. 编写 Stagehand v3 重写版本

首先，核实 API。 编写之前，请对照已安装的软件包（node_modules/@browserbasehq/stagehand 类型）或 https://docs.stagehand.dev/v3，确认即将使用的确切签名。以下映射基于 3.6.x 版本；如果已安装版本有所不同，以已安装版本为准。然后输出可运行的 TypeScript。始终：

• 提取数据时，使用 import { Stagehand } from "@browserbasehq/stagehand"; 和 import { z } from "zod";。
• 使用 const page = stagehand.context.pages()[0]; 获取页面。
• 在实例上调用 AI 方法：stagehand.act(...)、stagehand.extract(...)、stagehand.observe(...)——绝不要调用 page.act(...)。
• 将模型设为 "provider/model" 字符串。
• 默认使用 env: "BROWSERBASE"；将 env: "LOCAL" 作为开发选项展示。
• 通过 variables 和 process.env 传递密钥，绝不硬编码。
• 在开头调用 await stagehand.init()，并在 finally 中调用 await stagehand.close()。

提供项目设置，使其能够运行（参见下方模板）。

6. 编写迁移摘要

在代码之外，提供简短摘要：

• 检测到的变体和所做的确定性选择（哪些步骤变为确定性操作、AI 操作或 Agent 操作），并说明理由。
• 需要人工审核——任何无法一对一映射的内容：丢失的 allowed_domains 防护措施、自定义操作逻辑、辅助模型的意图、含义模糊的任务字符串。
• 建议的下一步——使用 Browserbase Context 复用身份验证、在生产环境中使用缓存，或在流程不透明时采用基于跟踪的路径。

7. 提供基于跟踪的路径（仅在有必要时）

如果源代码是一个大型且不透明的 agent(task=…)、运行不稳定，或无法有把握地完成重写映射，则提供基于跟踪的工作流（trace-assisted.md）：在 Browserbase 上运行原始代码，提取 sessions.logs.list，并根据观察到的行为进行重写。未经用户同意，不要运行任何内容。

输出模板

package.json

{
  "name": "stagehand-migration",
  "type": "module",
  "scripts": { "start": "tsx index.ts" },
  "dependencies": {
    "@browserbasehq/stagehand": "^3.0.0",
    "dotenv": "^16.0.0",
    "zod": "^3.25.0"
  },
  "devDependencies": { "tsx": "^4.0.0", "typescript": "^5.0.0" }
}

只有在自定义浏览器操作映射到 Agent tool 时，才添加 "ai": "^5.0.0"（Vercel AI SDK）。固定使用 v5，不要使用 v4——Stagehand 3.6.x 内置 ai v5，并将 agent({ tools }) 的类型定义为 v5 ToolSet，其中工具的 schema 字段为 inputSchema。v4 的 tool() 辅助函数会生成 parameters，因此无法通过与 Stagehand v5 ToolSet 的类型检查。如果你无法控制提升后的 ai 版本，请跳过 tool() 辅助函数，改为传入普通对象 { description, inputSchema: zodSchema, execute }——无论解析到哪个 ai 主版本，它都符合 v5 ToolSet。

.env

BROWSERBASE_API_KEY=...
BROWSERBASE_PROJECT_ID=...
ANTHROPIC_API_KEY=...   # or the provider matching your model string

index.ts 骨架（拆分后的首选结构）

import "dotenv/config";
import { Stagehand } from "@browserbasehq/stagehand";
import { z } from "zod";

async function main() {
  const stagehand = new Stagehand({
    env: "BROWSERBASE",
    model: "anthropic/claude-sonnet-4-6",
  });
  await stagehand.init();
  try {
    const page = stagehand.context.pages()[0];

    await page.goto("https://example.com");          // deterministic skeleton
    await stagehand.act("…");                          // AI where the page varies
    const data = await stagehand.extract("…", z.object({ /* … */ }));  // structured reads

    console.log(data);
  } finally {
    await stagehand.close();
  }
}

main().catch((err) => { console.error(err); process.exit(1); });

验证清单（完成前检查）

• AI 方法属于实例（stagehand.act/extract/observe），而非页面。
• 通过 stagehand.context.pages()[0] 获取页面。
• 模型使用 "provider/model" 字符串；对应的 provider 键位于 .env 中。
• extract 使用 zod schema；依赖项中包含 zod。
• 密钥使用 variables + process.env；不硬编码任何内容。
• 包含 init() / close()；在 finally 中调用 close()。
• 每个浏览器操作步骤都有对应处理，并有意地放置在确定性光谱上的合适位置。
• 迁移摘要列出确定性选择和“需要人工审核”的项目。

常见错误

• 照搬 v2 语法（page.act()、stagehand.page、modelName/modelClientOptions、 enableCaching），这些语法来自旧博客文章。请使用 v3——参见 api-mapping 的“版本说明”。
• 将每一步都转换为 act()——使用 page.goto 导航，并通过 observe→act 缓存可重复的步骤；不要每次操作都调用一次大模型。
• 默认所有操作都使用 agent()——这只是在新框架中复现 browser-use 的非确定性。已知流程应拆分处理。
• 悄悄丢弃 allowed_domains——Stagehand 没有域名防火墙；请标记出来以供审核。
• 臆造 Browserbase/Stagehand 选项——如果不确定某个字段，请查看 https://docs.stagehand.dev/v3 / https://docs.browserbase.com，不要猜测。