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

# Agent브라우저

그만큼`@mastra/agent-browser`패키지는 접근성 우선 요소 타겟팅과 함께 Playwright를 사용하여 브라우저 자동화를 제공합니다. 요소는 페이지 접근성 트리의 참조로 식별되므로 다양한 페이지 레이아웃에서 상호 작용이 안정적으로 이루어집니다.

## AgentBrowser를 사용하는 경우

다음이 필요한 경우 AgentBrowser를 사용하십시오.

- 접근성 참조를 통한 안정적인 요소 타겟팅
- 브라우저 작업을 세밀하게 제어
- Playwright의 안정적인 자동화 기능
- 키보드 단축키 및 복잡한 상호 작용 지원

## 빠른 시작

패키지를 설치합니다:

**npm**:

```bash
npm install @mastra/agent-browser
```

**pnpm**:

```bash
pnpm add @mastra/agent-browser
```

**Yarn**:

```bash
yarn add @mastra/agent-browser
```

**Bun**:

```bash
bun add @mastra/agent-browser
```

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

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

const browser = new AgentBrowser({
  headless: false,
})

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

When interacting with pages:
1. Use browser_snapshot to get the current page state and element refs
2. Use the refs (like @e1, @e2) to target elements for clicks and typing
3. After actions, take another snapshot to verify the result`,
})
```

> **노트:** 로컬 실행(기본값)의 경우 AgentBrowser에는 Playwright를 통해 설치된 Chromium 바이너리가 필요합니다. 일반적으로 `@mastra/agent-browser` 설치 시 자동으로 다운로드됩니다. 브라우저 실행이 `"browser executable is missing"` 오류와 함께 실패하면 `npx playwright install chromium`을 실행하세요. [`cdpUrl`](https://mastra.zisheng.pro/ko/reference/browser/agent-browser) 옵션으로 원격 브라우저에 연결하면 해당 원격 브라우저에서 Chromium을 제공합니다.

## 스크린샷

Agent가 `browser_screenshot` Tool을 사용하면 현재 페이지의 PNG 이미지를 캡처하고 시각 기능을 지원하는 Model이 직접 해석할 수 있는 이미지 콘텐츠로 반환합니다. 예를 들어 이미지, 레이아웃, 색상 평가 등 페이지를 시각적으로 검사해야 하는 경우 스크린샷을 사용하세요. 텍스트 또는 구조화된 데이터의 경우`browser_snapshot` instead.

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

```typescript
const browser = new AgentBrowser({
  headless: false,
  excludeTools: ['browser_screenshot'],
})
```

## 요소 참조

AgentBrowser는 접근성 트리 참조를 사용해 요소를 식별합니다. Agent가 `browser_snapshot`을 호출하면 `@e1`, `@e2` 등의 참조가 포함된 페이지의 텍스트 표현을 받습니다. 그런 다음 Agent는 다른 Tool에서 이러한 참조를 사용해 요소와 상호 작용합니다.

## 녹음

AgentBrowser는 알파 브라우저 기록 Tool을 선택할 수 있습니다.

```typescript
const browser = new AgentBrowser({
  headless: false,
  recording: {
    outputDir: './browser-recordings',
  },
})
```

이렇게 하면 Agent의 Tool 세트에 `browser_record` 및 `browser_record_caption`이 추가됩니다. 자세한 내용은 [브라우저 녹화(알파)](https://mastra.zisheng.pro/ko/docs/browser/recording)를 참조하세요. 모든 구성 옵션과 Tool 세부 정보는 [AgentBrowser 레퍼런스](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)
- [파이어 크롤링](https://mastra.zisheng.pro/ko/docs/browser/firecrawl)
- [브라우저 녹화(알파)](https://mastra.zisheng.pro/ko/docs/browser/recording)
- [AgentBrowser 참조](https://mastra.zisheng.pro/ko/reference/browser/agent-browser)