MastraBrowser 클래스

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

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

• AgentBrowser: 참조를 사용한 결정적 브라우저 자동화
• StagehandBrowser: 자연어를 활용한 AI 기반 브라우저 자동화
• BrowserViewer: CDP URL 삽입을 통한 CLI 기반 브라우저 자동화

사용예

src/mastra/agents/index.ts

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

= true

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

viewport?:

{ width: number; height: number } | 'window'

= { width: 1280, height: 720 }

브라우저 뷰포트 크기입니다. 브라우저 창의 크기를 제어합니다. 고정 크기 대신 실제 브라우저 창에 맞추려면 'window'로 설정하세요. agent-browser Provider와 CDP를 통해 연결하는 Stagehand에서 지원됩니다.

timeout?:

number

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

cdpUrl?:

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

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

scope?:

'shared' | 'thread'

= 'thread' (cdpUrl이 제공되면 'shared')

스레드 간 브라우저 인스턴스 범위입니다. 'shared'는 모든 스레드가 단일 브라우저 인스턴스를 공유한다는 의미입니다. 'thread'는 각 스레드가 자체 브라우저 인스턴스를 갖는다는 의미입니다(완전 격리).

onLaunch?:

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

브라우저가 'ready' 상태에 도달한 후 호출되는 콜백입니다.

onClose?:

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

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

screencast?:

ScreencastOptions

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

ScreencastOptions

format?:

'jpeg' | 'png'

스크린캐스트 프레임의 이미지 형식입니다.

quality?:

number

이미지 품질(1~100)입니다. JPEG 형식에만 적용됩니다.

maxWidth?:

number

스크린캐스트 프레임의 최대 너비입니다.

maxHeight?:

number

스크린캐스트 프레임의 최대 높이입니다.

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 실행 전에 자동으로 호출됩니다. 기본 클래스에서 구현됩니다.

await browser.ensureReady()

close()

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

await browser.close()

isBrowserRunning()

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

const isRunning = browser.isBrowserRunning()

보고: boolean

스레드 관리

setCurrentThread(threadId)

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

browser.setCurrentThread('thread-123')

getCurrentThread()

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

const threadId = browser.getCurrentThread()

보고: string

hasThreadSession(threadId)

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

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

보고: boolean

closeThreadSession(threadId)

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

await browser.closeThreadSession('thread-123')

Tool

getTools()

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

const tools = browser.getTools()

보고: Record<string, Tool>

스크린캐스트

startScreencast(options?, threadId?)

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

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

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

injectKeyboardEvent(params, threadId?)

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

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

상태

getState(threadId?)

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

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

보고: Promise<BrowserState>

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

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

getCurrentUrl(threadId?)

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

const url = await browser.getCurrentUrl()

보고: Promise<string | null>

브라우저 범위

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

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

// 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:

// 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브라우저: 결정론적 브라우저 자동화
• Stagehand브라우저: AI 기반 브라우저 자동화
• 브라우저 개요: 브라우저 자동화에 대한 개념 가이드