본문으로 건너뛰기

Agent브라우저

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

AgentBrowser를 사용하는 경우
AgentBrowser를 사용하는 경우에 대한 직접 링크

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

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

빠른 시작
빠른 시작에 대한 직접 링크

패키지를 설치합니다:

npm install @mastra/agent-browser

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

src/mastra/agents/browser-agent.ts
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 옵션으로 원격 브라우저에 연결하면 해당 원격 브라우저에서 Chromium을 제공합니다.

스크린샷
스크린샷에 대한 직접 링크

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

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

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

요소 참조
요소 참조에 대한 직접 링크

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

녹음
녹음에 대한 직접 링크

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

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

이렇게 하면 Agent의 Tool 세트에 browser_record 및 browser_record_caption이 추가됩니다. 자세한 내용은 브라우저 녹화(알파)를 참조하세요. 모든 구성 옵션과 Tool 세부 정보는 AgentBrowser 레퍼런스를 참조하세요.

On this page