Praison AI

Tavily Search

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

Diagram

Input

Agent

Tool

Output

Tavily Search Tool

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

Installation

bash
npm install @tavily/ai-sdk

Environment Variables

bash
export TAVILY_API_KEY=your-api-key

Get your API key at tavily.com.

Quick Start

  1. Simple Usage
    typescript
    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
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:

typescript
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:

typescript
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:

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

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

Examples

Research Agent

typescript
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
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
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
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
interface TavilyExtractResult {
  results: Array<{
    url: string;
    rawContent: string;
  }>;
}

Crawl Response

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

Best Practices

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

Related

Tavily CLI Usage

Command-line interface for Tavily

 Tools Registry

Overview of all available tools

 Exa Search

Alternative semantic search tool