브라우저뷰어

그만큼BrowserViewer클래스는 CLI 기반 Tool에 대한 브라우저 자동화를 제공합니다. Playwright를 통해 Chrome을 실행하고 CDP(Chrome DevTools Protocol) URL을 노출하며 작업공간 Tool을 통해 실행되는 CLI 명령에 자동으로 삽입합니다.

Agent가 browser-use, agent-browser, browse 같은 CLI Tool을 통해 브라우저를 제어할 때 BrowserViewer를 사용하세요. SDK 기반 브라우저 자동화에는 AgentBrowser 또는 StagehandBrowser를 사용하세요.

사용예

src/mastra/index.ts

import { Workspace, LocalSandbox } from '@mastra/core/workspace'
import { Memory } from '@mastra/memory'
import { BrowserViewer } from '@mastra/browser-viewer'
import { Agent } from '@mastra/core/agent'

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.',
  memory: new Memory(),
})

기존 브라우저에 연결

const viewer = new BrowserViewer({
  cli: 'browser-use',
  cdpUrl: 'ws://127.0.0.1:9222/devtools/browser/abc123',
})

cdpUrl이 제공되면 BrowserViewer는 새 브라우저를 실행하는 대신 기존 브라우저에 연결합니다. 범위의 기본값은 'shared'입니다.

생성자 매개변수

cli:

'agent-browser' | 'browser-use' | 'browse' | 'browse-cli'

Agent가 브라우저 자동화에 사용하는 CLI입니다. CLI는 CDP URL을 통해 Chrome에 연결합니다.

headless?:

boolean

= true

Chrome을 헤드리스 모드로 실행할지 여부입니다.

cdpUrl?:

string | (() => string | Promise<string>)

새 브라우저를 실행하는 대신 기존 브라우저에 연결하기 위한 CDP WebSocket URL입니다.

cdpPort?:

number

= 0 (자동 할당)

Chrome 원격 디버깅용 포트입니다. Chrome을 실행할 때만 사용됩니다(cdpUrl을 통해 연결할 때는 사용되지 않음).

scope?:

'shared' | 'thread'

= 'thread'

브라우저 인스턴스 범위입니다. 'thread'는 각 스레드에 자체 브라우저를 제공합니다. 'shared'는 모든 스레드가 하나의 브라우저를 공유합니다. cdpUrl이 제공되면 기본값은 'shared'입니다.

viewport?:

{ width: number; height: number }

= { width: 1280, height: 720 }

브라우저 뷰포트 크기입니다.

executablePath?:

string

Chrome 실행 파일의 경로입니다. 기본적으로 Playwright에 번들된 Chromium을 사용합니다.

onLaunch?:

(args: { browser: MastraBrowser }) => void | Promise<void>

브라우저가 준비된 후 호출되는 콜백입니다.

onClose?:

(args: { browser: MastraBrowser }) => void | Promise<void>

브라우저가 닫히기 전에 호출되는 콜백입니다.

screencast?:

ScreencastOptions

브라우저 프레임을 Studio로 스트리밍하기 위한 구성입니다.

속성

id:

string

이 브라우저 인스턴스의 고유 식별자입니다. 'browser-viewer-{timestamp}' 형식으로 생성됩니다.

name:

string

'BrowserViewer'

provider:

string

'browser-viewer'

providerType:

'cli'

항상 'cli'입니다. BrowserViewer를 AgentBrowser와 같은 SDK 기반 Provider와 구분합니다.

cli:

'agent-browser' | 'browser-use' | 'browse' | 'browse-cli'

이 인스턴스에 구성된 CLI Provider입니다.

status:

BrowserStatus

현재 브라우저 상태입니다: 'pending', 'launching', 'ready', 'error', 'closing' 또는 'closed'.

행동 양식

수명주기

launch(threadId?)

Chrome을 실행합니다. 'shared' 범위에서는 공유 브라우저 하나를 실행합니다. 'thread' 범위에서는 지정된 스레드의 브라우저를 실행합니다.

