KakaFlow KB

BrowserViewer - CLI-Based Browser Automation for Agents

5 phút đọc

BrowserViewer - CLI-Based Browser Automation for Agents

Trust: ★★★☆☆ (0.90) · 0 validations · developer_reference

Published: 2026-05-10 · Source: crawler_authoritative

Tình huống

Mastra documentation for setting up browser automation when agents drive browsers through CLI tools rather than SDKs, targeting developers integrating browser-use, agent-browser, or browse-cli with Mastra agents.

Insight

The @mastra/browser-viewer package provides browser automation for CLI-based tools by launching Chrome via Playwright, exposing a Chrome DevTools Protocol (CDP) URL, and automatically injecting it into CLI commands run through workspace tools. It handles launching and managing Chrome for CLI tools to connect to, automatic CDP URL injection into workspace_execute_command calls, live screencast streaming to Studio, and thread-scoped browser isolation. BrowserViewer supports three CLI providers: agent-browser (CDP flag: —cdp), browser-use (CDP flag: —cdp-url), and browse-cli (CDP flag: —ws). Each CLI must be installed separately in the workspace environment, and each publishes a skill that teaches the agent its commands and workflows. The BrowserViewer class accepts a cli option to specify which CLI the agent uses (e.g., ‘browser-use’), and a headless option to control Chrome’s display mode.

Hành động

Install @mastra/browser-viewer using npm (npm install @mastra/browser-viewer), pnpm (pnpm add @mastra/browser-viewer), yarn (yarn add @mastra/browser-viewer), or bun (bun add @mastra/browser-viewer). Install the desired CLI tool in your workspace environment (e.g., pip install browser-use). Install the corresponding skill so the agent knows how to use the CLI (e.g., npx skills add browser-use/browser-use —skill browser-use). Create a Workspace with BrowserViewer configured, assigning it to an Agent. When the agent runs a CLI command like browser-use open https://example.com, Mastra automatically launches Chrome, injects the CDP connection, and starts streaming the screencast to Studio.

Kết quả

Chrome launches via Playwright (if not already running), the CDP URL is injected into the CLI command so the CLI connects to the managed browser, and screencast frames stream from page-level CDP sessions to Studio for live viewing.

Điều kiện áp dụng

Requires a Workspace setup with LocalSandbox. For CLI-based browser automation only; use AgentBrowser or Stagehand instead for SDK-based browser automation. Each supported CLI (agent-browser, browser-use, browse-cli) must be installed separately.

Nội dung gốc (Original)

BrowserViewer

The @mastra/browser-viewer package provides browser automation for CLI-based tools like agent-browser, browser-use, and browse. BrowserViewer launches Chrome via Playwright, exposes a Chrome DevTools Protocol (CDP) URL, and automatically injects it into CLI commands run through workspace tools.

When to use BrowserViewer

Use BrowserViewer when your agent drives a browser through a CLI tool rather than an SDK. BrowserViewer handles:

  • Launching and managing Chrome for CLI tools to connect to
  • Automatic CDP URL injection into workspace_execute_command calls
  • Live screencast streaming to Studio
  • Thread-scoped browser isolation

For SDK-based browser automation, use AgentBrowser or Stagehand instead.

Quickstart

Install @mastra/browser-viewer and the CLI tool your agent will use. BrowserViewer manages Chrome, but the CLI tool itself must be installed separately.

npm:

npm install @mastra/browser-viewer

pnpm:

pnpm add @mastra/browser-viewer

Yarn:

yarn add @mastra/browser-viewer

Bun:

bun add @mastra/browser-viewer

Install the CLI tool in your workspace environment. This example uses browser-use:

pip install browser-use

Install the corresponding skill so the agent knows how to use the CLI:

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

Create a workspace with BrowserViewer and assign it to an agent:

import { Mastra } from '@mastra/core/mastra'
import { Agent } from '@mastra/core/agent'
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.4',
  workspace,
  instructions: `You are a web automation assistant.
Use browser-use commands to navigate and interact with websites.`,
})
 
export const mastra = new Mastra({
  agents: { browserAgent },
})

When the agent runs a CLI command like browser-use open https://example.com, Mastra automatically launches Chrome, injects the CDP connection, and starts streaming the screencast to Studio.

How it works

  1. The agent calls workspace_execute_command with a browser CLI command.
  2. Mastra detects the CLI command and launches Chrome via Playwright (if not already running).
  3. The CDP URL is injected into the command so the CLI connects to the managed browser.
  4. Screencast frames stream from page-level CDP sessions to Studio.

Supported CLIs

BrowserViewer supports three CLI providers. Each CLI must be installed separately in your workspace environment. Each CLI also publishes a skill that teaches the agent its commands and workflows.

agent-browser

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

CDP flag: --cdp

browser-use

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

CDP flag: --cdp-url

browse-cli

npm install -g @browserbasehq/browse-cli
npx skills add browserbase/skills

CDP flag: --ws

Set the cli option to match the CLI your agent uses:

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

Note: See BrowserViewer reference for all configuration options, advanced connection modes, and method details.

Liên kết

Xem thêm:

Sơ đồ

Liên kết ngược