본문으로 건너뛰기

파이어 크롤링

그만큼@mastra/browser-firecrawl패키지는 다음을 사용하여 브라우저 자동화를 제공합니다.Firecrawl 브라우저 샌드박스. Firecrawl API를 통해 원격 브라우저 세션을 프로비저닝하고 동일한 결정론적 접근성 우선 Tool을 사용하여 이를 구동합니다.Agent브라우저.

FirecrawlBrowser는 AgentBrowser를 확장하므로 Agent는 동일한 Tool 세트(browser_goto, browser_snapshot, browser_click 등)를 사용하지만 브라우저 자체는 Firecrawl의 호스팅 인프라에서 실행됩니다. 로컬 Chromium 설치가 필요하지 않습니다.

Firecrawl을 사용해야 하는 경우
Firecrawl을 사용해야 하는 경우에 대한 직접 링크

다음과 같은 경우 Firecrawl을 사용하세요.

  • 로컬 Chromium 바이너리를 관리하지 않고 호스팅된 브라우저 세션
  • 로컬 브라우저를 실행할 수 없는 환경의 브라우저 자동화
  • 자동 세션 정리를 통한 스레드별 샌드박스 격리
  • 세션 간 쿠키 및 로그인 상태를 유지하는 명명된 Firecrawl 프로필

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

패키지를 설치합니다:

npm install @mastra/browser-firecrawl

Firecrawl API 키를 설정합니다.

.env
FIRECRAWL_API_KEY=fc-...

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

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

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

export const firecrawlAgent = new Agent({
  id: 'firecrawl-agent',
  name: 'Firecrawl 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`,
})

apiKey를 생략하면 Provider가 환경에서 FIRECRAWL_API_KEY를 읽습니다.

세션 범위
세션 범위에 대한 직접 링크

FirecrawlBrowser는 AgentBrowser와 동일한 scope 옵션을 따릅니다.

  • 'thread'(기본값): 각 대화 스레드는 자체 Firecrawl 샌드박스 세션을 갖습니다. 스레드의 브라우저가 닫히면 세션이 삭제됩니다.
  • 'shared': 하나의 Firecrawl 샌드박스 세션은 모든 스레드에서 공유되며 브라우저가 닫히면 삭제됩니다.
const browser = new FirecrawlBrowser({
  scope: 'shared',
})

세션 옵션
세션 옵션에 대한 직접 링크

Firecrawl 관련 세션 옵션은 firecrawl 키 아래에 전달하세요. 이러한 옵션은 Firecrawl browser() API에 매핑됩니다.

const browser = new FirecrawlBrowser({
  firecrawl: {
    ttl: 600,
    activityTtl: 120,
    profile: {
      name: 'my-profile',
      saveChanges: true,
    },
  },
})
  • ttl: 최대 세션 수명(초)입니다.
  • activityTtl: Firecrawl이 세션을 재활용하기 전까지의 유휴 제한 시간(초)입니다.
  • profile: 쿠키와 로그인 상태를 유지하는 명명된 Firecrawl 프로필입니다. 세션이 종료될 때 프로필 변경 사항을 저장하려면 saveChanges: true를 설정하세요.
노트

중첩된 firecrawl.profile 옵션은 Firecrawl 인프라에 저장된 프로필을 나타냅니다. 이는 AgentBrowser에서 상속되는 최상위 profile 옵션과 다릅니다. 최상위 옵션은 로컬 Playwright 사용자 데이터 디렉터리 경로입니다.

자체 호스팅 Firecrawl
자체 호스팅 Firecrawl에 대한 직접 링크

자체 호스팅 Firecrawl API를 사용하려면 다음을 설정하세요.apiUrl:

const browser = new FirecrawlBrowser({
  apiUrl: 'https://firecrawl.internal.example.com',
})
On this page