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

# AgentBrowser 클래스

그만큼`AgentBrowser`클래스는 다음을 사용하여 결정적 브라우저 자동화를 제공합니다.[Agent 브라우저](https://github.com/vercel-labs/agent-browser)도서관. 접근성 트리 스냅샷과 요소 참조(예:`@e5`) 정확하고 재현 가능한 상호 작용을 위해.

신뢰할 수 있고 결정적인 브라우저 자동화가 필요할 때 `AgentBrowser`를 사용하세요. 자연어를 사용하는 AI 기반 상호작용은 [`StagehandBrowser`](https://mastra.zisheng.pro/ko/reference/browser/stagehand-browser)를 참조하세요.

## 사용예

```typescript
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. Use browser_snapshot to see the page structure,
then interact with elements using their refs (e.g., @e5).`,
  model: 'openai/gpt-5.6-sol',
  browser,
})
```

## 생성자 매개변수

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

**viewport** (`{ width: number; height: number } | 'window'`): 브라우저 뷰포트 크기입니다. 고정 크기 대신 실제 브라우저 창에 맞추려면 'window'를 사용합니다. (Default: `{ width: 1280, height: 720 }`)

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

**cdpUrl** (`string | (() => string | Promise<string>)`): 기존 브라우저에 연결하기 위한 CDP WebSocket URL입니다. 클라우드 브라우저 Provider에 유용합니다.

**scope** (`'shared' | 'thread'`): 브라우저 인스턴스 범위입니다. 'shared'는 모든 스레드가 하나의 브라우저를 공유합니다. 'thread'는 각 스레드에 자체 브라우저를 제공합니다. (Default: `'thread' (cdpUrl이 제공되면 'shared')`)

**onLaunch** (`(args: { browser: MastraBrowser }) => void | Promise<void>`): 브라우저가 준비된 후 호출되는 콜백입니다.

**onClose** (`(args: { browser: MastraBrowser }) => void | Promise<void>`): 브라우저가 닫히기 전에 호출되는 콜백입니다.

**screencast** (`ScreencastOptions`): 브라우저 프레임을 Studio로 스트리밍하기 위한 구성입니다.

**recording** (`BrowserRecordingOptions`): 브라우저 녹화 Tool을 추가하기 위한 알파 옵션입니다. Tool 세트에 browser\_record와 browser\_record\_caption을 추가하려면 outputDir을 제공하세요. 모든 녹화의 기본값으로 maxDurationMs, maxWidth, maxHeight도 설정할 수 있습니다.

**excludeTools** (`BrowserToolName[]`): 브라우저 Tool 세트에서 제외할 Tool 이름입니다. 비전과 같은 특정 기능을 지원하지 않는 Model에서 특정 Tool을 비활성화할 때 사용하세요.

## Tool

`AgentBrowser`브라우저 자동화를 위한 16가지 결정론적 Tool을 제공합니다. 요소와 상호 작용하는 모든 Tool은 접근성 트리 스냅샷의 참조를 사용합니다.

`recording`이 구성되면 `AgentBrowser`는 알파 `browser_record` 및 `browser_record_caption` Tool도 추가합니다. [브라우저 녹화(알파)](https://mastra.zisheng.pro/ko/docs/browser/recording)를 참조하세요.

### 핵심 Tool

| Tool                 | 설명                                                     |
| -------------------- | ------------------------------------------------------ |
| `browser_goto`       | URL로 이동                                                |
| `browser_snapshot`   | 요소 참조가 포함된 접근성 트리 스냅샷 가져오기                             |
| `browser_click`      | 참조로 요소 클릭                                              |
| `browser_type`       | 요소에 텍스트 입력                                             |
| `browser_press`      | 키보드 키 누르기                                              |
| `browser_select`     | 드롭다운에서 옵션 선택                                           |
| `browser_scroll`     | 페이지 또는 요소 스크롤                                          |
| `browser_screenshot` | 스크린샷을 PNG로 캡처(기본값은 뷰포트이며, 전체 페이지는 `fullPage: true` 설정) |
| `browser_close`      | 브라우저 닫기                                                |

### 확장 Tool

| Tool                                          | 설명                                    |
| --------------------------------------------- | ------------------------------------- |
| `browser_hover`                               | 요소 위에 마우스 올리기                         |
| `browser_back`                                | 브라우저 기록에서 뒤로 이동                       |
| `browser_dialog`                              | 브라우저 대화 상자 처리(alert, confirm, prompt) |
| `browser_wait`                                | 요소 상태 변경 대기                           |
| `browser_tabs`                                | 브라우저 탭 관리(목록, 새 탭, 전환, 닫기)            |
| `browser_drag`                                | 요소 드래그 앤 드롭                           |
| `browser_evaluate`                            | 페이지에서 JavaScript 실행(이스케이프 해치)         |
| 특정 Tool을 제외하려면 생성자의 `excludeTools`를 통해 전달하세요. |                                       |

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

## Tool 참조

### `browser_goto`

URL로 이동합니다.

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

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

### `browser_snapshot`

페이지의 접근성 트리 스냅샷을 가져옵니다. 다른 Tool과 함께 사용할 `@e5` 같은 요소 참조를 반환합니다.

```text
// Tool input
{
  "interactiveOnly": true,
  "maxDepth": 10
}
```

| 매개변수              | 유형        | 설명                                           |
| ----------------- | --------- | -------------------------------------------- |
| `interactiveOnly` | `boolean` | Only include interactive elements (optional) |
| `maxDepth`        | `number`  | Maximum tree depth (optional)                |

**예제 출력:**

```text
[document] Example Page
  [banner]
    [link @e1] Home
    [link @e2] About
  [main]
    [heading @e3] Welcome
    [textbox @e4] Search...
    [button @e5] Submit
