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

# 브라우저뷰어

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

Agent가 `browser-use`, `agent-browser`, `browse` 같은 CLI Tool을 통해 브라우저를 제어할 때 `BrowserViewer`를 사용하세요. SDK 기반 브라우저 자동화에는 [`AgentBrowser`](https://mastra.zisheng.pro/ko/reference/browser/agent-browser) 또는 [`StagehandBrowser`](https://mastra.zisheng.pro/ko/reference/browser/stagehand-browser)를 사용하세요.

## 사용예

```typescript
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(),
})
```

### 기존 브라우저에 연결

```typescript
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`): Chrome을 헤드리스 모드로 실행할지 여부입니다. (Default: `true`)

**cdpUrl** (`string | (() => string | Promise<string>)`): 새 브라우저를 실행하는 대신 기존 브라우저에 연결하기 위한 CDP WebSocket URL입니다.

**cdpPort** (`number`): Chrome 원격 디버깅용 포트입니다. Chrome을 실행할 때만 사용됩니다(cdpUrl을 통해 연결할 때는 사용되지 않음). (Default: `0 (자동 할당)`)

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

**viewport** (`{ width: number; height: number }`): 브라우저 뷰포트 크기입니다. (Default: `{ 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'` 범위에서는 지정된 스레드의 브라우저를 실행합니다.

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

#### `ensureReady()`

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

```typescript
await viewer.ensureReady()
```

#### `isBrowserRunning(threadId?)`

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

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

보고:`boolean`

#### `close()`

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

```typescript
await viewer.close()
```

### CDP 액세스

#### `getCdpUrl(threadId?)`

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

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

보고:`string | null`

#### `connectToExternalCdp(cdpUrl, threadId?)`

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

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

### 스크린캐스트

#### `startScreencast(options?)`

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

```typescript
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에서 사용됩니다.

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

#### `injectKeyboardEvent(params, threadId?)`

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

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

## 지원되는 CLI

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

### [`agent-browser`](https://www.npmjs.com/package/agent-browser)

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

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

### [`browser-use`](https://pypi.org/project/browser-use/)

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

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

### [`browse`](https://www.npmjs.com/package/browse)(명령:`browse`)

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

```bash
npm install -g browse
browse skills install
```

## 관련된

- [브라우저뷰어 가이드](https://mastra.zisheng.pro/ko/docs/browser/browser-viewer): 설정 및 사용법 연습
- [마스트라브라우저](https://mastra.zisheng.pro/ko/reference/browser/mastra-browser): 기본 클래스 API 참조
- [작업공간 개요](https://mastra.zisheng.pro/ko/docs/workspace/overview): 작업공간 구성