본문으로 건너뛰기

타빌리 Tool

그만큼@mastra/tavily패키지는타빌리Mastra 호환 Tool로서의 API. 검색, 추출, 크롤링 및 매핑을 위한 팩토리 기능을 노출합니다. 각 함수는 다음으로 생성된 Tool을 반환합니다.createTool()여기에는 전체 Zod 입력/출력 스키마가 포함됩니다.

설치
설치에 대한 직접 링크

npm install @mastra/tavily @tavily/core zod

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

공유 구성이 적용된 네 가지 Tool을 모두 가져오려면 createTavilyTools()를 사용하세요.

src/mastra/tools/index.ts
import { createTavilyTools } from '@mastra/tavily'

const tools = createTavilyTools()
// Or pass an explicit API key:
// const tools = createTavilyTools({ apiKey: 'tvly-...' })

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

src/mastra/tools/index.ts
import { createTavilySearchTool, createTavilyExtractTool } from '@mastra/tavily'

const searchTool = createTavilySearchTool()
const extractTool = createTavilyExtractTool({ apiKey: 'tvly-...' })

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

구성
구성에 대한 직접 링크

모든 팩토리 함수는 @tavily/core의 TavilyClientOptions를 허용합니다.

apiKey?:

string
Tavily API 키입니다. 지정하지 않으면 TAVILY_API_KEY 환경 변수를 사용합니다.

clientName?:

string
= 'mastra'
각 요청의 X-Client-Name 헤더로 전송되는 출처 표시 문자열입니다.

apiBaseURL?:

string
Tavily API의 기본 URL입니다.

proxies?:

object
내부 HTTP 클라이언트에 전달되는 프록시 구성입니다.

projectId?:

string
요청 범위를 지정하는 Tavily 프로젝트 ID입니다.

createTavilyTools()
createtavilytools에 대한 직접 링크

공유 구성이 있는 네 가지 Tool이 모두 포함된 개체를 반환합니다.

import { createTavilyTools } from '@mastra/tavily'

const tools = createTavilyTools({ apiKey: 'tvly-...' })
// tools.tavilySearch, tools.tavilyExtract, tools.tavilyCrawl, tools.tavilyMap

보고: { tavilySearch, tavilyExtract, tavilyCrawl, tavilyMap }

createTavilySearchTool()
createtavilysearchtool에 대한 직접 링크

Tavily를 사용하여 웹을 검색하는 Tool을 만듭니다. 콘텐츠 조각, 선택적 AI 생성 답변 및 이미지와 함께 관련 결과를 반환합니다.

Tool ID: tavily-search

import { createTavilySearchTool } from '@mastra/tavily'

const searchTool = createTavilySearchTool()

입력
입력에 대한 직접 링크

query:

string
검색 쿼리입니다.

searchDepth?:

'basic' | 'advanced' | 'fast' | 'ultra-fast'
검색 깊이입니다. 표준 결과에는 'basic', 더 철저한 결과에는 'advanced', 짧은 지연 시간에는 'fast'/'ultra-fast'를 사용하세요.

maxResults?:

number
반환할 최대 결과 수입니다(1~20).

includeAnswer?:

boolean | 'basic' | 'advanced'
AI가 생성한 답변 요약을 포함합니다.

includeImages?:

boolean
응답에 쿼리 관련 이미지를 포함합니다.

includeImageDescriptions?:

boolean
반환된 이미지의 설명을 포함합니다.

includeRawContent?:

false | 'markdown' | 'text'
각 결과에서 정리된 HTML 콘텐츠를 포함합니다. 비활성화하려면 false를 전달하고, 형식을 지정하려면 'markdown'/'text'를 전달하세요.

includeDomains?:

string[]
결과를 지정된 도메인으로 제한합니다.

excludeDomains?:

string[]
지정된 도메인의 결과를 제외합니다.

timeRange?:

'day' | 'week' | 'month' | 'year'
최신성에 따라 결과를 필터링합니다.

산출
산출에 대한 직접 링크

query:

string
원래 검색 쿼리입니다.

answer?:

string
AI가 생성한 답변 요약입니다.

images?:

{ url: string; description?: string }[]
관련 이미지입니다.

results:

SearchResult[]
검색 결과 배열입니다.
SearchResult

title:

string
Result title.

url:

string
Result URL.

content:

string
Content snippet.

score:

number
Relevance score.

rawContent?:

string
Full-page content (when requested).

responseTime:

number
서버 응답 시간(초)입니다.

createTavilyExtractTool()
createtavilyextracttool에 대한 직접 링크

하나 이상의 URL에서 콘텐츠를 추출하는 Tool을 만듭니다. 요청당 최대 20개의 URL을 사용하여 원시 페이지 콘텐츠를 마크다운 또는 텍스트 형식으로 반환합니다.

Tool ID: tavily-extract

import { createTavilyExtractTool } from '@mastra/tavily'

const extractTool = createTavilyExtractTool()

입력
입력에 대한 직접 링크

urls:

string[]
콘텐츠를 추출할 URL입니다(1~20개).

extractDepth?:

'basic' | 'advanced'
추출 깊이입니다. 표와 삽입된 콘텐츠를 가져오려면 'advanced'를 사용하세요.

query?:

string
추출된 콘텐츠 청크를 관련성에 따라 재정렬하는 데 사용할 사용자 의도입니다.

