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

# 타빌리 Tool

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

## 설치

**npm**:

```sh
npm install @mastra/tavily @tavily/core zod
```

**pnpm**:

```sh
pnpm add @mastra/tavily @tavily/core zod
```

**Yarn**:

```sh
yarn add @mastra/tavily @tavily/core zod
```

**Bun**:

```sh
bun add @mastra/tavily @tavily/core zod
```

## 빠른 시작

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

```typescript
import { createTavilyTools } from '@mastra/tavily'

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

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

```typescript
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`): 각 요청의 X-Client-Name 헤더로 전송되는 출처 표시 문자열입니다. (Default: `'mastra'`)

**apiBaseURL** (`string`): Tavily API의 기본 URL입니다.

**proxies** (`object`): 내부 HTTP 클라이언트에 전달되는 프록시 구성입니다.

**projectId** (`string`): 요청 범위를 지정하는 Tavily 프로젝트 ID입니다.

## `createTavilyTools()`

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

```typescript
import { createTavilyTools } from '@mastra/tavily'

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

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

## `createTavilySearchTool()`

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

**Tool ID:** `tavily-search`

```typescript
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[]`): 검색 결과 배열입니다.

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

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

**results.content** (`string`): Content snippet.

**results.score** (`number`): Relevance score.

**results.rawContent** (`string`): Full-page content (when requested).

**responseTime** (`number`): 서버 응답 시간(초)입니다.

## `createTavilyExtractTool()`

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

**Tool ID:** `tavily-extract`

```typescript
import { createTavilyExtractTool } from '@mastra/tavily'

const extractTool = createTavilyExtractTool()
```

### 입력

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

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

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

**includeImages** (`boolean`): 페이지에서 추출한 이미지를 포함합니다.

**format** (`'markdown' | 'text'`): 추출된 콘텐츠의 출력 형식입니다. (Default: `'markdown'`)

### 산출

**results** (`ExtractResult[]`): 성공적으로 추출된 페이지입니다.

**results.url** (`string`): Page URL.

**results.rawContent** (`string`): Extracted page content.

**results.images** (`string[]`): Extracted image URLs.

**failedResults** (`FailedResult[]`): 추출에 실패한 URL입니다.

**failedResults.url** (`string`): Failed URL.

**failedResults.error** (`string`): Error message.

**responseTime** (`number`): 서버 응답 시간(초)입니다.

## `createTavilyCrawlTool()`

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

**Tool ID:** `tavily-crawl`

```typescript
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'`): 추출된 콘텐츠의 출력 형식입니다. (Default: `'markdown'`)

### 산출

**baseUrl** (`string`): 크롤링한 루트 URL입니다.

**results** (`CrawlResult[]`): 발견된 페이지에서 추출한 콘텐츠입니다.

**results.url** (`string`): Page URL.

**results.rawContent** (`string`): Extracted page content.

**results.images** (`string[]`): Image URLs found on the page.

**responseTime** (`number`): 서버 응답 시간(초)입니다.

## `createTavilyMapTool()`

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

**Tool ID:** `tavily-map`

```typescript
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를 보여줍니다.

```typescript
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_KEY` | Tavily API 키입니다. 팩토리 함수에 `apiKey`를 전달하지 않았을 때 기본값으로 사용됩니다. |

## 관련된

- [`createTool()`](https://mastra.zisheng.pro/ko/reference/tools/create-tool)
- [Tavily API 문서](https://docs.tavily.com)