본문으로 건너뛰기

FirecrawlBrowser 클래스

그만큼FirecrawlBrowser클래스는Firecrawl 브라우저 샌드박스. Firecrawl API를 통해 원격 브라우저 세션을 프로비저닝하고 CDP(Chrome DevTools Protocol)를 통해 연결합니다.

FirecrawlBrowser는 AgentBrowser를 확장하며 동일한 결정적 Tool 세트를 제공합니다. 로컬 Chromium 설치 대신 호스팅된 브라우저 세션을 사용하려면 이 클래스를 사용하세요. 로컬 자동화는 AgentBrowser를 참조하세요. 자연어를 사용하는 AI 기반 상호작용은 StagehandBrowser를 참조하세요.

사용예
사용예에 대한 직접 링크

src/mastra/agents/index.ts
import { Agent } from '@mastra/core/agent'
import { FirecrawlBrowser } from '@mastra/browser-firecrawl'

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

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,
})

생성자 매개변수
생성자 매개변수에 대한 직접 링크

FirecrawlBrowser는 모든 AgentBrowser 생성자 매개변수와 다음 매개변수를 받습니다.

apiKey?:

string
Firecrawl API 키입니다. 없으면 FIRECRAWL_API_KEY 환경 변수를 사용합니다. 둘 다 설정되지 않으면 생성자가 오류를 발생시킵니다.

apiUrl?:

string
자체 호스팅 Firecrawl API의 기본 URL입니다.

firecrawl?:

FirecrawlBrowserSessionOptions
Sandbox 세션을 생성할 때 Firecrawl browser() API에 전달되는 세션 옵션입니다.
FirecrawlBrowserSessionOptions

ttl?:

number
초 단위의 최대 세션 수명입니다.

activityTtl?:

number
Sandbox가 세션을 재활용하기 전까지의 유휴 제한 시간(초)입니다.

streamWebView?:

boolean
true이면 Firecrawl이 원격 세션의 WebView 프레임을 스트리밍할 수 있습니다.

profile?:

{ name: string; saveChanges?: boolean }
이름이 지정된 Firecrawl Sandbox 프로필입니다. 세션 종료 시 쿠키와 로그인 상태를 유지하려면 saveChanges: true로 설정하세요. 프로필 이름만 지정해서는 변경 사항이 저장되지 않습니다. 로컬 Playwright 사용자 데이터 디렉터리 경로인 최상위 AgentBrowser profile 옵션과는 다릅니다.

integration?:

string
Firecrawl 분석 및 라우팅을 위한 통합 레이블입니다.

origin?:

string
Firecrawl 브라우저 세션의 출처 힌트입니다.

세션 수명주기
세션 수명주기에 대한 직접 링크

세션 프로비저닝은 AgentBrowser에서 상속된 scope 옵션에 따라 달라집니다.

  • 'thread'(기본값): 각 대화 스레드는 처음 사용할 때 생성되고 스레드의 브라우저 세션이 삭제되면 삭제되는 자체 Firecrawl 샌드박스 세션을 갖습니다.
  • 'shared': 브라우저가 시작되고 모든 스레드에서 공유될 때 하나의 Firecrawl 샌드박스 세션이 생성됩니다. 브라우저가 닫히면 세션이 삭제됩니다.

두 경우 모두 브라우저가 닫히면 FirecrawlBrowser가 원격 Firecrawl 세션을 삭제합니다. 세션 생성 또는 연결이 도중에 실패한 경우도 포함됩니다.

Tool
Tool에 대한 직접 링크

FirecrawlBrowser는 browser_goto, browser_snapshot, browser_click, browser_type, browser_screenshot을 포함하여 AgentBrowser와 동일한 Tool 세트를 제공합니다. 전체 목록과 Tool 매개변수는 AgentBrowser Tool 참조를 확인하세요.

On this page