> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ko/llms.txt

# 파이어 크롤링

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

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

## Firecrawl을 사용해야 하는 경우

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

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

## 빠른 시작

패키지를 설치합니다:

**npm**:

```bash
npm install @mastra/browser-firecrawl
```

**pnpm**:

```bash
pnpm add @mastra/browser-firecrawl
```

**Yarn**:

```bash
yarn add @mastra/browser-firecrawl
```

**Bun**:

```bash
bun add @mastra/browser-firecrawl
```

Firecrawl API 키를 설정합니다.

```bash
FIRECRAWL_API_KEY=fc-...
```

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

```typescript
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 샌드박스 세션은 모든 스레드에서 공유되며 브라우저가 닫히면 삭제됩니다.

```typescript
const browser = new FirecrawlBrowser({
  scope: 'shared',
})
```

## 세션 옵션

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

```typescript
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 API를 사용하려면 다음을 설정하세요.`apiUrl`:

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

## 관련된

- [브라우저 개요](https://mastra.zisheng.pro/ko/docs/browser/overview)
- [Agent브라우저](https://mastra.zisheng.pro/ko/docs/browser/agent-browser)
- [브라우저 녹화(알파)](https://mastra.zisheng.pro/ko/docs/browser/recording)
- [Firecrawl브라우저 참조](https://mastra.zisheng.pro/ko/reference/browser/firecrawl-browser)