> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Tavily Search
> AI-powered web search using Tavily API
Tavily is an AI-powered search engine that gives agents high-quality results with built-in answer synthesis.
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
subgraph "Tavily"
User[User] --> Agent[Agent]
Agent --> Tool[TavilyTool]
Tool --> API[Tavily API]
API --> Result[Results]
end
classDef input fill:#8B0000,stroke:#7C90A0,color:#fff
classDef process fill:#189AB4,stroke:#7C90A0,color:#fff
classDef output fill:#10B981,stroke:#7C90A0,color:#fff
class User,Agent input
class Tool,API process
class Result output
```
## Overview
Tavily is an AI-powered search engine optimized for LLMs and AI agents. It provides high-quality, relevant search results with built-in answer synthesis.
## Installation
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
pip install "praisonai[tools]"
```
## Environment Variables
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
export TAVILY_API_KEY="${TAVILY_API_KEY:?Set TAVILY_API_KEY in your shell}"
```
Get your API key from [Tavily](https://tavily.com/).
## How It Works
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
participant User
participant Agent
participant Tavily as TavilyTool
participant API as Tavily API
User->>Agent: "Search for X"
Agent->>Tavily: search(query)
Tavily->>API: HTTPS request
API-->>Tavily: results + answer
Tavily-->>Agent: parsed result
Agent-->>User: final answer
```
## Quick Start
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai_tools import TavilyTool
# Initialize
tavily = TavilyTool()
# Search
results = tavily.search("What is quantum computing?")
print(results)
```
Use the same tool with an agent — see **Usage with Agent** below, or pass env vars and options from the sections above.
## Usage with Agent
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent
from praisonai_tools import TavilyTool
agent = Agent(
name="Researcher",
instructions="You are a research assistant. Use Tavily to search for information.",
tools=[TavilyTool()]
)
response = agent.chat("Search for the latest AI news")
print(response)
```
## Available Methods
### search(query, max\_results=5)
Search the web with AI-powered results.
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai_tools import TavilyTool
tavily = TavilyTool()
results = tavily.search("Python best practices", max_results=3)
# Returns:
# {
# "query": "Python best practices",
# "answer": "AI-generated summary...",
# "results": [
# {"title": "...", "url": "...", "content": "...", "score": 0.95}
# ]
# }
```
### search\_context(query)
Get search context optimized for RAG applications.
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
context = tavily.search_context("machine learning fundamentals")
# Returns a string with relevant context for LLM consumption
```
### extract(urls)
Extract content from specific URLs.
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
content = tavily.extract("https://example.com,https://another.com")
# Returns list of extracted content from each URL
```
## Configuration Options
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
tavily = TavilyTool(
api_key="your_key", # Optional: defaults to TAVILY_API_KEY env var
search_depth="advanced", # "basic" or "advanced"
include_answer=True, # Include AI-generated answer
max_tokens=6000 # Max tokens for context
)
```
## Function-Based Usage
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai_tools import tavily_search
# Quick search without instantiating class
results = tavily_search("latest tech news", max_results=5)
```
## CLI Usage
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Set API key
export TAVILY_API_KEY=your_key
# Use with praisonai
praisonai --tools TavilyTool "Search for AI trends 2025"
```
## Error Handling
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai_tools import TavilyTool
tavily = TavilyTool()
results = tavily.search("my query")
if "error" in results:
print(f"Error: {results['error']}")
else:
print(f"Found {len(results['results'])} results")
```
## Common Errors
| Error | Cause | Solution |
| ------------------------------- | ------------------ | ----------------------------------------- |
| `TAVILY_API_KEY not configured` | Missing API key | Set `TAVILY_API_KEY` environment variable |
| `tavily-python not installed` | Missing dependency | Run `pip install tavily-python` |
| `Invalid API key` | Wrong API key | Verify your API key at tavily.com |
## Best Practices
`TavilyTool()` defaults to the `TAVILY_API_KEY` env var. Set it in your shell or `.env` rather than passing `api_key=` inline.
`search_context(query)` returns text optimised for LLM consumption. Prefer it over raw `search` when feeding results straight into the agent.
`search_depth="advanced"` returns richer results at higher latency. Use `"basic"` for quick lookups to keep the agent responsive.
## Related Tools
Neural search engine
Privacy-focused search
Google search API