Skip to main content

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

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

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

OptionTypeDefaultDescription
apiKeystringenv varTavily API key
searchDepth’basic’ | ‘advanced''basic’Search depth level
topic’general’ | ‘news’ | ‘finance''general’Search topic category
maxResultsnumber5Maximum number of results
includeAnswerbooleanfalseInclude AI-generated answer
includeImagesbooleanfalseInclude image results
timeRange’day’ | ‘week’ | ‘month’ | ‘year’-Filter by time range
includeDomainsstring[]-Only search these domains
excludeDomainsstring[]-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
OptionTypeDefaultDescription
apiKeystringenv varTavily 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,
});
OptionTypeDefaultDescription
apiKeystringenv varTavily API key
maxDepthnumber2Maximum crawl depth
extractDepth’basic’ | ‘advanced''basic’Content extraction depth
instructionsstring-Instructions for the crawler
allowExternalbooleanfalseAllow 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

  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 for details.