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

# 브라이트 데이터 Tool

그만큼`@mastra/brightdata`패키지는[브라이트 데이터 SDK](https://github.com/brightdata/bright-data-sdk-node)Mastra 호환 Tool로. 웹 검색 및 웹 가져오기를 위한 팩토리 기능을 노출합니다. 각 함수는 다음으로 생성된 Tool을 반환합니다.[`createTool()`](https://mastra.zisheng.pro/ko/reference/tools/create-tool)여기에는 전체 Zod 입력/출력 스키마가 포함됩니다.

검색 Tool은 Bright Data의 [SERP API](https://brightdata.com/products/serp-api)를 기반으로 하며, 가져오기 Tool은 [Web Unlocker](https://brightdata.com/products/web-unlocker)를 기반으로 합니다. 둘 다 봇 탐지와 CAPTCHA를 우회합니다.

## 설치

**npm**:

```sh
npm install @mastra/brightdata zod
```

**pnpm**:

```sh
pnpm add @mastra/brightdata zod
```

**Yarn**:

```sh
yarn add @mastra/brightdata zod
```

**Bun**:

```sh
bun add @mastra/brightdata zod
```

## 빠른 시작

공유 구성으로 두 Tool을 모두 가져오려면 `createBrightDataTools()`를 사용하세요.

```typescript
import { createBrightDataTools } from '@mastra/brightdata'

const { webSearch, webFetch } = createBrightDataTools()
// Or pass an explicit API key:
// const { webSearch, webFetch } = createBrightDataTools({ apiKey: 'brd-...' })
```

각 Tool을 개별적으로 만들 수도 있습니다.

```typescript
import { createBrightDataSearchTool, createBrightDataFetchTool } from '@mastra/brightdata'

const searchTool = createBrightDataSearchTool()
const fetchTool = createBrightDataFetchTool({ apiKey: 'brd-...' })
```

기본적으로 모든 Tool은 환경에서 `BRIGHTDATA_API_TOKEN`을 읽습니다. 명시적으로 `{ apiKey }`를 전달하여 재정의할 수 있습니다.

## 구성

모든 팩토리 함수는 `@brightdata/sdk`의 `BrightDataClientOptions`를 허용합니다.

**apiKey** (`string`): Bright Data API 토큰입니다. 제공하지 않으면 BRIGHTDATA\_API\_TOKEN 환경 변수를 사용합니다.

`bdclient` 생성자가 지원하는 추가 필드(예: `timeout`, `webUnlockerZone`, `serpZone`, `rateLimit`)도 동일한 옵션 객체를 통해 전달할 수 있습니다.

## `createBrightDataTools()`

공유 구성이 있는 두 Tool을 모두 포함하는 개체를 반환합니다.

```typescript
import { createBrightDataTools } from '@mastra/brightdata'

const tools = createBrightDataTools({ apiKey: 'brd-...' })
// tools.webSearch, tools.webFetch
```

**보고:** `{ webSearch, webFetch }`

## `createBrightDataSearchTool()`

Bright Data의 SERP API를 통해 Google을 검색하는 Tool을 만듭니다. 구문 분석된 유기적 결과를 반환합니다.

**Tool ID:** `brightdata-search`

```typescript
import { createBrightDataSearchTool } from '@mastra/brightdata'

const searchTool = createBrightDataSearchTool()
```

### 입력

**query** (`string`): 검색 쿼리입니다.

**country** (`string`): 지역 타기팅 결과를 위한 두 자리 국가 코드입니다(예: us 또는 gb).

**start** (`number`): 페이지네이션을 위한 결과 오프셋입니다. 예를 들어 10은 결과 10개로 구성된 두 번째 페이지를 반환합니다.

### 산출

**query** (`string`): 원래 검색 쿼리입니다.

**results** (`SearchResult[]`): 자연 검색 결과입니다. 링크나 제목이 없는 항목은 필터링됩니다.

**results.link** (`string`): Result URL.

**results.title** (`string`): Result title.

**results.description** (`string`): Result snippet.

**currentPage** (`number`): SERP API가 반환한 페이지 번호입니다. 업스트림 응답에서 값이 생략되거나 양수가 아닌 값을 반환하면 기본값은 1입니다.

## `createBrightDataFetchTool()`

Bright Data의 Web Unlocker를 통해 웹페이지를 가져오고 페이지 콘텐츠를 Markdown으로 반환하는 Tool을 만듭니다.

**Tool ID:** `brightdata-fetch`

```typescript
import { createBrightDataFetchTool } from '@mastra/brightdata'

const fetchTool = createBrightDataFetchTool()
```

### 입력

**url** (`string`): 가져올 URL입니다. 유효한 HTTP 또는 HTTPS URL이어야 합니다.

### 산출

**url** (`string`): 입력 URL입니다.

**content** (`string`): Markdown 형식의 페이지 콘텐츠입니다.

## Agent 예시

다음 예는 검색과 가져오기를 결합하는 연구 Agent를 보여줍니다.

```typescript
import { Agent } from '@mastra/core/agent'
import { createBrightDataTools } from '@mastra/brightdata'

const { webSearch, webFetch } = createBrightDataTools()

const agent = new Agent({
  id: 'research-agent',
  name: 'Research Agent',
  model: 'anthropic/claude-sonnet-4-6',
  instructions:
    'You are a research assistant. Use the search tool to find relevant pages, then use the fetch tool to read full Markdown content from the best results.',
  tools: {
    webSearch,
    webFetch,
  },
})
```

## 환경변수

| 변수                     | 설명                                                               |
| ---------------------- | ---------------------------------------------------------------- |
| `BRIGHTDATA_API_TOKEN` | Bright Data API 토큰입니다. 팩토리 함수에 `apiKey`를 전달하지 않았을 때 기본값으로 사용됩니다. |

## 관련된

- [`createTool()`](https://mastra.zisheng.pro/ko/reference/tools/create-tool)
- [브라이트 데이터 SERP API](https://brightdata.com/products/serp-api)
- [브라이트 데이터 웹 언락커](https://brightdata.com/products/web-unlocker)
- [Node.js용 Bright Data SDK](https://github.com/brightdata/bright-data-sdk-node)