> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Tavily Search

> Web search, content extraction, and crawling with Tavily AI SDK

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    U[Input] --> A[Agent]
    A --> T[Tool]
    T --> O[Output]

    classDef agent fill:#8B0000,color:#fff
    classDef tool fill:#189AB4,color:#fff

    class A agent
    class U,O tool
    class T tool
```

# Tavily Search Tool

Tavily provides AI-optimized web search, content extraction, and website crawling capabilities for your agents.

## Installation

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
npm install @tavily/ai-sdk
```

## Environment Variables

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
export TAVILY_API_KEY=your-api-key
```

Get your API key at [tavily.com](https://tavily.com).

## Quick Start

**1. Simple Usage**

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import { Agent, tools } from 'praisonai';

const agent = new Agent({
  name: 'Researcher',
  instructions: 'You are a research assistant that searches the web for information.',
  tools: [tools.tavily()],
});

const result = await agent.run('What are the latest AI developments?');
console.log(result.text);
```

**2. With Configuration**

Adjust agent instructions, tool options, and provider settings for production — see the Configuration section below.

## Using Tavily Directly

You can also use the Tavily SDK directly with AI SDK's `generateText`:

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import { generateText } from 'ai';
import { openai } from '@ai-sdk/openai';
import { tavilySearch } from '@tavily/ai-sdk';

const { text } = await generateText({
  model: openai('gpt-4o'),
  tools: {
    search: tavilySearch({
      apiKey: process.env.TAVILY_API_KEY,
      maxResults: 5,
      includeAnswer: true,
    }),
  },
  maxSteps: 5,
  prompt: 'Search for the latest AI agent frameworks',
});

console.log(text);
```

## Tool Options

### tavilySearch

| Option | Type | Default | Description |
| - | - | - | - |
| `apiKey` | string | env var | Tavily API key |
| `searchDepth` | 'basic' \| 'advanced' | 'basic' | Search depth level |
| `topic` | 'general' \| 'news' \| 'finance' | 'general' | Search topic category |
| `maxResults` | number | 5 | Maximum number of results |
| `includeAnswer` | boolean | false | Include AI-generated answer |
| `includeImages` | boolean | false | Include image results |
| `timeRange` | 'day' \| 'week' \| 'month' \| 'year' | - | Filter by time range |
| `includeDomains` | string\[] | - | Only search these domains |
| `excludeDomains` | string\[] | - | Exclude these domains |

### tavilyExtract

Extract content from specific URLs:

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import { tavilyExtract } from '@tavily/ai-sdk';

const extractTool = tavilyExtract({
  apiKey: process.env.TAVILY_API_KEY,
  extractDepth: 'advanced',
});

// Use with generateText or agents
```

| Option | Type | Default | Description |
| - | - | - | - |
| `apiKey` | string | env var | Tavily API key |
| `extractDepth` | 'basic' \| 'advanced' | 'basic' | Extraction depth |

### tavilyCrawl

Crawl websites starting from a base URL:

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import { tavilyCrawl } from '@tavily/ai-sdk';

const crawlTool = tavilyCrawl({
  apiKey: process.env.TAVILY_API_KEY,
  maxDepth: 3,
});
```

| Option | Type | Default | Description |
| - | - | - | - |
| `apiKey` | string | env var | Tavily API key |
| `maxDepth` | number | 2 | Maximum crawl depth |
| `extractDepth` | 'basic' \| 'advanced' | 'basic' | Content extraction depth |
| `instructions` | string | - | Instructions for the crawler |
| `allowExternal` | boolean | false | Allow crawling external links |

### tavilyMap

Map website structure:

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import { tavilyMap } from '@tavily/ai-sdk';

const mapTool = tavilyMap({
  apiKey: process.env.TAVILY_API_KEY,
});
```

## Examples

### Research Agent

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import { Agent, tools } from 'praisonai';

const researcher = new Agent({
  name: 'WebResearcher',
  instructions: `You are a thorough research assistant.
  When asked a question:
  1. Search for relevant information
  2. Synthesize findings from multiple sources
  3. Provide a comprehensive answer with citations`,
  tools: [
    tools.tavily({ 
      maxResults: 10, 
      includeAnswer: true,
      searchDepth: 'advanced'
    }),
  ],
});

const result = await researcher.run(
  'What are the key differences between LangChain and CrewAI frameworks?'
);
```

### News Agent

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
const newsAgent = new Agent({
  name: 'NewsAgent',
  instructions: 'You find and summarize the latest news on topics.',
  tools: [
    tools.tavily({ 
      topic: 'news',
      timeRange: 'day',
      maxResults: 5
    }),
  ],
});

const news = await newsAgent.run('Latest AI startup funding news');
```

### Content Extraction Agent

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import { Agent, tools } from 'praisonai';

const extractor = new Agent({
  name: 'ContentExtractor',
  instructions: 'Extract and summarize content from provided URLs.',
  tools: [tools.tavilyExtract()],
});

const content = await extractor.run(
  'Extract the main content from https://example.com/article'
);
```

## Response Format

### Search Response

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
interface TavilySearchResult {
  query: string;
  responseTime: number;
  answer?: string;
  results: Array<{
    title: string;
    url: string;
    content: string;
    score: number;
    publishedDate?: string;
  }>;
  images?: Array<{
    url: string;
    description?: string;
  }>;
}
```

### Extract Response

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
interface TavilyExtractResult {
  results: Array<{
    url: string;
    rawContent: string;
  }>;
}
```

### Crawl Response

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
interface TavilyCrawlResult {
  baseUrl: string;
  results: Array<{
    url: string;
    rawContent: string;
  }>;
}
```

## Best Practices

> [accordion] Guidelines
>
> 1. **Use appropriate search depth**: Use `basic` for quick searches, `advanced` for comprehensive research
> 2. **Filter by domain**: Use `includeDomains` to focus on authoritative sources
> 3. **Time-sensitive queries**: Use `timeRange` for news or recent information
> 4. **Rate limiting**: Tavily has rate limits; implement appropriate delays for batch operations
> 5. **Error handling**: Always handle potential API errors gracefully

## Pricing

Tavily offers:

* **Free tier**: 1,000 searches/month
* **Paid plans**: Higher limits and advanced features

See [tavily.com/pricing](https://tavily.com/pricing) for details.

## Related

> [card] [Tavily CLI Usage](https://praison.ai/docs/js/tools/tavily-cli.md)
>
> Command-line interface for Tavily

> [card] [Tools Registry](https://praison.ai/docs/js/tools/registry.md)
>
> Overview of all available tools

> [card] [Exa Search](https://praison.ai/docs/js/tools/exa.md)
>
> Alternative semantic search tool


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.