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

# 무대 담당자

그만큼`@mastra/stagehand`패키지는 다음을 사용하여 브라우저 자동화를 제공합니다.[스테이지핸드 SDK](https://docs.browserbase.com/stagehand/introduction)브라우저베이스에서. Stagehand는 AI를 사용하여 페이지 컨텍스트를 이해하고 요소를 찾아 명시적인 선택기 대신 자연어 설명을 가능하게 합니다.

## Stagehand를 사용해야 하는 경우

다음이 필요할 때 Stagehand를 사용하세요.

- 자연어 요소 타겟팅("로그인 버튼 선택")
- 페이지에서 AI 기반 데이터 추출
- 기본 브라우저 기반 클라우드 통합
- 일반적인 작업을 위한 더욱 간단한 Tool 인터페이스

## 빠른 시작

패키지를 설치합니다:

**npm**:

```bash
npm install @mastra/stagehand
```

**pnpm**:

```bash
pnpm add @mastra/stagehand
```

**Yarn**:

```bash
yarn add @mastra/stagehand
```

**Bun**:

```bash
bun add @mastra/stagehand
```

브라우저 인스턴스를 생성하고 Agent에 할당합니다.

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

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

export const stagehandAgent = new Agent({
  id: 'stagehand-agent',
  name: 'Stagehand Agent',
  model: 'openai/gpt-5.6-sol',
  browser,
  instructions: `You are a web automation assistant.

Use stagehand tools to interact with pages:
- stagehand_navigate to go to URLs
- stagehand_act to perform actions described in natural language
- stagehand_extract to get structured data from the page
- stagehand_observe to find available actions on the page
- stagehand_screenshot to visually inspect the page`,
})
```

## 자연어 동작

Agent가 `stagehand_act` Tool을 사용하면 자연어로 설명된 동작을 받을 수 있습니다.

- "로그인 버튼을 클릭하세요."
- "이메일 필드에 `'[user@example.com](mailto:user@example.com)'`을 입력하세요."
- "국가 드롭다운에서 '미국'을 선택하세요." Stagehand의 AI는 작업을 해석하고 페이지에서 적절한 요소를 찾습니다.

## 데이터 추출

Agent가 `stagehand_extract` Tool을 사용하면 페이지에서 구조화 데이터를 추출할 수 있습니다. 지침 예시: "제품 이름, 가격, 재고를 추출하세요."

이 Tool은 페이지 콘텐츠를 기반으로 구조화된 데이터를 반환합니다.

```json
{
  "name": "Widget Pro",
  "price": "$29.99",
  "availability": "In Stock"
}
```

## 행동 관찰

Agent가 `stagehand_observe` Tool을 사용하면 현재 페이지를 분석하고 가능한 동작을 반환합니다. 예제 지침: "이 로그인 양식에서 어떤 작업을 수행할 수 있나요?"

사용 가능한 작업 목록을 반환합니다.

```json
[
  { "action": "Press 'Sign In' button", "element": "button" },
  { "action": "Type in 'Email' field", "element": "input" },
  { "action": "Open 'Forgot Password' link", "element": "a" }
]
```

## 스크린샷

Agent가 `stagehand_screenshot` Tool을 사용하면 현재 페이지의 PNG 이미지를 캡처하고 시각 기능을 지원하는 Model이 직접 해석할 수 있는 이미지 콘텐츠로 반환합니다. 이미지, 레이아웃 또는 색상 평가처럼 페이지를 시각적으로 검사해야 할 때는 스크린샷을 사용하세요. 텍스트 또는 구조화 데이터에는 대신 `stagehand_extract` 또는 `stagehand_observe`를 사용하세요.

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

비전을 지원하지 않는 Model의 스크린샷 Tool을 비활성화하려면 다음을 사용하세요.`excludeTools`:

```typescript
const browser = new StagehandBrowser({
  headless: false,
  model: 'openai/gpt-5.6-sol',
  excludeTools: ['stagehand_screenshot'],
})
```

## 브라우저베이스

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

모든 구성 옵션은 [StagehandBrowser 레퍼런스](https://mastra.zisheng.pro/ko/reference/browser/stagehand-browser)를 참조하세요.

## 녹음

Stagehand는 알파 브라우저 녹음 Tool을 선택할 수 있습니다.

```typescript
const browser = new StagehandBrowser({
  headless: false,
  model: 'openai/gpt-5.6-sol',
  recording: {
    outputDir: './browser-recordings',
  },
})
```

이렇게 하면 Agent의 Tool 세트에 `browser_record` 및 `browser_record_caption`이 추가됩니다. 자세한 내용은 [브라우저 녹화(알파)](https://mastra.zisheng.pro/ko/docs/browser/recording)를 참조하세요.

## 관련된

- [브라우저 개요](https://mastra.zisheng.pro/ko/docs/browser/overview)
- [Agent브라우저](https://mastra.zisheng.pro/ko/docs/browser/agent-browser)
- [브라우저 녹화(알파)](https://mastra.zisheng.pro/ko/docs/browser/recording)
- [Stagehand브라우저 참조](https://mastra.zisheng.pro/ko/reference/browser/stagehand-browser)