Tavily AI SDK tools - Search, Extract, Crawl, and Map
npm install @tavily/ai-sdkAI SDK tools for Tavily, compatible with Vercel's AI SDK v5 and v6.
- Search: Real-time web search optimized for AI applications
- Extract: Clean, structured content extraction from URLs
- Crawl: Intelligent website crawling at scale
- Map: Website structure discovery and mapping
``bash`
npm install @tavily/ai-sdkor
pnpm install @tavily/ai-sdkor
yarn add @tavily/ai-sdk
You need a Tavily API key to use these tools. Get one at tavily.com.
Set your API key as an environment variable:
`bash`
export TAVILY_API_KEY=tvly-your-api-key
Or pass it directly to the tool configuration.
Search the web for real-time, AI-optimized information:
`typescript
import { tavilySearch } from "@tavily/ai-sdk";
import { generateText, gateway, stepCountIs } from "ai";
const result = await generateText({
model: gateway("openai/gpt-5-mini"),
prompt: "What are the latest developments in quantum computing?",
tools: {
tavilySearch: tavilySearch({
searchDepth: "advanced",
includeAnswer: true,
maxResults: 5,
}),
},
stopWhen: stepCountIs(3),
});
`
Configuration Options:
- apiKey?: string - Tavily API key (defaults to TAVILY_API_KEY env var)searchDepth?: "basic" | "advanced"
- - Search depth (default: "basic")topic?: "general" | "news" | "finance"
- - Search category (default: "general")includeImages?: boolean
- - Include images in results (default: false)includeAnswer?: boolean
- - Include AI-generated answer (default: false)maxResults?: number
- - Maximum results to return (default: 5)includeImageDescriptions?: boolean
- - Include AI-generated image descriptionsincludeRawContent?: false | "markdown" | "text"
- - Include raw content in specified formatincludeDomains?: string[]
- - List of domains to include in searchexcludeDomains?: string[]
- - List of domains to exclude from searchmaxTokens?: number
- - Maximum number of tokens in responsetimeRange?: "year" | "month" | "week" | "day" | "y" | "m" | "w" | "d"
- - Time range for resultschunksPerSource?: number
- - Number of content chunks per sourcecountry?: string
- - Country code for localized resultsstartDate?: string
- - Start date for results (YYYY-MM-DD format)endDate?: string
- - End date for results (YYYY-MM-DD format)days?: number
- - Number of days back to search (for news/finance topics)autoParameters?: boolean
- - Enable automatic parameter optimizationtimeout?: number
- - Request timeout in millisecondsincludeFavicon?: boolean
- - Include favicon URLs in resultsincludeUsage?: boolean
- - Whether to include credit usage information in the response.proxies?: { http?: string, https?: string }
- - HTTP/HTTPS proxy configurationapiBaseURL?: string
- - Custom API base URL
Extract clean, structured content from URLs:
`typescript
import { tavilyExtract } from "@tavily/ai-sdk";
import { generateText, gateway, stepCountIs } from "ai";
const result = await generateText({
model: gateway("openai/gpt-5-mini"),
prompt: "Extract and summarize the content from https://tavily.com",
tools: {
tavilyExtract: tavilyExtract(),
},
stopWhen: stepCountIs(3),
});
`
Configuration Options:
- apiKey?: string - Tavily API key (defaults to TAVILY_API_KEY env var)includeImages?: boolean
- - Include images in extracted content (default: false)extractDepth?: "basic" | "advanced"
- - Extraction depth (default: "basic")format?: "markdown" | "text"
- - Output format (default: "markdown")timeout?: number
- - Request timeout in millisecondsincludeFavicon?: boolean
- - Include favicon URLs in resultsincludeUsage?: boolean
- - Whether to include credit usage information in the response. NOTE:The value may be 0 if the total successful URL extractions has not yet reached 5 calls. See our Credits & Pricing documentation for details.proxies?: { http?: string, https?: string }
- - HTTP/HTTPS proxy configurationapiBaseURL?: string
- - Custom API base URL
Input Parameters (for AI agent):
- urls: string[] - Array of URLs to extract content from (required)extractDepth?: "basic" | "advanced"
- - Override extraction depth per call
Crawl websites to discover and extract content from multiple pages:
`typescript
import { tavilyCrawl } from "@tavily/ai-sdk";
import { generateText, gateway, stepCountIs } from "ai";
const result = await generateText({
model: gateway("openai/gpt-5-mini"),
prompt: "Crawl tavily.com and tell me about their integrations",
tools: {
tavilyCrawl: tavilyCrawl(),
},
stopWhen: stepCountIs(3),
});
`
Configuration Options:
- apiKey?: string - Tavily API key (defaults to TAVILY_API_KEY env var)maxDepth?: number
- - Maximum crawl depth (1-5, default: 1)maxBreadth?: number
- - Maximum pages per depth level (1-100, default: 20)limit?: number
- - Maximum total pages to crawl (default: 50)extractDepth?: "basic" | "advanced"
- - Content extraction depthinstructions?: string
- - Natural language crawling instructionsselectPaths?: string[]
- - Path patterns to include (e.g., ["/blog/*"])selectDomains?: string[]
- - Domains to includeexcludePaths?: string[]
- - Path patterns to exclude (e.g., ["/admin/*"])excludeDomains?: string[]
- - Domains to excludeallowExternal?: boolean
- - Allow crawling external domains (default: false)includeImages?: boolean
- - Include images in extracted contentformat?: "markdown" | "text"
- - Output format (default: "markdown")timeout?: number
- - Request timeout in millisecondsincludeFavicon?: boolean
- - Include favicon URLs in resultsincludeUsage?: boolean
- - Whether to include credit usage information in the response. NOTE:The value may be 0 if the total use of /extract and /map have not yet reached minimum requirements. See our Credits & Pricing documentation for details.proxies?: { http?: string, https?: string }
- - HTTP/HTTPS proxy configurationapiBaseURL?: string
- - Custom API base URL
Input Parameters (for AI agent):
- url: string - Base URL to start crawling from (required)maxDepth?: number
- - Override maximum crawl depth per callextractDepth?: "basic" | "advanced"
- - Override extraction depth per callinstructions?: string
- - Override or specify crawling instructions per callallowExternal?: boolean
- - Override external domain crawling setting per call
Map website structure to understand site architecture:
`typescript
import { tavilyMap } from "@tavily/ai-sdk";
import { generateText, gateway, stepCountIs } from "ai";
const result = await generateText({
model: gateway("openai/gpt-5-mini"),
prompt: "Map the structure of tavily.com",
tools: {
tavilyMap: tavilyMap(),
},
stopWhen: stepCountIs(3),
});
`
Configuration Options:
- apiKey?: string - Tavily API key (defaults to TAVILY_API_KEY env var)maxDepth?: number
- - Maximum mapping depth (1-5, default: 1)maxBreadth?: number
- - Maximum pages per depth level (1-100, default: 20)limit?: number
- - Maximum total pages to map (default: 50)instructions?: string
- - Natural language mapping instructionsselectPaths?: string[]
- - Path patterns to include (e.g., ["/docs/*"])selectDomains?: string[]
- - Domains to includeexcludePaths?: string[]
- - Path patterns to exclude (e.g., ["/api/*"])excludeDomains?: string[]
- - Domains to excludeallowExternal?: boolean
- - Allow mapping external domains (default: false)timeout?: number
- - Request timeout in millisecondsproxies?: { http?: string, https?: string }
- - HTTP/HTTPS proxy configurationapiBaseURL?: string
- - Custom API base URLincludeUsage?: boolean
- - Whether to include credit usage information in the response.NOTE:The value may be 0 if the total successful pages mapped has not yet reached 10 calls. See our Credits & Pricing documentation for details.
Input Parameters (for AI agent):
- url: string - Base URL to start mapping from (required)maxDepth?: number
- - Override maximum mapping depth per callinstructions?: string
- - Override or specify mapping instructions per callallowExternal?: boolean
- - Override external domain mapping setting per call
You can combine multiple Tavily tools in a single AI agent:
`typescript
import {
tavilySearch,
tavilyExtract,
tavilyCrawl,
tavilyMap
} from "@tavily/ai-sdk";
import { generateText, gateway, stepCountIs } from "ai";
const result = await generateText({
model: gateway("openai/gpt-5-mini"),
prompt: "Research the company at tavily.com - search for news, map their site, and extract key pages",
tools: {
tavilySearch: tavilySearch({ searchDepth: "advanced" }),
tavilyExtract: tavilyExtract(),
tavilyCrawl: tavilyCrawl(),
tavilyMap: tavilyMap(),
},
stopWhen: stepCountIs(3),
});
`
1. Clone the repository
2. Install dependencies:
`bash`
npm install
3. Create a .env file:
`bash``
TAVILY_API_KEY=tvly-your-api-key
For detailed API documentation, visit docs.tavily.com.
MIT
- Documentation: docs.tavily.com
- Support: help.tavily.com
- Issues: GitHub Issues