```

### `browser_click`

스냅샷의 참조를 사용하여 요소를 클릭합니다.

```text
{
  "ref": "@e5",
  "button": "left",
  "clickCount": 1,
  "modifiers": ["Control", "Shift"]
}
```

| 매개변수         | 유형                              | 설명                       |
| ------------ | ------------------------------- | ------------------------ |
| `ref`        | `string`                        | 스냅샷의 요소 참조(필수)           |
| `button`     | `"left" \| "right" \| "middle"` | 마우스 버튼(선택 사항)            |
| `clickCount` | `number`                        | 활성화 횟수, 두 번 클릭은 2(선택 사항) |
| `modifiers`  | `string[]`                      | 보조 키(선택 사항)              |

### `browser_type`

입력 요소에 텍스트를 입력합니다.

```text
// Tool input
{
  "ref": "@e4",
  "text": "search query",
  "clear": true,
  "delay": 50
}
```

| 매개변수    | 유형        | 설명                        |
| ------- | --------- | ------------------------- |
| `ref`   | `string`  | 스냅샷의 요소 참조(필수)            |
| `text`  | `string`  | 입력할 텍스트(필수)               |
| `clear` | `boolean` | 기존 콘텐츠를 먼저 지울지 여부(선택 사항)  |
| `delay` | `number`  | 키 입력 사이의 지연 시간(ms, 선택 사항) |

### `browser_press`

키보드 키를 누르세요.

```text
// Tool input
{
  "key": "Enter",
  "modifiers": ["Control"]
}

// Key combinations
{ "key": "Control+a" }
{ "key": "Control+c" }
```

| 매개변수        | 유형         | 설명                                                 |
| ----------- | ---------- | -------------------------------------------------- |
| `key`       | `string`   | 키 이름(예: "Enter", "Tab", "Escape", "Control+a")(필수) |
| `modifiers` | `string[]` | 보조 키(선택 사항)                                        |

### `browser_select`

드롭다운에서 옵션을 선택합니다. `value`, `label`, `index` 중 하나를 제공하세요.

```text
// Tool input - by value
{
  "ref": "@e10",
  "value": "option-value"
}

// Tool input - by label
{
  "ref": "@e10",
  "label": "Option Text"
}

