Mastra 浏览器 Agent 模板用 Stagehand 构建会导航、观察与提取数据的 AI 网页助手【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra本文以 Mastra monorepo 中的 template-browsing-agent 模板为对象讲解如何将 Browserbase Stagehand 的浏览器自动化能力接入 Mastra 的 Agent 系统。读完后你将掌握该模板从脚手架、环境变量配置到 Agent、四个网页工具导航/观察/操作/提取以及会话管理的完整实现链路并能基于源码修改出自己的浏览器 Agent 应用。模板定位让 Agent 用自然语言操作真实浏览器该模板的核心目标是让 AI Agent 通过 Mastra 框架与网页交互利用 Stagehand 的浏览器自动化能力为 Agent 提供网页导航、元素观察、数据提取和动作执行四类工具并统一由 Mastra 的 Agent 系统编排。相比自己写 Playwright 脚本再拼提示词的做法这个模板把浏览器能力封装成了 Agent 可直接调用的 ToolsAgent 只需根据用户意图决定导航到哪、观察什么、执行哪个动作、提取什么数据。模板提供的能力清单见 README网页导航以编程方式访问任意 URL元素观察在网页上定位并识别元素动作执行点击按钮、填写表单等交互操作数据提取从网页中提取结构化数据会话管理带自动超时与断线重连的智能会话处理AI 驱动交互默认使用 OpenAI 模型完成智能网页交互模型可替换。快速开始从零跑通一个 Browsing Agent前置条件与依赖按 README 说明运行模板需要准备两个 API KeyOpenAI API Key默认模型openai/gpt-5-mini使用可替换为任意受支持的模型Browserbase API Key为 Stagehand 提供云端浏览器用于页面抓取与操作。模板的 .env.example 明确了需要填写的三个变量BROWSERBASE_API_KEY BROWSERBASE_PROJECT_ID OPENAI_API_KEY其中BROWSERBASE_PROJECT_ID是 Stagehand 初始化时的必填项见后文 stage-hand.ts 的构造参数OPENAI_API_KEY则用于 Agent 的默认模型调用。脚手架、安装与启动README 给出的快速开始步骤如下克隆模板执行npx create-mastralatest --template browsing-agent在本地生成项目配置密钥把.env.example复制为.env并填入上述三个变量启动开发服务器执行npm run dev然后打开http://localhost:4111体验。结合 package.json 可以看到dev/build/start三个脚本分别对应mastra dev、mastra build、mastra start即开发、构建与生产运行都由 Mastra CLI 驱动。engines字段要求 Node.js 版本不低于22.13.0搭建环境时需要注意这一前提。核心依赖包括browserbasehq/stagehandv3.1.0、mastra/core、mastra/memory、mastra/libsql、mastra/loggers、mastra/observability以及zodv4。启动后打开 Mastra Studio选择 Web Assistant agent 即可开始对话式体验——这是 README 中Making it yours一节给出的入口。Agent 定义Web Assistant 是如何组装的Agent 的完整定义位于 web-agent.ts它由四个要素构成身份标识、系统指令、模型、工具集与记忆。export const webAgent new Agent({ id: web-agent, name: Web Assistant, instructions: You are a helpful web assistant that can navigate websites and extract information. ... Use the pageActTool to perform actions on webpages. Use the pageObserveTool to find elements on webpages. Use the pageExtractTool to extract data from webpages. Use the pageNavigateTool to navigate to a URL. , model: openai/gpt-5-mini, tools: { pageActTool, pageObserveTool, pageExtractTool, pageNavigateTool }, memory: new Memory(), });几个关键设计点instructions 明确了行为边界系统指令要求 Agent 在用户未提供 URL 时主动询问、明确说明要执行的动作并在提取数据时说清需要哪些信息。指令末尾逐一声明了四个工具的用途帮助模型在规划阶段正确路由到对应工具memory: new Memory()挂载 Mastra Memory 后多轮对话上下文得以保持Agent 能记住当前浏览的页面这类会话级状态模型可替换model只是字符串形式openai/gpt-5-mini替换成其他供应商的模型 ID 即可换用别的模型。四个网页工具导航、观察、操作、提取模板的浏览器能力全部封装在 src/mastra/tools 目录下的四个createTool工具中每个工具都通过 Zod 定义了inputSchema与outputSchema供 Agent 做参数校验与结果结构化。1. pageNavigateToolweb-navigate导航到指定 URLpage-navigate-tool.ts 的入参只有一个必填字段参数类型说明urlstring要导航到的 URL输出为{ success, message?, title?, currentUrl? }。其执行流程通过sessionManager.ensureStagehand()拿到已初始化的 Stagehand 实例取stagehand.context.pages()[0]上下文中的第一个页面调用page.goto(input.url)完成跳转用page.evaluate读取document.title与window.location.href作为结果返回。值得注意的是导航失败时该工具捕获异常并返回{ success: false, message }而不是直接抛出便于 Agent 把失败信息转述给用户或决定重试。2. pageObserveToolweb-observe按自然语言观察元素page-observe-tool.ts 的入参参数类型说明urlstring可选若提供则先导航若已在目标页面可不填instructionstring观察指令例如 find the sign in button输出为z.array(z.any())即可操作项数组。核心逻辑是拿到 Stagehand 实例后若提供了url先page.goto(url)再调用stagehand.observe(instruction)——这一步由 Stagehand 的 AI 能力把页面解析为可交互元素列表并返回。若未提供 instruction则返回空数组。3. pageActToolweb-act执行点击、输入等动作page-act-tool.ts 的入参参数类型说明urlstring可选若提供则先导航到该页面actionstring自然语言动作如 click sign in button、type hello in search field输出为{ success, message }。实现上直接调用stagehand.act(action)由 Stagehand 负责把自然语言动作映射到具体的浏览器操作点击、输入等。与 observe 工具不同act 失败时抛出Web action failed: ...异常由上层 Agent 的运行时处理。4. pageExtractToolweb-extract结构化数据提取page-extract-tool.ts 的入参参数类型说明urlstring可选若提供则先导航instructionstring提取指令如 extract all product pricesschemaunknown可选提取数据的 Zod schema 定义输出为z.unknown()即按 schema 提取出的数据。两个实现细节值得注意默认 schema 兜底若 Agent 未传schema工具会回退到{ content: z.string() }保证至少能提取到一段文本内容schema 包装方式内部执行z.object(finalSchemaObj)后再传给stagehand.extract(instruction, schema)即传入的 schema 对象会被包成 Zod object 使用扩展字段时按 Zod object shape 的形式传入即可。会话管理StagehandSessionManager 的懒初始化与自动重连README 中Session Management一节的实现落在 stage-hand.ts。这是一个单例getInstance()模式的StagehandSessionManager所有工具共享同一个sessionManager导出实例确保多轮操作复用同一浏览器会话。其核心机制懒初始化ensureStagehand()首次调用时才new Stagehand({ apiKey, projectId, env: BROWSERBASE })并执行init()。apiKey与projectId分别取自环境变量BROWSERBASE_API_KEY与BROWSERBASE_PROJECT_ID这也解释了为什么这两个变量是必填的会话健康检查每次ensureStagehand()会读取当前页面document.title作为探测。若返回错误且错误信息包含Target page, context or browser has been closed、Session expired或context destroyed之一则判定会话失效并自动重建 Stagehand 实例其他类型错误则原样上抛空闲超时清理sessionTimeout为 10 分钟构造函数中用setInterval每 60 秒执行一次checkAndCleanupSession()当距上次使用超过 10 分钟时调用stagehand.close()并重置状态防止浏览器会话长期挂起造成资源泄漏失败复位初始化/重连失败时会把initialized置为false、stagehand置为null下次调用将重新走完整初始化流程而不是在一个坏实例上反复重试。这套懒加载 心跳探测 自动重连 空闲回收的组合正是 README 所说automatic timeouts and reconnection的源码级含义。Mastra 实例存储、日志与可观测性配置mastra/index.ts 展示了模板如何把 Agent 挂进一个完整的 Mastra 应用export const mastra new Mastra({ storage: new LibSQLStore({ id: mastra-storage, // stores observability, evals, ... into memory storage, if it needs to persist, change to file:../mastra.db url: :memory:, }), agents: { webAgent }, logger: new PinoLogger({ name: Mastra, level: info }), observability: new Observability({ configs: { default: { serviceName: mastra, exporters: [ new MastraStorageExporter(), // Persists observability events to Mastra Storage new MastraPlatformExporter(), // Sends observability events to Mastra Platform (if MASTRA_CLOUD_ACCESS_TOKEN is set) ], spanOutputProcessors: [ new SensitiveDataFilter(), // Redacts sensitive data like passwords, tokens, keys ], }, }, }), });配置要点存储使用 LibSQL默认:memory:内存模式。源码注释明确提示——如果需要持久化例如让 Memory 的对话记录跨重启保留把url改为file:../mastra.dbAgent 注册agents: { webAgent }以 key 形式注册Studio 与 API 会以此 key 寻址日志PinoLogger名称Mastra级别info可观测性双 exporter 组合——MastraStorageExporter把可观测事件落到 Mastra StorageMastraPlatformExporter在设置了MASTRA_CLOUD_ACCESS_TOKEN时同步到 Mastra PlatformSensitiveDataFilter作为 span 输出处理器对密码、token、key 等敏感数据做脱敏。自定义与二次开发模板的定制入口README Making it yours 一节就是在 Mastra Studio 中选中 Web Assistant agent 进行交互而代码层面的扩展点非常清晰换模型修改 web-agent.ts 中的model字段换工具行为四个工具各自独立成文件新增工具如截图、多页签操作只需按同样的createTool Zod schema sessionManager模式编写并加入tools对象持久化记忆将 index.ts 中 LibSQL 的url由:memory:改为文件路径源码注释给出的建议是file:../mastra.db生产运行npm run build构建后以npm start启动。需要注意的前提限制浏览器操作依赖 Browserbase 云端环境env: BROWSERBASE因此BROWSERBASE_API_KEY与BROWSERBASE_PROJECT_ID缺失时工具会初始化失败Node.js 需要 22.13.0 及以上版本。另外根据 CONTRIBUTING.md该模板目录由 Mastra monorepo 同步生成若要贡献改动应面向 monorepo 中templates/template-browsing-agent路径提交而不是直接修改下游副本。文件地图文件作用templates/template-browsing-agent/README.md模板说明功能、前置条件与快速开始templates/template-browsing-agent/.env.example环境变量模板Browserbase OpenAItemplates/template-browsing-agent/package.json依赖与 dev/build/start 脚本、Node 版本要求templates/template-browsing-agent/src/mastra/index.tsMastra 实例存储、日志、可观测性templates/template-browsing-agent/src/mastra/agents/web-agent.tsWeb Assistant Agent 定义templates/template-browsing-agent/src/mastra/tools/page-navigate-tool.ts导航工具web-navigatetemplates/template-browsing-agent/src/mastra/tools/page-observe-tool.ts观察工具web-observetemplates/template-browsing-agent/src/mastra/tools/page-act-tool.ts动作执行工具web-acttemplates/template-browsing-agent/src/mastra/tools/page-extract-tool.ts数据提取工具web-extracttemplates/template-browsing-agent/src/lib/stage-hand.tsStagehand 单例会话管理器【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考