跳到主要内容

BrowserViewer

@mastra/browser-viewer 包为 agent-browser、browser-use 和 browse 等基于 CLI 的 Tool 提供浏览器自动化。BrowserViewer 通过 Playwright 启动 Chrome，公开 Chrome DevTools Protocol（CDP）URL，并自动将其注入通过 Workspace Tool 运行的 CLI 命令。

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

当 Agent 通过 CLI Tool（而不是 SDK）操控浏览器时，请使用 BrowserViewer。BrowserViewer 负责：

  • 启动并管理 Chrome，供 CLI Tool 连接
  • 自动将 CDP URL 注入 workspace_execute_command 调用
  • 向 Studio 实时传输投屏画面
  • 按线程隔离浏览器

对于基于 SDK 的浏览器自动化，请改用 AgentBrowser 或 Stagehand。

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

安装 @mastra/browser-viewer 以及 Agent 将使用的 CLI Tool。BrowserViewer 负责管理 Chrome，但 CLI Tool 本身必须单独安装。

npm install @mastra/browser-viewer

在 Workspace 环境中安装 CLI Tool。此示例使用 browser-use：

pip install browser-use

安装相应的 Skill，让 Agent 知道如何使用该 CLI：

npx skills add browser-use/browser-use --skill browser-use

使用 BrowserViewer 创建 Workspace，并将其分配给 Agent：

src/mastra/index.ts
import { Mastra } from '@mastra/core/mastra'
import { Agent } from '@mastra/core/agent'
import { Memory } from '@mastra/memory'
import { LibSQLStore } from '@mastra/libsql'
import { Workspace, LocalSandbox } from '@mastra/core/workspace'
import { BrowserViewer } from '@mastra/browser-viewer'

const workspace = new Workspace({
  sandbox: new LocalSandbox({
    workingDirectory: './workspace',
  }),
  browser: new BrowserViewer({
    cli: 'browser-use',
    headless: false,
  }),
})

const browserAgent = new Agent({
  id: 'browser-agent',
  model: 'openai/gpt-5.6-sol',
  workspace,
  instructions: `You are a web automation assistant.
Use browser-use commands to navigate and interact with websites.`,
  memory: new Memory(),
})

export const mastra = new Mastra({
  agents: { browserAgent },
  storage: new LibSQLStore({
    id: 'mastra-storage',
    url: 'file:./mastra.db',
  }),
})

当 Agent 运行 browser-use open https://example.com 之类的 CLI 命令时，Mastra 会自动启动 Chrome 并注入 CDP 连接，同时开始向 Studio 传输投屏画面。

工作原理
工作原理的直接链接

  1. Agent 使用浏览器 CLI 命令调用 workspace_execute_command。
  2. Mastra 检测到 CLI 命令，并通过 Playwright 启动 Chrome（如果尚未运行）。
  3. CDP URL 会注入命令，使 CLI 连接到托管浏览器。
  4. 投屏帧从页面级 CDP 会话传输到 Studio。

支持的 CLI
支持的 CLI的直接链接

BrowserViewer 支持三个 CLI Provider。每个 CLI 都必须单独安装到 Workspace 环境中。每个 CLI 还会发布一个 Skill，向 Agent 说明其命令和工作方式。

设置 cli 选项，使其与 Agent 使用的 CLI 一致：

const viewer = new BrowserViewer({
  cli: 'browser-use',
  headless: false,
})

agent-browser
agent-browser的直接链接

npm install -g agent-browser
npx skills add vercel-labs/agent-browser

CDP 标志：--cdp

browser-use
browser-use的直接链接

pip install browser-use
npx skills add browser-use/browser-use --skill browser-use

CDP 标志：--cdp-url

browse
browse的直接链接

npm install -g browse
browse skills install

CDP 标志：--ws。有关所有配置选项、高级连接模式和方法详情，请参阅 BrowserViewer 参考。

On this page