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

# MastraBrowser 클래스

그만큼`MastraBrowser`클래스는 브라우저 자동화 공급자의 추상 기본 클래스입니다. 공통 인터페이스에는 브라우저 시작 및 스레드 격리, 스크린캐스트 스트리밍 및 입력 이벤트가 포함됩니다.

`MastraBrowser`를 직접 인스턴스화하지 마세요. 대신 Provider 구현을 사용하세요.

- [`AgentBrowser`](https://mastra.zisheng.pro/ko/reference/browser/agent-browser): 참조를 사용한 결정적 브라우저 자동화
- [`StagehandBrowser`](https://mastra.zisheng.pro/ko/reference/browser/stagehand-browser): 자연어를 활용한 AI 기반 브라우저 자동화
- [`BrowserViewer`](https://mastra.zisheng.pro/ko/reference/browser/browser-viewer): CDP URL 삽입을 통한 CLI 기반 브라우저 자동화

## 사용예

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

const browser = new AgentBrowser({
  headless: true,
  viewport: { width: 1280, height: 720 },
  scope: 'thread',
})

export const browserAgent = new Agent({
  id: 'browser-agent',
  name: 'Browser Agent',
  instructions: 'You can browse the web to find information.',
  model: 'openai/gpt-5.6-sol',
  browser,
})
```

## 생성자 매개변수

**headless** (`boolean`): 브라우저를 헤드리스 모드(표시되는 UI 없음)로 실행할지 여부입니다. (Default: `true`)

**viewport** (`{ width: number; height: number } | 'window'`): 브라우저 뷰포트 크기입니다. 브라우저 창의 크기를 제어합니다. 고정 크기 대신 실제 브라우저 창에 맞추려면 'window'로 설정하세요. agent-browser Provider와 CDP를 통해 연결하는 Stagehand에서 지원됩니다. (Default: `{ width: 1280, height: 720 }`)

**timeout** (`number`): 밀리초 단위의 기본 제한 시간입니다. 각 Provider는 자체 의미와 기본값을 정의합니다. 자세한 내용은 Provider 참조를 확인하세요.

**cdpUrl** (`string | (() => string | Promise<string>)`): CDP WebSocket URL, HTTP 엔드포인트 또는 동기/비동기 Provider 함수입니다. 제공하면 새 브라우저를 실행하는 대신 기존 브라우저에 연결합니다. HTTP 엔드포인트는 내부적으로 WebSocket으로 확인됩니다. scope: 'thread'와 함께 사용할 수 없습니다(자동으로 공유 범위를 사용함).

**scope** (`'shared' | 'thread'`): 스레드 간 브라우저 인스턴스 범위입니다. 'shared'는 모든 스레드가 단일 브라우저 인스턴스를 공유한다는 의미입니다. 'thread'는 각 스레드가 자체 브라우저 인스턴스를 갖는다는 의미입니다(완전 격리). (Default: `'thread' (cdpUrl이 제공되면 'shared')`)

**onLaunch** (`(args: { browser: MastraBrowser }) => void | Promise<void>`): 브라우저가 'ready' 상태에 도달한 후 호출되는 콜백입니다.

**onClose** (`(args: { browser: MastraBrowser }) => void | Promise<void>`): 브라우저가 닫히기 전에 호출되는 콜백입니다.

**screencast** (`ScreencastOptions`): 브라우저 프레임 스트리밍을 위한 구성입니다.

**screencast.format** (`'jpeg' | 'png'`): 스크린캐스트 프레임의 이미지 형식입니다.

**screencast.quality** (`number`): 이미지 품질(1\~100)입니다. JPEG 형식에만 적용됩니다.

**screencast.maxWidth** (`number`): 스크린캐스트 프레임의 최대 너비입니다.

**screencast.maxHeight** (`number`): 스크린캐스트 프레임의 최대 높이입니다.

**screencast.everyNthFrame** (`number`): 대역폭을 줄이기 위해 N번째 프레임마다 캡처합니다.

## 속성

다음 속성(`id`, `name`, `provider`)은 추상 속성이며 구체적인 Provider 구현에서 정의해야 합니다.

**id** (`string`): 이 브라우저 인스턴스의 고유 식별자입니다. 추상 속성이며 Provider에서 정의합니다.

**name** (`string`): 사람이 읽을 수 있는 브라우저 Provider 이름입니다(예: 'AgentBrowser', 'StagehandBrowser'). 추상 속성이며 Provider에서 정의합니다.

**provider** (`string`): Provider 식별자입니다(예: 'vercel-labs/agent-browser', 'browserbase/stagehand'). 추상 속성이며 Provider에서 정의합니다.

**headless** (`boolean`): 브라우저가 헤드리스 모드로 실행 중인지 여부입니다.

**status** (`BrowserStatus`): 현재 브라우저 상태입니다: 'pending', 'launching', 'ready', 'error', 'closing' 또는 'closed'.

## 행동 양식

### 수명주기

#### `ensureReady()`

브라우저가 실행되고 사용할 준비가 되었는지 확인합니다. Tool 실행 전에 자동으로 호출됩니다. 기본 클래스에서 구현됩니다.

```typescript
await browser.ensureReady()
```

#### `close()`

브라우저를 닫고 모든 리소스를 정리합니다. 경쟁 조건에 안전한 처리를 사용하여 기본 클래스에서 구현됩니다.

```typescript
await browser.close()
```

#### `isBrowserRunning()`

브라우저가 현재 실행 중인지 확인합니다.

```typescript
const isRunning = browser.isBrowserRunning()
```

**보고:** `boolean`

### 스레드 관리

#### `setCurrentThread(threadId)`

브라우저 작업을 위한 현재 스레드 ID를 설정합니다. Agent 런타임에서 내부적으로 사용됩니다.

```typescript
browser.setCurrentThread('thread-123')
```

#### `getCurrentThread()`

현재 스레드 ID를 가져옵니다.

```typescript
const threadId = browser.getCurrentThread()
```

**보고:** `string`

#### `hasThreadSession(threadId)`

스레드에 활성 브라우저 세션이 있는지 확인합니다.

```typescript
const hasSession = browser.hasThreadSession('thread-123')
```

**보고:** `boolean`

#### `closeThreadSession(threadId)`

특정 스레드의 브라우저 세션을 닫습니다. '스레드' 범위를 사용하면 해당 스레드의 브라우저 인스턴스를 닫습니다. '공유' 범위를 사용하면 스레드 상태가 지워집니다.

```typescript
await browser.closeThreadSession('thread-123')
```

### Tool

#### `getTools()`

Agent와 함께 사용할 브라우저 Tool을 반환합니다. 각 공급자는 해당 Model에 따라 다양한 Tool을 반환합니다.

```typescript
const tools = browser.getTools()
```

**보고:** `Record<string, Tool>`

### 스크린캐스트

#### `startScreencast(options?, threadId?)`

브라우저 프레임 스트리밍을 시작합니다. 프레임 이벤트를 내보내는 `ScreencastStream`을 반환합니다.

```typescript
const stream = await browser.startScreencast({ format: 'jpeg', quality: 80 }, 'thread-123')

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?)`

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

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

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

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

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

### 상태

#### `getState(threadId?)`

URL 및 탭을 포함하여 현재 브라우저 상태를 가져옵니다.

```typescript
const state = await browser.getState('thread-123')
console.log('Current URL:', state.currentUrl)
console.log('Tabs:', state.tabs)
```

**보고:** `Promise<BrowserState>`

```typescript
interface BrowserState {
  currentUrl: string | null
  tabs: BrowserTabState[]
  activeTabIndex: number
}

interface BrowserTabState {
  id: string
  url: string
  title: string
}
```

#### `getCurrentUrl(threadId?)`

현재 페이지 URL을 가져옵니다.

```typescript
const url = await browser.getCurrentUrl()
```

**보고:** `Promise<string | null>`

## 브라우저 범위

`scope` 옵션은 대화 스레드 간에 브라우저 인스턴스를 공유하는 방식을 제어합니다.

| 범위         | 설명                           | 사용 사례                      |
| ---------- | ---------------------------- | -------------------------- |
| `'shared'` | 모든 스레드가 하나의 브라우저 인스턴스를 공유합니다 | 충돌하지 않는 작업을 비용 효율적으로 처리할 때 |
| `'thread'` | 각 스레드에 자체 브라우저 인스턴스가 제공됩니다   | 동시 사용자를 완전히 격리할 때          |

```typescript
// Shared browser for all threads
const sharedBrowser = new AgentBrowser({
  scope: 'shared',
})

// Isolated browser per thread
const isolatedBrowser = new AgentBrowser({
  scope: 'thread',
})
```

`cdpUrl`을 사용하여 외부 브라우저에 연결하면 새 브라우저 인스턴스를 생성할 수 없으므로 범위가 자동으로 `'shared'`로 대체됩니다.

## 클라우드 브라우저 Provider

다음을 사용하여 클라우드 브라우저 서비스에 연결합니다.`cdpUrl` option:

```typescript
// Static CDP URL
const browser = new AgentBrowser({
  cdpUrl: 'wss://browser.example.com/ws',
})

// Dynamic CDP URL (e.g., session-based)
const browser = new AgentBrowser({
  cdpUrl: async () => {
    const session = await createBrowserSession()
    return session.wsUrl
  },
})
```

## 관련된

- [Agent브라우저](https://mastra.zisheng.pro/ko/reference/browser/agent-browser): 결정론적 브라우저 자동화
- [Stagehand브라우저](https://mastra.zisheng.pro/ko/reference/browser/stagehand-browser): AI 기반 브라우저 자동화
- [브라우저 개요](https://mastra.zisheng.pro/ko/docs/browser/overview): 브라우저 자동화에 대한 개념 가이드