브라이트 데이터 Tool

그만큼@mastra/brightdata패키지는브라이트 데이터 SDKMastra 호환 Tool로. 웹 검색 및 웹 가져오기를 위한 팩토리 기능을 노출합니다. 각 함수는 다음으로 생성된 Tool을 반환합니다.createTool()여기에는 전체 Zod 입력/출력 스키마가 포함됩니다.

검색 Tool은 Bright Data의 SERP API를 기반으로 하며, 가져오기 Tool은 Web Unlocker를 기반으로 합니다. 둘 다 봇 탐지와 CAPTCHA를 우회합니다.

설치

npm

npm install @mastra/brightdata zod

pnpm

pnpm add @mastra/brightdata zod

Yarn

yarn add @mastra/brightdata zod

Bun

bun add @mastra/brightdata zod

빠른 시작

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

src/mastra/tools/index.ts

import { createBrightDataTools } from '@mastra/brightdata'

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

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

src/mastra/tools/index.ts

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을 모두 포함하는 개체를 반환합니다.

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

import { createBrightDataSearchTool } from '@mastra/brightdata'

const searchTool = createBrightDataSearchTool()

입력

query:

string

검색 쿼리입니다.

country?:

string

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

start?:

number

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

산출

query:

string

원래 검색 쿼리입니다.

results:

SearchResult[]

자연 검색 결과입니다. 링크나 제목이 없는 항목은 필터링됩니다.

SearchResult

link:

string

Result URL.

title:

string

Result title.

description:

string

Result snippet.

currentPage:

number

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

createBrightDataFetchTool()

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

Tool ID: brightdata-fetch

import { createBrightDataFetchTool } from '@mastra/brightdata'

const fetchTool = createBrightDataFetchTool()

입력

url:

string

가져올 URL입니다. 유효한 HTTP 또는 HTTPS URL이어야 합니다.

산출

url:

string

입력 URL입니다.

content:

string

Markdown 형식의 페이지 콘텐츠입니다.

Agent 예시

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

src/mastra/agents/index.ts

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()
• 브라이트 데이터 SERP API
• 브라이트 데이터 웹 언락커
• Node.js용 Bright Data SDK