Complete Tavily Tutorial: AI Search API for RAG and AI Agents
Tavily is a search API designed specifically for AI applications, Large Language Models (LLMs), and Retrieval-Augmented Generation (RAG). Unlike traditional search APIs like Google Custom Search or Bing API that return lists of URLs, Tavily optimizes search results for direct AI consumption — providing extracted, summarized content ready to be used as LLM context.
In this tutorial, we will learn how to use Tavily from installation, basic usage, integration with LangChain and LlamaIndex, to building powerful RAG applications using Tavily as a real-time knowledge source.
Why Tavily?
When building AI applications that require up-to-date information from the internet, developers face several challenges:
Tavily solves all these problems by providing:
- Pre-extracted and cleaned search results
- Content optimized for LLM consumption
- Support for different search depths (basic and advanced)
- Native integration with popular AI frameworks
- Affordable pricing for production usage
Installation
Python SDK
pip install tavily-python
Node.js SDK
npm install @tavily/core
Getting Your API Key
export TAVILYAPIKEY="tvly-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
Or save it in a .env file:
TAVILYAPIKEY=tvly-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Tavily offers a free tier with 1,000 API calls per month, sufficient for development and prototyping.
Basic Usage
Python — Simple Search
from tavily import TavilyClient
client = TavilyClient(apikey="tvly-YOURAPIKEY")
response = client.search("What is Retrieval Augmented Generation?")
for result in response["results"]:
print(f"Title: {result['title']}")
print(f"URL: {result['url']}")
print(f"Content: {result['content'][:200]}...")
print("---")
Response Structure
{
"query": "What is Retrieval Augmented Generation?",
"followupquestions": None,
"answer": None,
"images": [],
"results": [
{
"title": "What is RAG? - Retrieval-Augmented Generation Explained",
"url": "https://example.com/rag-explained",
"content": "Retrieval-Augmented Generation (RAG) is...",
"score": 0.98,
"rawcontent": None
}
],
"responsetime": 1.23
}
Node.js — Simple Search
const { tavily } = require("@tavily/core");
const client = tavily({ apiKey: "tvly-YOURAPIKEY" });
async function search() {
const response = await client.search("Latest developments in AI agents 2026");
response.results.forEach(result => {
console.log(Title: ${result.title});
console.log(URL: ${result.url});
console.log(Score: ${result.score});
console.log("---");
});
}
search();
Search with Advanced Parameters
from tavily import TavilyClient
client = TavilyClient(apikey="tvly-YOURAPIKEY")
response = client.search(
query="machine learning model deployment best practices",
searchdepth="advanced", # "basic" or "advanced"
topic="general", # "general" or "news"
maxresults=10, # number of results (default: 5)
includedomains=["arxiv.org", "huggingface.co"], # domain filter
excludedomains=["pinterest.com"], # exclude domain
includeanswer=True, # include AI-generated answer
includerawcontent=True, # include raw HTML content
includeimages=True # include relevant images
)
if response.get("answer"):
print(f"AI Answer: {response['answer']}\n")
for result in response["results"]:
print(f"[{result['score']:.2f}] {result['title']}")
print(f" URL: {result['url']}")
print(f" Content: {result['content'][:150]}...")
print()
Search Depth: Basic vs Advanced
Tavily offers two levels of search depth:
Basic Search
- Faster response time (average 1-2 seconds)
- Suitable for general questions and simple facts
- Lower cost per query
- Uses 1 API credit
Advanced Search
- More thorough (average 3-5 seconds)
- Performs multi-step search and analysis
- Extracts more detailed content from each page
- Uses 2 API credits
- Ideal for research and complex questions
basicresult = client.search("Python release date", searchdepth="basic")
advancedresult = client.search(
"Comparison of transformer vs mamba architectures for sequence modeling",
searchdepth="advanced"
)
Context Search for RAG
The getsearchcontext method is specifically designed for RAG pipelines. It returns a string optimized for direct insertion as LLM context.
from tavily import TavilyClient
client = TavilyClient(apikey="tvly-YOURAPIKEY")
context = client.getsearchcontext(
query="How to fine-tune LLMs with LoRA?",
searchdepth="advanced",
maxtokens=4000
)
print(type(context)) #
print(len(context)) # Length of optimized context
print(context[:500]) # Context preview
Using Context with OpenAI
from tavily import TavilyClient
from openai import OpenAI
tavilyclient = TavilyClient(apikey="tvly-YOURAPIKEY")
openaiclient = OpenAI(apikey="sk-YOURAPIKEY")
userquestion = "What are the best practices for deploying ML models to production in 2026?"
context = tavilyclient.getsearchcontext(
query=userquestion,
searchdepth="advanced",
maxtokens=4000
)
response = openaiclient.chat.completions.create(
model="gpt-4o",
messages=[
{
"role": "system",
"content": f"""You are an AI assistant that answers based on current context.
Use the following context to answer the user's question:
{context}
If the information is not in the context, say that you don't have that information."""
},
{
"role": "user",
"content": userquestion
}
]
)
print(response.choices[0].message.content)
Q&A Search
The qnasearch method provides direct answers as a string, perfect for chatbots or quick-answer systems.
answer = client.qnasearch(
query="Who is the CEO of Anthropic and when was the company founded?",
searchdepth="advanced"
)
print(answer)
Output: "Dario Amodei is the CEO of Anthropic. The company was founded in 2021..."
Integration with LangChain
Tavily has official integration with LangChain, making it a powerful tool for building AI agents.
Installation
pip install langchain-community tavily-python langchain-openai
Tavily as a LangChain Tool
import os
from langchaincommunity.tools.tavilysearch import TavilySearchResults
from langchainopenai import ChatOpenAI
from langchain.agents import AgentExecutor, createtoolcallingagent
from langchaincore.prompts import ChatPromptTemplate
os.environ["TAVILYAPIKEY"] = "tvly-YOURAPIKEY"
os.environ["OPENAIAPIKEY"] = "sk-YOURAPIKEY"
searchtool = TavilySearchResults(
maxresults=5,
searchdepth="advanced",
includeanswer=True,
includerawcontent=False
)
tools = [searchtool]
prompt = ChatPromptTemplate.frommessages([
("system", "You are a research assistant that helps find current information from the internet. Always provide source URLs for every piece of information."),
("human", "{input}"),
("placeholder", "{agentscratchpad}")
])
llm = ChatOpenAI(model="gpt-4o", temperature=0)
agent = createtoolcallingagent(llm, tools, prompt)
agentexecutor = AgentExecutor(agent=agent, tools=tools, verbose=True)
result = agentexecutor.invoke({
"input": "What are the latest developments in open-source LLMs?"
})
print(result["output"])
Tavily as a LangChain Retriever
from langchaincommunity.retrievers import TavilySearchAPIRetriever
retriever = TavilySearchAPIRetriever(
k=5,
search
depth="advanced",
includegeneratedanswer=True
)
docs = retriever.invoke("How to use vector databases for RAG")
for doc in docs:
print(f"Source: {doc.metadata['source']}")
print(f"Content: {doc.pagecontent[:200]}...")
print("---")
RAG Chain with LangChain + Tavily
from langchaincommunity.retrievers import TavilySearchAPIRetriever
from langchainopenai import ChatOpenAI
from langchaincore.prompts import ChatPromptTemplate
from langchaincore.outputparsers import StrOutputParser
from langchaincore.runnables import RunnablePassthrough
retriever = TavilySearchAPIRetriever(k=5, searchdepth="advanced")
llm = ChatOpenAI(model="gpt-4o", temperature=0)
template = """Answer the following question based on the provided context.
Include source URLs when possible.
Context:
{context}
Question: {question}
Answer:"""
prompt = ChatPromptTemplate.fromtemplate(template)
def formatdocs(docs):
return "\n\n".join([
f"Source: {doc.metadata.get('source', 'N/A')}\n{doc.pagecontent}"
for doc in docs
])
chain = (
{"context": retriever | formatdocs, "question": RunnablePassthrough()}
| prompt
| llm
| StrOutputParser()
)
answer = chain.invoke("What is mixture of experts in LLMs?")
print(answer)
Integration with LlamaIndex
pip install llama-index llama-index-tools-tavily-research
from llamaindex.tools.tavilyresearch import TavilyToolSpec
from llamaindex.core.agent import ReActAgent
from llamaindex.llms.openai import OpenAI
tavilytool = TavilyToolSpec(apikey="tvly-YOURAPIKEY")
tools = tavilytool.totoollist()
llm = OpenAI(model="gpt-4o", temperature=0)
agent = ReActAgent.fromtools(tools, llm=llm, verbose=True)
response = agent.chat("Search for the latest information about AI agent frameworks in 2026")
print(response)
Building a Research Agent with Tavily
Here is a complete example of building a research agent that can perform multi-step research:
from tavily import TavilyClient
from openai import OpenAI
import json
class ResearchAgent:
def init(self, tavilyapikey, openaiapikey):
self.tavily = TavilyClient(apikey=tavilyapikey)
self.openai = OpenAI(apikey=openaiapikey)
self.researchdata = []
def generatesearchqueries(self, topic):
"""Generate multiple search queries for deeper research."""
response = self.openai.chat.completions.create(
model="gpt-4o",
messages=[
{
"role": "system",
"content": "Generate 3 different search queries for the following research topic. Return as a JSON array of strings."
},
{
"role": "user",
"content": f"Topic: {topic}"
}
],
responseformat={"type": "jsonobject"}
)
result = json.loads(response.choices[0].message.content)
return result.get("queries", [topic])
def searchandcollect(self, queries):
"""Run multiple searches and collect results."""
allresults = []
seenurls = set()
for query in queries:
print(f"Searching: {query}")
response = self.tavily.search(
query=query,
searchdepth="advanced",
maxresults=5,
includeanswer=True
)
for result in response["results"]:
if result["url"] not in seenurls:
seenurls.add(result["url"])
allresults.append({
"query": query,
"title": result["title"],
"url": result["url"],
"content": result["content"],
"score": result["score"]
})
if response.get("answer"):
allresults.append({
"query": query,
"title": "AI-Generated Summary",
"url": "tavily-answer",
"content": response["answer"],
"score": 1.0
})
self.researchdata = sorted(allresults, key=lambda x: x["score"], reverse=True)
return self.researchdata
def synthesizereport(self, topic):
"""Synthesize all research data into a structured report."""
context = "\n\n".join([
f"Source: {r['title']} ({r['url']})\n{r['content']}"
for r in self.researchdata[:10]
])
response = self.openai.chat.completions.create(
model="gpt-4o",
messages=[
{
"role": "system",
"content": """You are a research analyst. Create a comprehensive research report
based on the collected data. The report should be structured with:
Executive Summary
Key Findings (with bullet points)
Analysis
Conclusions and Recommendations
Include reference URLs for every claim."""
},
{
"role": "user",
"content": f"Topic: {topic}\n\nResearch Data:\n{context}"
}
]
)
return response.choices[0].message.content
def research(self, topic):
"""Run the full research pipeline."""
print(f"Starting research on: {topic}\n")
print("Step 1: Generating search queries...")
queries = self.generatesearchqueries(topic)
print(f"Generated {len(queries)} queries\n")
print("Step 2: Searching and collecting data...")
results = self.searchandcollect(queries)
print(f"Collected {len(results)} unique results\n")
print("Step 3: Synthesizing report...")
report = self.synthesizereport(topic)
return {
"topic": topic,
"queriesused": queries,
"sourcescount": len(results),
"report": report,
"sources": [{"title": r["title"], "url": r["url"]} for r in results]
}
agent = ResearchAgent(
tavilyapikey="tvly-YOURAPIKEY",
openaiapikey="sk-YOURAPIKEY"
)
result = agent.research("State of AI Agents in 2026")
print(result["report"])
Extract API
Tavily also provides an Extract API for extracting content from specific URLs:
from tavily import TavilyClient
client = TavilyClient(apikey="tvly-YOURAPIKEY")
response = client.extract(
urls=[
"https://arxiv.org/abs/2005.11401",
"https://huggingface.co/blog/rag-evaluation"
]
)
for result in response["results"]:
print(f"URL: {result['url']}")
print(f"Content length: {len(result['rawcontent'])} chars")
print(f"Content preview: {result['rawcontent'][:300]}...")
print("---")
This is useful when you already know which URLs you want to extract content from, such as from previous search results or document references.
Best Practices
1. Query Optimization
# Less optimal - too generic
result = client.search("AI")
More optimal - specific and contextual
result = client.search(
"practical applications of AI agents in enterprise software development 2026",
searchdepth="advanced"
)
2. Use Domain Filtering
# For academic research
result = client.search(
"transformer attention mechanism improvements",
includedomains=["arxiv.org", "paperswithcode.com", "scholar.google.com"]
)
For technical tutorials
result = client.search(
"deploy FastAPI with Docker",
includedomains=["docs.docker.com", "fastapi.tiangolo.com", "realpython.com"]
)
3. Caching to Reduce API Calls
import hashlib
import json
from pathlib import Path
class CachedTavilyClient:
def init(self, apikey, cachedir="./tavilycache"):
self.client = TavilyClient(apikey=apikey)
self.cachedir = Path(cachedir)
self.cachedir.mkdir(existok=True)
def cachekey(self, query, kwargs):
keydata = json.dumps({"query": query, kwargs}, sortkeys=True)
return hashlib.md5(keydata.encode()).hexdigest()
def search(self, query, cachettl=3600, kwargs):
cachekey = self.cachekey(query, kwargs)
cachefile = self.cachedir / f"{cachekey}.json"
if cachefile.exists():
import time
cachedata = json.loads(cachefile.readtext())
if time.time() - cachedata["timestamp"] < cachettl:
return cachedata["response"]
response = self.client.search(query, kwargs)
import time
cachedata = {"timestamp": time.time(), "response": response}
cachefile.writetext(json.dumps(cachedata))
return response
4. Proper Error Handling
from tavily import TavilyClient
import time
def robustsearch(client, query, maxretries=3, kwargs):
for attempt in range(maxretries):
try:
return client.search(query, kwargs)
except Exception as e:
if "rate limit" in str(e).lower():
waittime = 2 attempt
print(f"Rate limited. Waiting {waittime}s...")
time.sleep(waittime)
elif attempt == maxretries - 1:
raise
else:
print(f"Error: {e}. Retrying...")
time.sleep(1)
5. Batching for Multiple Queries
import asyncio
from tavily import AsyncTavilyClient
async def batchsearch(queries, apikey):
client = AsyncTavilyClient(apikey=apikey)
tasks = [
client.search(query, searchdepth="basic")
for query in queries
]
results = await asyncio.gather(*tasks, returnexceptions=True)
successful = []
for query, result in zip(queries, results):
if isinstance(result, Exception):
print(f"Failed: {query} - {result}")
else:
successful.append({"query": query, "results": result})
return successful
queries = [
"Python async programming best practices",
"FastAPI vs Django REST framework comparison",
"Docker multi-stage build optimization"
]
results = asyncio.run(batchsearch(queries, "tvly-YOURAPIKEY"))
Tavily with CrewAI
Tavily works exceptionally well with multi-agent frameworks like CrewAI:
from crewai import Agent, Task, Crew
from crewaitools import TavilySearchTool
searchtool = TavilySearchTool(apikey="tvly-YOURAPIKEY")
researcher = Agent(
role="Senior Research Analyst",
goal="Find current and accurate information about the given topic",
backstory="You are an experienced research analyst who always searches for data from trusted sources.",
tools=[searchtool],
verbose=True
)
writer = Agent(
role="Technical Writer",
goal="Write technical articles based on research findings",
backstory="You are a technical writer who can transform research data into easily understandable articles.",
verbose=True
)
researchtask = Task(
description="Research about: {topic}. Collect at least 5 different sources.",
expectedoutput="Research report with source URLs",
agent=researcher
)
writingtask = Task(
description="Write an article based on the research results. Include code examples if relevant.",
expectedoutput="Complete article in markdown",
agent=writer
)
crew = Crew(
agents=[researcher, writer],
tasks=[researchtask, writingtask],
verbose=True
)
result = crew.kickoff(inputs={"topic": "AI Agent Frameworks Comparison 2026"})
print(result)
Comparison with Alternatives
| Feature | Tavily | SerpAPI | Google Custom Search | Bing Search API |
|---------|--------|---------|---------------------|-----------------|
| Optimized for AI | Yes | No | No | No |
| Content Extraction | Built-in | No | No | No |
| AI Answer | Yes | No | No | No |
| LangChain Integration | Native | Community | Community | Community |
| Free Tier | 1,000/month | 100/month | 100/day | 1,000/month |
| Search Depth | Basic + Advanced | Single | Single | Single |
| Domain Filtering | Yes | Yes | Yes | Yes |
Conclusion
Tavily is an excellent choice for developers building AI applications that require real-time access to information from the internet. Its key advantages include:
By leveraging Tavily in your RAG pipeline, you can build AI applications that always have access to current information without managing complex web scraping infrastructure. Combine it with frameworks like LangChain or CrewAI to build truly powerful and well-informed AI agents.