跳到主要内容

Stagehand

@mastra/stagehand 包使用 Browserbase 的 Stagehand SDK 提供浏览器自动化。Stagehand 使用 AI 理解页面上下文并定位元素，因此可以使用自然语言描述，而无需显式选择器。

何时使用 Stagehand
何时使用 Stagehand的直接链接

当你需要以下能力时，请使用 Stagehand：

  • 使用自然语言定位元素（“选择登录按钮”）
  • 从页面中提取 AI 驱动的数据
  • 原生集成 Browserbase 云服务
  • 为常用操作提供更简单的 Tool 接口

快速开始
快速开始的直接链接

安装该包：

npm install @mastra/stagehand

创建浏览器实例并将其分配给 Agent：

src/mastra/agents/stagehand-agent.ts
import { Agent } from '@mastra/core/agent'
import { StagehandBrowser } from '@mastra/stagehand'

const browser = new StagehandBrowser({
  headless: false,
  model: 'openai/gpt-5.6-sol',
})

export const stagehandAgent = new Agent({
  id: 'stagehand-agent',
  name: 'Stagehand Agent',
  model: 'openai/gpt-5.6-sol',
  browser,
  instructions: `You are a web automation assistant.

Use stagehand tools to interact with pages:
- stagehand_navigate to go to URLs
- stagehand_act to perform actions described in natural language
- stagehand_extract to get structured data from the page
- stagehand_observe to find available actions on the page
- stagehand_screenshot to visually inspect the page`,
})

自然语言操作
自然语言操作的直接链接

Agent 使用 stagehand_act Tool 时，该 Tool 接受操作的自然语言描述：

  • “按下登录按钮”
  • “在电子邮件字段中输入 '[user@example.com](mailto:user@example.com)'”
  • “从国家/地区下拉列表中选择‘美国’”

Stagehand 的 AI 会解读操作，并在页面上找到相应元素。

数据提取
数据提取的直接链接

Agent 使用 stagehand_extract Tool 时，可以从页面提取结构化数据。

指令示例：“提取产品名称、价格和库存状态”

Tool 会根据页面内容返回结构化数据：

{
  "name": "Widget Pro",
  "price": "$29.99",
  "availability": "In Stock"
}

观察操作
观察操作的直接链接

Agent 使用 stagehand_observe Tool 时，该 Tool 会分析当前页面并返回可执行的操作。

指令示例：“我可以在此登录表单上执行哪些操作？”

返回可用操作列表：

[
  { "action": "Press 'Sign In' button", "element": "button" },
  { "action": "Type in 'Email' field", "element": "input" },
  { "action": "Open 'Forgot Password' link", "element": "a" }
]

截图
截图的直接链接

当 Agent 使用 stagehand_screenshot Tool 时，它会捕获当前页面的 PNG 图像，并以支持视觉的模型可直接解读的图像内容形式返回。

需要直观检查页面（例如评估图像、布局或颜色）时，请使用截图。对于文本或结构化数据，请改用 stagehand_extract 或 stagehand_observe。

const browser = new StagehandBrowser({
  headless: false,
  model: 'openai/gpt-5.6-sol',
})

要为不支持视觉的模型禁用截图 Tool，请使用 excludeTools：

const browser = new StagehandBrowser({
  headless: false,
  model: 'openai/gpt-5.6-sol',
  excludeTools: ['stagehand_screenshot'],
})

Browserbase
Browserbase的直接链接

Stagehand 原生集成 Browserbase 云浏览器基础设施：

const browser = new StagehandBrowser({
  env: 'BROWSERBASE',
  apiKey: process.env.BROWSERBASE_API_KEY,
  projectId: process.env.BROWSERBASE_PROJECT_ID,
  model: 'openai/gpt-5.6-sol',
})

有关所有配置选项，请参阅 StagehandBrowser 参考。

录制
录制的直接链接

Stagehand 可选择启用 alpha 版浏览器录制 Tool：

const browser = new StagehandBrowser({
  headless: false,
  model: 'openai/gpt-5.6-sol',
  recording: {
    outputDir: './browser-recordings',
  },
})

这会向 Agent 的 Tool 集添加 browser_record 和 browser_record_caption。有关详细信息，请参阅浏览器录制（alpha）。

On this page