includeImages?:

boolean
페이지에서 추출한 이미지를 포함합니다.

format?:

'markdown' | 'text'
= 'markdown'
추출된 콘텐츠의 출력 형식입니다.

산출
산출에 대한 직접 링크

results:

ExtractResult[]
성공적으로 추출된 페이지입니다.
ExtractResult

url:

string
Page URL.

rawContent:

string
Extracted page content.

images?:

string[]
Extracted image URLs.

failedResults:

FailedResult[]
추출에 실패한 URL입니다.
FailedResult

url:

string
Failed URL.

error:

string
Error message.

responseTime:

number
서버 응답 시간(초)입니다.

createTavilyCrawlTool()
createtavilycrawltool에 대한 직접 링크

URL에서 시작하여 웹사이트를 크롤링하는 Tool을 만듭니다. 구성 가능한 깊이, 너비 및 도메인 제약 조건을 사용하여 검색된 페이지에서 콘텐츠를 추출합니다.

Tool ID: tavily-crawl

import { createTavilyCrawlTool } from '@mastra/tavily'

const crawlTool = createTavilyCrawlTool()

입력
입력에 대한 직접 링크

url:

string
크롤링을 시작할 루트 URL입니다.

maxDepth?:

number
기본 URL부터 적용되는 최대 크롤링 깊이입니다.

maxBreadth?:

number
페이지마다 따라갈 최대 링크 수입니다.

limit?:

number
크롤러가 중지하기 전까지 처리할 전체 페이지 수입니다.

instructions?:

string
크롤러에 제공할 자연어 지침입니다.

selectPaths?:

string[]
특정 URL 경로를 선택하는 정규식 패턴입니다.

selectDomains?:

string[]
특정 도메인으로 제한하는 정규식 패턴입니다.

excludePaths?:

string[]
특정 URL 경로를 제외하는 정규식 패턴입니다.

excludeDomains?:

string[]
특정 도메인을 제외하는 정규식 패턴입니다.

allowExternal?:

boolean
외부 도메인 링크를 따라갈지 여부입니다.

extractDepth?:

'basic' | 'advanced'
추출 깊이입니다. 표와 삽입된 콘텐츠를 가져오려면 'advanced'를 사용하세요.

includeImages?:

boolean
크롤링한 페이지의 이미지를 포함합니다.

format?:

'markdown' | 'text'
= 'markdown'
추출된 콘텐츠의 출력 형식입니다.

산출
산출에 대한 직접 링크

baseUrl:

string
크롤링한 루트 URL입니다.

results:

CrawlResult[]
발견된 페이지에서 추출한 콘텐츠입니다.
CrawlResult

url:

string
Page URL.

rawContent:

string
Extracted page content.

images?:

string[]
Image URLs found on the page.

responseTime:

number
서버 응답 시간(초)입니다.

createTavilyMapTool()
createtavilymaptool에 대한 직접 링크

URL에서 시작하여 웹사이트 구조를 매핑하는 Tool을 만듭니다. 페이지 콘텐츠를 추출하지 않고 URL 목록을 검색하고 반환합니다. 이를 사용하여 대상 추출 전에 사이트 구조를 이해합니다.

Tool ID: tavily-map

import { createTavilyMapTool } from '@mastra/tavily'

const mapTool = createTavilyMapTool()

입력
입력에 대한 직접 링크

url:

string
매핑을 시작할 루트 URL입니다.

maxDepth?:

number
기본 URL부터 적용되는 최대 매핑 깊이입니다.

maxBreadth?:

number
페이지마다 따라갈 최대 링크 수입니다.

limit?:

number
매퍼가 중지하기 전까지 처리할 전체 링크 수입니다.

instructions?:

string
매퍼에 제공할 자연어 지침입니다.

selectPaths?:

string[]
특정 URL 경로를 선택하는 정규식 패턴입니다.

selectDomains?:

string[]
특정 도메인으로 제한하는 정규식 패턴입니다.

excludePaths?:

string[]
특정 URL 경로를 제외하는 정규식 패턴입니다.

excludeDomains?:

string[]
특정 도메인을 제외하는 정규식 패턴입니다.

allowExternal?:

boolean
외부 도메인 링크를 포함할지 여부입니다.

산출
산출에 대한 직접 링크

baseUrl:

string
매핑한 루트 URL입니다.

results:

string[]
발견된 URL입니다.

responseTime:

number
서버 응답 시간(초)입니다.

Agent 예시
Agent 예시에 대한 직접 링크

다음 예에서는 검색과 추출을 결합하는 연구 Agent를 보여줍니다.

src/mastra/agents/index.ts
import { Agent } from '@mastra/core/agent'
import { createTavilySearchTool, createTavilyExtractTool } from '@mastra/tavily'

const agent = new Agent({
  id: 'web-search-agent',
  name: 'Web Search Agent',
  model: 'anthropic/claude-sonnet-4-6',
  instructions:
    'You are a web search assistant. Use search tool to find relevant pages, then use extract tool to get full content from the best results.',
  tools: {
    search: createTavilySearchTool(),
    extract: createTavilyExtractTool(),
  },
})

환경변수
환경변수에 대한 직접 링크

변수설명
TAVILY_API_KEYTavily API 키입니다. 팩토리 함수에 apiKey를 전달하지 않았을 때 기본값으로 사용됩니다.
On this page