AgentBrowser 클래스

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

신뢰할 수 있고 결정적인 브라우저 자동화가 필요할 때 AgentBrowser를 사용하세요. 자연어를 사용하는 AI 기반 상호작용은 StagehandBrowser를 참조하세요.

사용예

src/mastra/agents/index.ts

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

= true

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

viewport?:

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

= { width: 1280, height: 720 }

브라우저 뷰포트 크기입니다. 고정 크기 대신 실제 브라우저 창에 맞추려면 'window'를 사용합니다.

timeout?:

number

= 30000

브라우저 작업의 기본 제한 시간(밀리초)입니다.

cdpUrl?:

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

기존 브라우저에 연결하기 위한 CDP WebSocket URL입니다. 클라우드 브라우저 Provider에 유용합니다.

scope?:

'shared' | 'thread'

= 'thread' (cdpUrl이 제공되면 'shared')

브라우저 인스턴스 범위입니다. 'shared'는 모든 스레드가 하나의 브라우저를 공유합니다. 'thread'는 각 스레드에 자체 브라우저를 제공합니다.

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도 추가합니다. 브라우저 녹화(알파)를 참조하세요.

핵심 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를 통해 전달하세요.

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

Tool 참조

browser_goto

URL로 이동합니다.

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

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

browser_snapshot

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

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

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

예제 출력:

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

browser_click

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

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

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

browser_type

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

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

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

browser_press

키보드 키를 누르세요.

// 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 중 하나를 제공하세요.

// 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

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

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

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

browser_hover

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

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

browser_back

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

// Tool input (no parameters required)
{}

browser_dialog

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

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

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

browser_wait

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

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

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

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

browser_drag

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

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

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

browser_evaluate

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

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

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

browser_screenshot

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

// Viewport only (default)
{}

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

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

browser_close

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

// Tool input (no parameters required)
{}

심판의 작동 방식

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

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

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

관련된

• 마스트라브라우저: 기본 클래스 참조
• Stagehand브라우저: AI 기반 대안
• 브라우저 개요: 개념 가이드
• Agent 브라우저 가이드: 이용안내