> ## Documentation Index
> Fetch the complete documentation index at: https://agno-v2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Tavily

> Search and extract web content with TavilyTools, backed by the Tavily search and extract APIs.

**TavilyTools** enable an Agent to search the web using the Tavily API.

## Prerequisites

The following example requires the `tavily-python` and `openai` libraries and an API key from [Tavily](https://tavily.com/).

```shell theme={null}
uv pip install -U tavily-python openai
```

```shell theme={null}
export TAVILY_API_KEY=***
# optional: use a self-hosted Tavily-compatible API endpoint
export TAVILY_API_BASE_URL=https://custom.tavily.com
```

## Example

The following agent will run a search on Tavily for "language models" and print the response.

```python cookbook/91_tools/tavily_tools.py theme={null}
from agno.agent import Agent
from agno.tools.tavily import TavilyTools

agent = Agent(tools=[TavilyTools()], markdown=True)
agent.print_response("Search tavily for 'language models'")
```

## Toolkit Params

| Parameter | Type | Default | Description |
| - | - | - | - |
| `api_key` | `Optional[str]` | `None` | Tavily API key. If not provided, will use TAVILY\_API\_KEY environment variable. |
| `api_base_url` | `Optional[str]` | `None` | Tavily API base URL. If not provided, uses `TAVILY_API_BASE_URL` when set; if both are unset or `None`, falls back to the default base URL from the `tavily-python` client (for example, [https://api.tavily.com](https://api.tavily.com)). |
| `enable_search` | `bool` | `True` | Enable search functionality. |
| `enable_search_context` | `bool` | `False` | Enable search context functionality using Tavily's context API. |
| `enable_extract` | `bool` | `False` | Enable URL content extraction functionality. |
| `all` | `bool` | `False` | Enable all available functions in the toolkit. |
| `max_tokens` | `int` | `6000` | Maximum number of tokens to use in search results. |
| `include_answer` | `bool` | `True` | Whether to include an AI-generated answer summary in the response. |
| `search_depth` | `Literal['basic', 'advanced', 'fast', 'ultra-fast']` | `'advanced'` | Depth of search - 'basic' (1 credit), 'advanced' (2 credits), 'fast', or 'ultra-fast'. |
| `extract_depth` | `Literal['basic', 'advanced']` | `'basic'` | Extraction depth - 'basic' (1 credit/5 URLs) or 'advanced' (2 credits/5 URLs). |
| `include_images` | `bool` | `False` | Include images in extracted content. |
| `include_favicon` | `bool` | `False` | Include favicon in extracted content. |
| `extract_timeout` | `Optional[int]` | `None` | Timeout in seconds for extraction requests. |
| `extract_format` | `Literal['markdown', 'text']` | `'markdown'` | Output format for extracted content. |
| `format` | `Literal['json', 'markdown']` | `'markdown'` | Output format - 'json' for raw data or 'markdown' for formatted text. |
| `topic` | `Optional[Literal['general', 'news', 'finance']]` | `None` | Search category - general, news, or finance. |
| `time_range` | `Optional[Literal['day', 'week', 'month', 'year', 'd', 'w', 'm', 'y']]` | `None` | Time window for results - day, week, month, year (or d/w/m/y). |
| `start_date` | `Optional[str]` | `None` | Only include results published after this date (YYYY-MM-DD). |
| `end_date` | `Optional[str]` | `None` | Only include results published before this date (YYYY-MM-DD). |
| `days` | `Optional[int]` | `None` | Number of days back to include results. Applies to the news topic only. |
| `include_domains` | `Optional[List[str]]` | `None` | Restrict results to these domains. |
| `exclude_domains` | `Optional[List[str]]` | `None` | Exclude these domains from results. |
| `country` | `Optional[str]` | `None` | Boost results from this country (e.g., 'united states'). |
| `auto_parameters` | `bool` | `False` | Let Tavily auto-tune search parameters. Explicitly set values (including the always-sent `search_depth` and `include_answer`) take precedence. |
| `chunks_per_source` | `Optional[int]` | `None` | Number of content chunks per source (1-3). Advanced search only. |
| `search_params` | `Optional[Dict[str, Any]]` | `None` | Additional parameters merged into web search requests. Overrides named parameters on key collision. |

## Toolkit Functions

| Function | Description |
| - | - |
| `web_search_using_tavily` | Search the web for a given query using Tavily API. Parameters include `query` (str) for the search query and `max_results` (int, default=5) for maximum number of results. Returns JSON string of results with titles, URLs, content and relevance scores in specified format. |
| `web_search_with_tavily` | Alternative search function that uses Tavily's search context API. Parameters include `query` (str) for the search query. Returns contextualized search results. Only available when `enable_search_context` is True. |
| `extract_url_content` | Extract content from one or more URLs using Tavily's Extract API. Parameters include `urls` (str), a single URL or comma-separated URLs. Returns extracted content in the configured `extract_format` (markdown or text). Only available when `enable_extract` or `all` is True. |

## Developer Resources

* [Tools](https://github.com/agno-agi/agno/blob/main/libs/agno/agno/tools/tavily.py)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.