> ## 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

> Built-in Tavily search tools for AI agents - web search, content extraction, crawling, and site mapping

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent, tavily

agent = Agent(name="Researcher", tools=[tavily])
agent.start("Search for the latest on agent frameworks")
```

The user describes a research question; the agent calls Tavily search and returns concise findings.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    U[Input] --> A[Agent]
    A --> T[Tool]
    T --> O[Output]

    classDef agent fill:#8B0000,color:#fff
    classDef tool fill:#189AB4,color:#fff

    class A agent
    class U,O tool
    class T tool
```

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant User
    participant Agent
    participant Feature as Tavily Search

    User->>Agent: Request
    Agent->>Feature: Process request
    Feature-->>Agent: Result
    Agent-->>User: Response
```

<Note>
  **Prerequisites**

  * Python 3.10 or higher
  * PraisonAI Agents package installed
  * `tavily-python` package installed
  * `TAVILY_API_KEY` environment variable set
</Note>

Tavily is an AI-powered search API optimized for LLM applications. PraisonAI includes **built-in Tavily tools** for easy integration.

## Quick Start

<Steps>
  <Step title="Install and set key">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    pip install praisonaiagents tavily-python
    export TAVILY_API_KEY=your_tavily_api_key
    ```
  </Step>

  <Step title="Search with agent">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonaiagents import Agent, tavily

    agent = Agent(
        name="SearchAgent",
        instructions="Search the web for accurate, up-to-date information.",
        tools=[tavily],
    )

    agent.start("What are the latest AI trends in 2025?")
    ```
  </Step>
</Steps>

## Installation

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
pip install praisonaiagents tavily-python
```

## Setup

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
export TAVILY_API_KEY=your_tavily_api_key
export OPENAI_API_KEY=your_openai_api_key
```

## Built-in Tavily Tool

PraisonAI provides a built-in `tavily` tool that you can import directly:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent
from praisonaiagents import tavily

agent = Agent(
    name="SearchAgent",
    role="Web Researcher",
    goal="Find information on the web",
    tools=[tavily]
)

result = agent.start("What are the latest AI trends in 2025?")
print(result)
```

## Available Functions

| Function         | Description                            |
| ---------------- | -------------------------------------- |
| `tavily`         | Web search (alias for `tavily_search`) |
| `tavily_search`  | Search with full parameters            |
| `tavily_extract` | Extract content from URLs              |
| `tavily_crawl`   | Crawl websites                         |
| `tavily_map`     | Get site maps                          |

## Basic Usage

### Simple Search

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import tavily

# Simple search
results = tavily("Python programming best practices")
print(results)
```

### Search with Options

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import tavily_search

results = tavily_search(
    query="AI trends 2025",
    max_results=5,
    search_depth="advanced",  # "basic" or "advanced"
    include_answer=True,      # Get LLM-generated answer
    topic="general"           # "general", "news", or "finance"
)

print(results.get("answer"))  # AI-generated answer
for r in results.get("results", []):
    print(f"- {r['title']}: {r['url']}")
```

### Extract Content from URLs

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import tavily_extract

content = tavily_extract(
    urls=["https://praison.ai/docs", "https://example.com"],
    extract_depth="basic"  # "basic" or "advanced"
)

for result in content.get("results", []):
    print(f"URL: {result['url']}")
    print(f"Content: {result['raw_content'][:500]}...")
```

### Crawl Websites

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import tavily_crawl

results = tavily_crawl(
    url="https://praison.ai/docs",
    max_depth=2,
    max_breadth=10,
    limit=20,
    instructions="Find all pages about agents"
)

for page in results.get("results", []):
    print(f"- {page['url']}")
```

### Get Site Map

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import tavily_map

sitemap = tavily_map(
    url="https://praison.ai/docs",
    max_depth=2,
    limit=50
)

for url in sitemap.get("results", []):
    print(url)
```

## With PraisonAI Agent

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent
from praisonaiagents import tavily

agent = Agent(
    name="SearchAgent",
    role="Web Researcher",
    goal="Find and analyze information from the web",
    tools=[tavily]
)

result = agent.start("Research the latest developments in quantum computing")
print(result)
```

## Using TavilyTools Class

For more control, use the `TavilyTools` class directly:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import TavilyTools

# Initialize with custom API key (optional)
tools = TavilyTools(api_key="your_api_key")  # or uses TAVILY_API_KEY env var

# Search
results = tools.search("AI news", max_results=5, include_answer=True)

# Extract
content = tools.extract(["https://example.com"])

# Crawl
pages = tools.crawl("https://praison.ai/docs", max_depth=2)

# Map
sitemap = tools.map("https://praison.ai/docs")
```

## Async Usage

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import asyncio
from praisonaiagents import Agent, Task, AgentTeam
from praisonaiagents import tavily_search_async

agent = Agent(
    name="AsyncSearchAgent",
    role="Search Specialist",
    tools=[tavily_search_async]
)

task = Task(
    description="Search for AI trends",
    agent=agent,
    async_execution=True
)

agents = AgentTeam(agents=[agent], tasks=[task])
result = asyncio.run(agents.astart())
```

## Search Parameters

| Parameter             | Type | Description                     |
| --------------------- | ---- | ------------------------------- |
| `query`               | str  | Search query                    |
| `search_depth`        | str  | "basic" or "advanced"           |
| `topic`               | str  | "general", "news", or "finance" |
| `max_results`         | int  | Max results (1-20)              |
| `include_answer`      | bool | Include LLM-generated answer    |
| `include_raw_content` | bool | Include full page content       |
| `include_images`      | bool | Include images                  |
| `include_domains`     | list | Domains to include              |
| `exclude_domains`     | list | Domains to exclude              |
| `time_range`          | str  | "day", "week", "month", "year"  |

## Key Points

* **Simple function signature**: Tool must accept `query: str` and return `str`
* **Environment variable**: Set `TAVILY_API_KEY` before running
* **Agent decides**: The LLM decides when to use the tool based on the query
* **Works globally**: `--query-rewrite` works with any PraisonAI command

## Best Practices

<AccordionGroup>
  <Accordion title="Use the simple tavily import">
    `from praisonaiagents import tavily` is the simplest integration - use it unless you need specific parameters.
  </Accordion>

  <Accordion title="Set search_depth based on task">
    Use `search_depth='basic'` for quick lookups and `'advanced'` for research needing deeper results.
  </Accordion>

  <Accordion title="Enable include_answer for summaries">
    Set `include_answer=True` to get a Tavily-generated summary alongside raw search results.
  </Accordion>

  <Accordion title="Use topic filter for domain-specific search">
    Set `topic='news'` for current events or `topic='finance'` for financial queries.
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card title="Custom Tools" icon="wrench" href="/docs/tools/custom">
    Build your own agent tools
  </Card>

  <Card title="Tools Overview" icon="toolbox" href="/docs/tools/tools">
    Browse PraisonAI tool documentation
  </Card>
</CardGroup>