StagehandBrowser 클래스

그만큼StagehandBrowser클래스는 다음을 사용하여 AI 기반 브라우저 자동화를 제공합니다.무대 담당자. 요소 참조 대신 상호 작용을 위해 자연어 지침을 사용합니다.

AI가 자연어로 브라우저 동작을 해석하고 실행하도록 하려면 StagehandBrowser를 사용하세요. 요소 참조를 사용하는 결정론적 자동화는 AgentBrowser를 참조하세요.

사용예

src/mastra/agents/index.ts

import { Agent } from '@mastra/core/agent'
import { StagehandBrowser } from '@mastra/stagehand'

const browser = new StagehandBrowser({
  headless: true,
  model: 'openai/gpt-5.6-sol',
  selfHeal: true,
})

export const browserAgent = new Agent({
  id: 'browser-agent',
  name: 'Browser Agent',
  instructions: `You can browse the web using natural language.
Use stagehand_act to perform actions like "click the login button".
Use stagehand_extract to get data from pages.`,
  model: 'openai/gpt-5.6-sol',
  browser,
})

생성자 매개변수

headless?:

boolean

= true

브라우저를 헤드리스 모드로 실행할지 여부입니다.

viewport?:

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

= { width: 1280, height: 720 }

브라우저 뷰포트 크기입니다. 'window'는 실제 브라우저 창에 맞춰지며 CDP를 통해 연결할 때만 적용됩니다. 로컬에서 실행한 브라우저에는 기본 크기가 사용됩니다.

env?:

'LOCAL' | 'BROWSERBASE'

= 'LOCAL'

브라우저를 실행할 환경입니다. 클라우드에서 실행하려면 'BROWSERBASE'를 사용하세요.

apiKey?:

string

Browserbase API 키입니다. env가 'BROWSERBASE'이면 필수입니다.

projectId?:

string

Browserbase 프로젝트 ID입니다. env가 'BROWSERBASE'이면 필수입니다.

model?:

string | ModelConfiguration

= 'openai/gpt-5.5'

AI 작업을 위한 Model 구성입니다. 'openai/gpt-5.5' 같은 문자열이나 modelName, apiKey, baseURL을 포함하는 객체를 사용할 수 있습니다.

selfHeal?:

boolean

= true

자가 복구 선택자를 활성화합니다. 활성화하면 초기 선택자가 실패해도 Stagehand가 AI를 사용하여 요소를 찾습니다.

domSettleTimeout?:

number

= 5000

동작 후 DOM이 안정될 때까지 기다리는 제한 시간(밀리초)입니다.

verbose?:

0 | 1 | 2

= 1

로깅 상세 수준입니다. 0 = 출력 없음, 1 = 오류만, 2 = 상세 출력입니다.

systemPrompt?:

string

AI 작업을 위한 사용자 정의 시스템 Prompt입니다.

cdpUrl?:

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

기존 브라우저에 연결하기 위한 CDP WebSocket URL 또는 HTTP 엔드포인트입니다. HTTP 엔드포인트는 내부적으로 WebSocket으로 변환됩니다.

scope?:

'shared' | 'thread'

= 'thread' (또는 cdpUrl이 제공된 경우 'shared')

스레드 간 브라우저 인스턴스 범위입니다.

timeout?:

number

= 30000

Stagehand 작업의 기본 제한 시간(밀리초)입니다.

onLaunch?:

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

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

onClose?:

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

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

screencast?:

ScreencastOptions

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

recording?:

BrowserRecordingOptions

브라우저 녹화 Tool을 추가하는 알파 옵션입니다. outputDir을 제공하면 Tool 세트에 browser_record와 browser_record_caption이 추가됩니다. 모든 녹화의 기본값으로 maxDurationMs, maxWidth, maxHeight를 설정할 수도 있습니다.

excludeTools?:

StagehandToolName[]

브라우저 Tool 세트에서 제외할 Tool 이름입니다. 시각 기능 등 특정 기능을 지원하지 않는 Model에 대해 특정 Tool을 비활성화할 때 사용합니다.

Tool

StagehandBrowser브라우저 자동화를 위한 7가지 AI 기반 Tool을 제공합니다.

recording이 구성되면 StagehandBrowser는 알파 Tool인 browser_record와 browser_record_caption도 추가합니다. 브라우저 녹화(알파)를 참조하세요. 핵심 Tool:

Tool	설명
stagehand_act	자연어 지시에 따라 동작을 수행합니다
stagehand_extract	페이지에서 구조화된 데이터를 추출합니다
stagehand_observe	페이지에서 유용한 요소를 찾습니다
stagehand_navigate	URL로 이동합니다
stagehand_tabs	브라우저 탭을 관리합니다
stagehand_screenshot	PNG 스크린샷을 캡처합니다(기본값은 뷰포트이며 전체 페이지는 fullPage: true로 설정)
stagehand_close	브라우저를 닫습니다
특정 Tool을 제외하려면 생성자에서 excludeTools를 전달하세요.

const browser = new StagehandBrowser({
  excludeTools: ['stagehand_screenshot'],
})

Tool 참조

stagehand_act

