브라우저 개요

브라우저 지원을 통해 Agent은 웹사이트를 통해 이동하고, 페이지 요소와 상호 작용하고, 양식을 채우고, 데이터를 추출할 수 있습니다. Mastra는 브라우저 자동화 라이브러리를 래핑하는 SDK 공급자와 명령줄 Tool을 통해 브라우저를 구동하는 Agent용 CLI 공급자를 통해 브라우저 기능을 제공합니다.

Mastra는 3개의 SDK 공급자와 1개의 CLI 공급자를 지원합니다.

• Agent브라우저: 접근성 우선 요소 타겟팅을 갖춘 극작가 기반 공급자입니다. 일반적인 웹 자동화 및 스크래핑에 가장 적합합니다.
• 무대 담당자: AI 기반 요소 감지 기능을 갖춘 브라우저 베이스 Provider입니다. 자연어 선택기의 이점을 활용하는 복잡한 상호 작용에 가장 적합합니다.
• Firecrawl브라우저: 호스팅된 브라우저 세션에 대해 AgentBrowser Tool을 실행하는 Firecrawl 브라우저 샌드박스 제공자입니다. 로컬 브라우저 인프라를 관리하지 않고 호스팅된 브라우저 세션에서 자동화를 실행하는 데 가장 적합합니다.
• 브라우저뷰어: Chrome을 실행하고 CDP URL을 Agent 브라우저, 브라우저 사용 및 찾아보기와 같은 CLI Tool에 삽입하는 CLI 제공자입니다. 셸 명령을 통해 브라우저를 구동하는 작업공간 Agent에 가장 적합합니다.
• 브라우저 녹화(알파): 브라우저 세션을 선택적 캡션이 포함된 Motion-JPEG AVI 비디오로 저장하는 옵트인 Tool 레이어입니다.

브라우저를 사용해야 하는 경우

Agent가 다음을 수행해야 하는 경우 브라우저를 사용하세요.

• 웹사이트 탐색 및 페이지 요소 상호작용
• 양식 작성 및 데이터 제출
• 웹페이지에서 구조화된 데이터 추출
• 다단계 웹 Workflow 자동화
• 실제 브라우저가 필요한 작업 수행(JavaScript 렌더링, 인증 흐름)

작동 원리

Agent에 브라우저를 할당하면 Mastra는 Agent Tool 세트에 공급자의 Tool을 포함합니다. Agent는 URL 탐색, 요소 선택, 텍스트 입력, 페이지 콘텐츠 읽기 등의 Tool을 사용하여 브라우저를 제어합니다.

각 공급자는 해당 접근 방식에 최적화된 다양한 Tool 세트를 제공합니다.

빠른 시작

선택한 공급자를 설치합니다. 이 예에서는 AgentBrowser 공급자를 사용합니다.

npm

npm install @mastra/agent-browser

pnpm

pnpm add @mastra/agent-browser

Yarn

yarn add @mastra/agent-browser

Bun

bun add @mastra/agent-browser

새 브라우저 인스턴스를 만듭니다.

src/mastra/browsers.ts

import { AgentBrowser } from '@mastra/agent-browser'

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

Agent에 브라우저를 할당합니다.

src/mastra/agents/web-agent.ts

import { Agent } from '@mastra/core/agent'
import { browser } from '../browsers'

export const webAgent = new Agent({
  id: 'web-agent',
  name: 'Web Agent',
  description: 'A web automation assistant that can navigate websites and complete tasks.',
  model: 'openai/gpt-5.6-sol',
  browser,
  instructions:
    'You are a web automation assistant. Use browser tools to navigate websites and complete tasks.',
})

Agent는 공급자로부터 모든 브라우저 Tool을 자동으로 받습니다.

클라우드 Provider

모든 SDK 공급자는 로컬 브라우저를 실행하는 대신 클라우드 브라우저 서비스에 대한 연결을 지원합니다.

Firecrawl 브라우저 샌드박스(FirecrawlBrowser 기본)

FirecrawlBrowser는 Firecrawl API를 통해 호스팅 세션을 프로비저닝합니다.

import { FirecrawlBrowser } from '@mastra/browser-firecrawl'

const browser = new FirecrawlBrowser({
  apiKey: process.env.FIRECRAWL_API_KEY,
})

브라우저베이스(Stagehand 기본)

Stagehand에는 기본 브라우저 베이스 통합 기능이 있습니다.

import { StagehandBrowser } from '@mastra/stagehand'

const browser = new StagehandBrowser({
  env: 'BROWSERBASE',
  apiKey: process.env.BROWSERBASE_API_KEY,
  projectId: process.env.BROWSERBASE_PROJECT_ID,
})

CDP URL(모든 공급자)

Chrome DevTools Protocol(CDP) 엔드포인트를 노출하는 브라우저에 연결합니다.

import { AgentBrowser } from '@mastra/agent-browser'

const browser = new AgentBrowser({
  cdpUrl: process.env.BROWSER_CDP_URL,
  headless: true,
})

이것은 어떤 경우에도 작동합니다.CDP-compatible browser service.

스크린캐스트

브라우저 공급자는 브라우저의 라이브 비디오 피드를 Mastra Studio UI로 스트리밍합니다. 이를 통해 Agent가 페이지와 실시간으로 상호 작용하는 것을 볼 수 있습니다.

스크린캐스트에는 WebSocket 지원이 필요합니다. 프로젝트에 다음 패키지를 설치합니다.

npm

npm install ws @hono/node-ws

pnpm

pnpm add ws @hono/node-ws

Yarn

yarn add ws @hono/node-ws

Bun

bun add ws @hono/node-ws

노트

이러한 패키지는 Cloudflare Workers와 같은 서버리스 환경과 호환되지 않기 때문에 기본적으로 포함되지 않습니다. 설치되지 않은 경우 스크린캐스트가 비활성화되지만 다른 모든 브라우저 기능은 정상적으로 작동합니다.

스크린캐스트는 기본적으로 활성화되어 있으며 다음과 같이 구성할 수 있습니다.

const browser = new AgentBrowser({
  screencast: {
    enabled: true,
    format: 'jpeg',
    quality: 80,
    maxWidth: 1280,
    maxHeight: 720,
  },
})

다음 단계

• Agent브라우저
• 무대 담당자
• 파이어 크롤링
• 브라우저 녹화(알파)
• 브라우저뷰어
• MastraBrowser 참조
• 📹 Mastra browser capabilities workshop