await viewer.launch()
await viewer.launch('thread-123')

ensureReady()

브라우저가 실행되어 준비되었는지 확인합니다. 'thread' 범위에서는 필요한 경우 현재 스레드에 새 브라우저를 생성합니다.

await viewer.ensureReady()

isBrowserRunning(threadId?)

브라우저가 실행 중인지 확인합니다. 'thread' 범위에서는 지정된 스레드를 확인합니다.

const running = viewer.isBrowserRunning()
const threadRunning = viewer.isBrowserRunning('thread-123')

보고:boolean

close()

모든 브라우저 인스턴스를 닫고 리소스를 정리합니다.

await viewer.close()

CDP 액세스

getCdpUrl(threadId?)

현재 또는 지정된 스레드에 대한 CDP WebSocket URL을 반환합니다. CLI Tool은 이 URL을 사용하여 관리되는 브라우저에 연결합니다.

const cdpUrl = viewer.getCdpUrl()
// => 'ws://127.0.0.1:52481/devtools/browser/abc...'

보고:string | null

connectToExternalCdp(cdpUrl, threadId?)

스크린캐스트를 위해 CDP URL을 통해 외부 브라우저에 연결합니다. Agent가 자체 브라우저 엔드포인트(예: 클라우드 브라우저 서비스)를 제공하는 경우 이를 사용합니다. BrowserViewer는 브라우저 수명주기를 관리하지 않고 스크린캐스트를 위해 연결합니다.

await viewer.connectToExternalCdp('wss://cloud.example.com/session', 'thread-123')

스크린캐스트

startScreencast(options?)

브라우저 프레임 스트리밍을 시작합니다. 프레임 이벤트를 내보내는 ScreencastStream을 반환합니다. 탭이 변경될 때 새로운 CDP 세션을 생성하여 탭 전환을 자동으로 처리합니다.

const stream = await viewer.startScreencast({
  format: 'jpeg',
  quality: 80,
})

stream.on('frame', frame => {
  console.log('Frame received:', frame.data.length, 'bytes')
})

stream.on('stop', reason => {
  console.log('Screencast stopped:', reason)
})

보고:Promise<ScreencastStream>

입력 주입

injectMouseEvent(params, threadId?)

CDP를 통해 브라우저에 마우스 이벤트를 삽입합니다. 실시간 상호작용을 위해 Studio에서 사용됩니다.

await viewer.injectMouseEvent({
  type: 'mousePressed',
  x: 100,
  y: 200,
  button: 'left',
  clickCount: 1,
})

injectKeyboardEvent(params, threadId?)

CDP를 통해 브라우저에 키보드 이벤트를 삽입합니다. 실시간 상호작용을 위해 Studio에서 사용됩니다.

await viewer.injectKeyboardEvent({
  type: 'keyDown',
  key: 'Enter',
  code: 'Enter',
})

지원되는 CLI

각 CLI는 별도로 설치해야 합니다. 각 CLI에는 Agent에게 명령과 Workflow를 알려 주는 Skill도 있습니다. CLI 명령이 workspace_execute_command를 통해 실행되면 Mastra가 이를 감지하고 올바른 플래그를 사용하여 CDP URL을 자동으로 주입합니다. SDK Provider와 달리 BrowserViewer는 Agent Tool을 제공하지 않습니다. 대신 Agent는 workspace_execute_command를 통해 CLI 명령을 사용합니다.

agent-browser

구성 값:'agent-browser' · CDP flag: --cdp

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

browser-use

구성 값:'browser-use' · CDP flag: --cdp-url

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

browse(명령:browse)

구성 값:'browse' · CDP flag: --ws

npm install -g browse
browse skills install

관련된

• 브라우저뷰어 가이드: 설정 및 사용법 연습
• 마스트라브라우저: 기본 클래스 API 참조
• 작업공간 개요: 작업공간 구성