Documentation Index
Fetch the complete documentation index at: https://docs.praison.ai/llms.txt
Use this file to discover all available pages before exploring further.
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);
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 |
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');
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'
);
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;
}>;
}
interface TavilyExtractResult {
results: Array<{
url: string;
rawContent: string;
}>;
}
Crawl Response
interface TavilyCrawlResult {
baseUrl: string;
results: Array<{
url: string;
rawContent: string;
}>;
}
Best Practices
- 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.