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

# StagehandBrowser 클래스

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

AI가 자연어로 브라우저 동작을 해석하고 실행하도록 하려면 `StagehandBrowser`를 사용하세요. 요소 참조를 사용하는 결정론적 자동화는 [`AgentBrowser`](https://mastra.zisheng.pro/ko/reference/browser/agent-browser)를 참조하세요.

## 사용예

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

**viewport** (`{ width: number; height: number } | 'window'`): 브라우저 뷰포트 크기입니다. 'window'는 실제 브라우저 창에 맞춰지며 CDP를 통해 연결할 때만 적용됩니다. 로컬에서 실행한 브라우저에는 기본 크기가 사용됩니다. (Default: `{ width: 1280, height: 720 }`)

**env** (`'LOCAL' | 'BROWSERBASE'`): 브라우저를 실행할 환경입니다. 클라우드에서 실행하려면 'BROWSERBASE'를 사용하세요. (Default: `'LOCAL'`)

**apiKey** (`string`): Browserbase API 키입니다. env가 'BROWSERBASE'이면 필수입니다.

**projectId** (`string`): Browserbase 프로젝트 ID입니다. env가 'BROWSERBASE'이면 필수입니다.

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

**selfHeal** (`boolean`): 자가 복구 선택자를 활성화합니다. 활성화하면 초기 선택자가 실패해도 Stagehand가 AI를 사용하여 요소를 찾습니다. (Default: `true`)

**domSettleTimeout** (`number`): 동작 후 DOM이 안정될 때까지 기다리는 제한 시간(밀리초)입니다. (Default: `5000`)

**verbose** (`0 | 1 | 2`): 로깅 상세 수준입니다. 0 = 출력 없음, 1 = 오류만, 2 = 상세 출력입니다. (Default: `1`)

**systemPrompt** (`string`): AI 작업을 위한 사용자 정의 시스템 Prompt입니다.

**cdpUrl** (`string | (() => string | Promise<string>)`): 기존 브라우저에 연결하기 위한 CDP WebSocket URL 또는 HTTP 엔드포인트입니다. HTTP 엔드포인트는 내부적으로 WebSocket으로 변환됩니다.

**scope** (`'shared' | 'thread'`): 스레드 간 브라우저 인스턴스 범위입니다. (Default: `'thread' (또는 cdpUrl이 제공된 경우 'shared')`)

**timeout** (`number`): Stagehand 작업의 기본 제한 시간(밀리초)입니다. (Default: `30000`)

**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`도 추가합니다. [브라우저 녹화(알파)](https://mastra.zisheng.pro/ko/docs/browser/recording)를 참조하세요. 핵심 Tool:

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

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

## Tool 참조

### `stagehand_act`

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

```text
// 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`                 | 제한 시간(밀리초, 선택 사항)               |
| **보고:**       |                          |                                 |

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

### `stagehand_extract`

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

```text
// 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" }
    }
  }
}
```

**보고:**

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

### `stagehand_observe`

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

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

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

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

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

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

### `stagehand_navigate`

URL로 이동합니다.

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

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

### `stagehand_tabs`

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

```text
// 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`를 사용하세요.

```text
// Viewport only (default)

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

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

### `stagehand_close`

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

```text
// Tool input (no parameters required)

```

## 브라우저베이스 사용

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

```typescript
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을 구성합니다.

```typescript
// 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`를 선택하세요. |                |                  |

## 관련된

- [마스트라브라우저](https://mastra.zisheng.pro/ko/reference/browser/mastra-browser): 기본 클래스 참조
- [Agent브라우저](https://mastra.zisheng.pro/ko/reference/browser/agent-browser): 결정론적 대안
- [브라우저 개요](https://mastra.zisheng.pro/ko/docs/browser/overview): 개념 가이드
- [무대감독 가이드](https://mastra.zisheng.pro/ko/docs/browser/stagehand): 이용안내