// Tool input - by index
{
  "ref": "@e10",
  "index": 0
}
```

### `browser_scroll`

페이지 또는 특정 요소를 스크롤합니다.

```text
// Tool input
{
  "direction": "down",
  "amount": 300,
  "ref": "@e15"
}
```

| 매개변수        | 유형                                    | 설명                           |
| ----------- | ------------------------------------- | ---------------------------- |
| `direction` | `"up" \| "down" \| "left" \| "right"` | 스크롤 방향(필수)                   |
| `amount`    | `number`                              | 스크롤할 픽셀 수, 기본값 300(선택 사항)    |
| `ref`       | `string`                              | 스크롤할 요소, 생략하면 페이지 스크롤(선택 사항) |

### `browser_hover`

요소 위로 마우스를 가져가면 호버 효과가 실행됩니다.

```text
// Tool input
{
  "ref": "@e7"
}
```

### `browser_back`

브라우저 기록으로 돌아갑니다.

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

```

### `browser_dialog`

브라우저 대화 상자(경고, 확인, Prompt)를 처리합니다. 대화 상자를 트리거하는 요소를 클릭하고 처리합니다.

```text
// Tool input
{
  "triggerRef": "@e5",
  "action": "accept",
  "text": "response"
}
```

| 매개변수         | 유형                      | 설명                           |
| ------------ | ----------------------- | ---------------------------- |
| `triggerRef` | `string`                | 대화 상자를 트리거하는 요소(필수)          |
| `action`     | `"accept" \| "dismiss"` | 대화 상자 처리 방법(필수)              |
| `text`       | `string`                | prompt 대화 상자에 입력할 텍스트(선택 사항) |

### `browser_wait`

요소가 특정 상태에 도달할 때까지 기다립니다.

```text
// Tool input
{
  "ref": "@e20",
  "state": "visible",
  "timeout": 30000
}
```

| 매개변수      | 유형                                                  | 설명                  |
| --------- | --------------------------------------------------- | ------------------- |
| `ref`     | `string`                                            | 대기할 요소 참조(선택 사항)    |
| `state`   | `"visible" \| "hidden" \| "attached" \| "detached"` | 대기할 상태(선택 사항)       |
| `timeout` | `number`                                            | 최대 대기 시간(ms, 선택 사항) |

### `browser_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
{ "action": "close", "index": 1 }
```

### `browser_drag`

요소를 대상 위치로 드래그합니다.

```text
// Tool input
{
  "sourceRef": "@e10",
  "targetRef": "@e20"
}
```

| 매개변수        | 유형       | 설명           |
| ----------- | -------- | ------------ |
| `sourceRef` | `string` | 드래그할 요소(필수)  |
| `targetRef` | `string` | 놓을 대상 요소(필수) |

### `browser_evaluate`

페이지 컨텍스트에서 JavaScript를 실행합니다. 다른 Tool로 사용 사례를 다룰 수 없을 때 탈출용 해치로 사용하세요.

```text
// Tool input
{
  "script": "document.title",
  "returnValue": true
}
```

| 매개변수          | 유형        | 설명                 |
| ------------- | --------- | ------------------ |
| `script`      | `string`  | 실행할 JavaScript(필수) |
| `returnValue` | `boolean` | 결과를 반환할지 여부(선택 사항) |

### `browser_screenshot`

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

```text
// Viewport only (default)

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

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

### `browser_close`

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

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

```

## 심판의 작동 방식

`browser_snapshot` Tool은 `@e1`, `@e2` 같은 요소 참조가 포함된 접근성 트리를 반환합니다. 이 참조는 다른 Tool에서 사용하는 안정적인 식별자입니다.

1. `browser_snapshot`을 호출하여 페이지 구조를 확인합니다.
2. 상호작용할 요소를 찾습니다.
3. 해당 참조를 `browser_type` 또는 `browser_scroll` 같은 상호작용 Tool과 함께 사용합니다.

```text
// 1. Get snapshot
// Returns: [textbox @e4] Search... [link @e5] Home

// 2. Type in the search box
{ "tool": "browser_type", "input": { "ref": "@e4", "text": "mastra" } }

// 3. Navigate to home
{ "tool": "browser_goto", "input": { "url": "https://example.com" } }
```

## 관련된

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