Tavily Search Tool

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

Installation

npm install @tavily/ai-sdk

Environment Variables

export TAVILY_API_KEY=your-api-key

Get your API key at tavily.com.

Quick Start

Simple Usage

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);

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:

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:

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:

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:

import { tavilyMap } from '@tavily/ai-sdk';

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

Examples

Research Agent

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

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

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

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

interface TavilyExtractResult {
  results: Array<{
    url: string;
    rawContent: string;
  }>;
}

Crawl Response

interface TavilyCrawlResult {
  baseUrl: string;
  results: Array<{
    url: string;
    rawContent: string;
  }>;
}

Best Practices

Guidelines

Use appropriate search depth: Use basic for quick searches, advanced for comprehensive research
Filter by domain: Use includeDomains to focus on authoritative sources
Time-sensitive queries: Use timeRange for news or recent information
Rate limiting: Tavily has rate limits; implement appropriate delays for batch operations
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 for details.

Tavily CLI Usage

Command-line interface for Tavily

Tools Registry

Overview of all available tools

Exa Search

Alternative semantic search tool

​Tavily Search Tool

​Installation

​Environment Variables

​Quick Start

​Using Tavily Directly

​Tool Options

​tavilySearch

​tavilyExtract

​tavilyCrawl

​tavilyMap

​Examples

​Research Agent

​News Agent

​Content Extraction Agent

​Response Format

​Search Response

​Extract Response

​Crawl Response

​Best Practices

​Pricing

​Related