자연어 지침을 사용하여 작업을 수행합니다. AI는 사용자의 지시를 해석하고 적절한 브라우저 작업을 실행합니다.

// Tool input
{
  "instruction": "click the login button",
  "variables": { "username": "john" },
  "useVision": true,
  "timeout": 30000
}

// With variable substitution
{
  "instruction": "type %email% into the email field",
  "variables": { "email": "user@example.com" }
}

매개변수	유형	설명
instruction	string	자연어 지시(필수)
variables	Record<string, string>	%variableName% 치환을 위한 변수(선택 사항)
useVision	boolean	시각 기능 활성화(선택 사항)
timeout	number	제한 시간(밀리초, 선택 사항)
보고:

interface ActResult {
  success: boolean
  message?: string
  action?: string
  url?: string
}

stagehand_extract

자연어 지침을 사용하여 페이지에서 구조화된 데이터를 추출합니다.

// Basic extraction
{
  "instruction": "extract all product names and prices"
}

// With schema for structured output
{
  "instruction": "extract the product information",
  "schema": {
    "type": "object",
    "properties": {
      "name": { "type": "string" },
      "price": { "type": "number" },
      "inStock": { "type": "boolean" }
    }
  }
}

보고:

interface ExtractResult<T = unknown> {
  success: boolean
  data?: T
  hint?: string
  error?: string
  url?: string
}

stagehand_observe

페이지에서 유용한 요소를 찾아보세요. 선택기와 설명이 포함된 요소 목록을 반환합니다.

// Find specific elements
{
  "instruction": "find all buttons related to checkout"
}

// Find all interactive elements
{
  "onlyVisible": true
}

매개변수	유형	설명
instruction	string	자연어 지시(선택 사항, 모두 찾으려면 생략)
onlyVisible	boolean	표시되는 요소만 포함(선택 사항)
timeout	number	제한 시간(밀리초, 선택 사항)
보고:

interface ObserveResult {
  success: boolean
  actions: StagehandAction[]
  url?: string
}

interface StagehandAction {
  selector: string
  description: string
  method?: string
  arguments?: string[]
}

stagehand_navigate

URL로 이동합니다.

// Tool input
{
  "url": "https://example.com",
  "waitUntil": "domcontentloaded"
}

매개변수	유형	설명
url	string	열 URL(필수)
waitUntil	"load" | "domcontentloaded" | "networkidle"	탐색이 완료된 것으로 간주할 시점(선택 사항)

stagehand_tabs

브라우저 탭을 관리합니다.

// List all tabs
{ "action": "list" }

// Open new tab
{ "action": "new", "url": "https://example.com" }

// Switch to tab by index
{ "action": "switch", "index": 0 }

// Close tab by index (or current if omitted)
{ "action": "close", "index": 1 }

stagehand_screenshot

현재 페이지의 스크린샷을 PNG로 캡처합니다(기본값은 뷰포트이며 전체 페이지를 캡처하려면 fullPage: true로 설정). 시각 기능을 지원하는 Model이 직접 해석할 수 있는 이미지 콘텐츠를 반환합니다. 텍스트나 구조화된 데이터만 필요하다면 stagehand_observe 또는 stagehand_extract를 사용하세요.

// Viewport only (default)
{}

// Full scrollable page
{ "fullPage": true }

매개변수	유형	설명
fullPage	boolean	뷰포트만이 아니라 스크롤 가능한 전체 페이지를 캡처합니다(선택 사항, 기본값: false)

stagehand_close

브라우저를 닫고 리소스를 정리하세요.

// Tool input (no parameters required)
{}

브라우저베이스 사용

Browserbase를 사용하여 클라우드에서 Stagehand를 실행합니다.

const browser = new StagehandBrowser({
  env: 'BROWSERBASE',
  apiKey: process.env.BROWSERBASE_API_KEY,
  projectId: process.env.BROWSERBASE_PROJECT_ID,
  model: 'openai/gpt-5.6-sol',
})

Model 구성

Stagehand 작업을 위한 AI Model을 구성합니다.

// String format: "provider/model"
const browser = new StagehandBrowser({
  model: 'openai/gpt-5.6-sol',
})

// Object format for custom configuration
const browser = new StagehandBrowser({
  model: {
    modelName: 'gpt-5.4',
    apiKey: process.env.OPENAI_API_KEY,
    baseURL: 'https://api.openai.com/v1',
  },
})

AgentBrowser 대 StagehandBrowser

측면	AgentBrowser	StagehandBrowser
접근 방식	결정론적 참조(@e5)	자연어
정밀도	정확한 요소 지정	AI 해석
유연성	먼저 스냅샷 필요	직접 지시
사용 사례	재현 가능한 자동화	적응형 자동화
속도	더 빠름(AI 추론 없음)	더 느림(AI 추론 사용)
정밀하고 재현 가능한 자동화에는 AgentBrowser를 선택하세요. 유연한 자연어 상호작용에는 StagehandBrowser를 선택하세요.

관련된

• 마스트라브라우저: 기본 클래스 참조
• Agent브라우저: 결정론적 대안
• 브라우저 개요: 개념 가이드
• 무대감독 가이드: 이용안내