What is TavilySearchResults?
TavilySearchResults is a LangChain tool that wraps the Tavily Search API, giving agents the ability to search the web and retrieve relevant, AI-optimized results. Unlike raw web scraping or the SerpAPI wrapper, Tavily is designed specifically for LLM contexts—its results are cleaned, snippet-focused, and ranked for relevance to the query rather than SEO.
Each result is a dict with url, content (a clean text snippet), score (Tavily's relevance confidence), and optionally raw_content (the full page text). The max_results parameter controls how many top results to return. For most agent tasks, max_results=3–5 is sufficient; higher values increase API latency and token count when results are injected into the model's context.
TavilySearchResults requires the TAVILY_API_KEY environment variable—obtain one from tavily.com. The free tier provides 1000 searches per month. For production agent deployments, note that Tavily results are non-deterministic (the web changes) and each search adds 500ms–2s of latency. Cache results with a simple dict or Redis when the same query is expected multiple times in one agent session.
When to Use
Your agent needs to search the web for real-time info. Use TavilySearchResults for web-aware agents.
Use Cases
- • Web search in agents
- • Real-time information
- • Fact-checking
- • News gathering
- • Research assistance
- • Current data
Key Features
- ✓ Real-time web search
- ✓ Relevance ranking
- ✓ Links included
- ✓ Fast results
- ✓ Simple integration
- ✓ Agent-ready
When NOT to Use
For offline systems. When search terms are sensitive.
Notes
TAVILY_API_KEY is required
Set TAVILY_API_KEY in your environment or pass api_key="..." to the constructor. Without it, every tool call raises a TavilyError at runtime, not at initialization. Add a startup check: assert os.getenv("TAVILY_API_KEY"), "TAVILY_API_KEY not set".
Result format: list of dicts, not strings
TavilySearchResults.invoke("query") returns list[dict] with keys url, content, score. If your agent prompt expects a plain string, stringify it: " ".join(r["content"] for r in results). The structured format is intentional for chaining with post-processors.
Async support via ainvoke
TavilySearchResults supports async invocation via await tool.ainvoke("query"). In async agent loops (LangGraph, async chains), always use the async path to avoid blocking the event loop during the HTTP request to Tavily's API.
Latency budget: 500ms-2s per search
Tavily adds 0.5-2 seconds of network latency per call. For time-sensitive agents, limit max_results=3 and cache repeated queries. Consider adding a tool description that discourages the model from calling search for well-known facts.
include_raw_content for full-page extraction
Pass include_raw_content=True to get the full page body in the raw_content key. Useful when the snippet is too short for answering the question, but significantly increases response size and token usage. Use selectively, not by default.
Import
from langchain_community.tools.tavily_search import TavilySearchResultsKey Parameters
| Parameter | Type | Default | Purpose |
|---|---|---|---|
| max_results | int | 5 | Maximum results to return |
Code Examples
Search Tool
from langchain_community.tools.tavily_search import TavilySearchResults
tool = TavilySearchResults(max_results=5)
tools = [tool]
# Use with agent
agent = create_agent(model, tools)Direct Invocation and Result Structure
tool = TavilySearchResults(max_results=3)
results = tool.invoke("LangChain v0.3 release notes")
for r in results:
print(r["url"])
print(r["content"][:200])
print(r["score"])Async Invocation
import asyncio
from langchain_community.tools.tavily_search import TavilySearchResults
tool = TavilySearchResults(max_results=3)
async def search(query: str):
results = await tool.ainvoke(query)
return results
asyncio.run(search("latest AI news"))Common Mistakes
❌ Forget to set TAVILY_API_KEY
✅ export TAVILY_API_KEY='...'
Related LangChain References
Browse the full LangChain API reference index to explore more classes, methods, and decorators, or start with the LangChain introduction tutorial for end-to-end context on building with TavilySearchResults and the wider framework.
TavilySearchResults FAQ
What is TavilySearchResults in LangChain?
Web search tool for agents. TavilySearchResults is a LangChain tool that wraps the Tavily Search API, giving agents the ability to search the web and retrieve relevant, AI-optimized results. Unlike raw web scraping or the SerpAPI wrapper, Tavily is designed specifically for LLM contexts—its results are cleaned, snippet-focused, and ranked for relevance to the query rather than SEO. Each result is a dict with url, content (a clean text snippet), score (Tavily's relevance confidence), and optionally raw_…
Which package provides TavilySearchResults?
DevShelfHub documents TavilySearchResults from the langchain-community package. Pin your installed LangChain version and match imports to the snippet on this page.
When should I use TavilySearchResults?
Your agent needs to search the web for real-time info. Use TavilySearchResults for web-aware agents.
When should I avoid using TavilySearchResults?
For offline systems. When search terms are sensitive.
How do I import TavilySearchResults in Python?
from langchain_community.tools.tavily_search import TavilySearchResults
Where can I explore more LangChain API reference pages?
Open the LangChain API reference index on DevShelfHub to browse classes, methods, and decorators, each with runnable examples, parameters, common mistakes, and cross-links.