> ## 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

<Steps>
  <Step title="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);
    ```
  </Step>

  <Step title="With Configuration">
    Adjust agent instructions, tool options, and provider settings for production — see the Configuration section below.
  </Step>
</Steps>

## 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

<AccordionGroup>
  <Accordion title="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
  </Accordion>
</AccordionGroup>

## 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

<CardGroup cols={2}>
  <Card title="Tavily CLI Usage" icon="book" href="/js/tools/tavily-cli">
    Command-line interface for Tavily
  </Card>

  <Card title="Tools Registry" icon="book" href="/js/tools/registry">
    Overview of all available tools
  </Card>

  <Card title="Exa Search" icon="book" href="/js/tools/exa">
    Alternative semantic search tool
  </Card>
</CardGroup>