> Discover all available pages from the documentation index: https://mastra.zisheng.pro/llms.txt

# AgentBrowser

`@mastra/agent-browser` 包使用 Playwright 提供浏览器自动化，并优先通过无障碍信息定位元素。元素由页面无障碍树中的引用标识，因此在不同页面布局中也能可靠交互。

## 何时使用 AgentBrowser

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

- 通过无障碍引用可靠定位元素
- 精细控制浏览器操作
- 使用 Playwright 可靠的自动化能力
- 支持键盘快捷键和复杂交互

## 快速开始

安装该包：

**npm**:

```bash
npm install @mastra/agent-browser
```

**pnpm**:

```bash
pnpm add @mastra/agent-browser
```

**Yarn**:

```bash
yarn add @mastra/agent-browser
```

**Bun**:

```bash
bun add @mastra/agent-browser
```

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

```typescript
import { Agent } from '@mastra/core/agent'
import { AgentBrowser } from '@mastra/agent-browser'

const browser = new AgentBrowser({
  headless: false,
})

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

When interacting with pages:
1. Use browser_snapshot to get the current page state and element refs
2. Use the refs (like @e1, @e2) to target elements for clicks and typing
3. After actions, take another snapshot to verify the result`,
})
```

> **备注:** 对于本地启动（默认方式），AgentBrowser 需要安装通过 Playwright 提供的 Chromium 二进制文件。安装 `@mastra/agent-browser` 时通常会自动下载该文件。如果启动浏览器时出现 `"browser executable is missing"` 错误，请运行 `npx playwright install chromium`。如果通过 [`cdpUrl`](https://mastra.zisheng.pro/reference/browser/agent-browser) 选项连接远程浏览器，则由远程浏览器提供 Chromium。

## 截图

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

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

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

```typescript
const browser = new AgentBrowser({
  headless: false,
  excludeTools: ['browser_screenshot'],
})
```

## 元素引用

AgentBrowser 使用无障碍树引用来标识元素。当 Agent 调用 `browser_snapshot` 时，会收到页面的文本表示，其中包含 `@e1`、`@e2` 等引用。随后，Agent 会在其他 Tool 中使用这些引用与元素交互。

## 录制

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

```typescript
const browser = new AgentBrowser({
  headless: false,
  recording: {
    outputDir: './browser-recordings',
  },
})
```

这会向 Agent 的 Tool 集添加 `browser_record` 和 `browser_record_caption`。有关详细信息，请参阅[浏览器录制（alpha）](https://mastra.zisheng.pro/docs/browser/recording)。有关所有配置选项和 Tool 详情，请参阅 [AgentBrowser 参考](https://mastra.zisheng.pro/reference/browser/agent-browser)。

## 相关内容

- [Browser 概览](https://mastra.zisheng.pro/docs/browser/overview)
- [Stagehand](https://mastra.zisheng.pro/docs/browser/stagehand)
- [Firecrawl](https://mastra.zisheng.pro/docs/browser/firecrawl)
- [浏览器录制（alpha）](https://mastra.zisheng.pro/docs/browser/recording)
- [AgentBrowser 参考](https://mastra.zisheng.pro/reference/browser/agent-browser)