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.

uv pip install -U tavily-python openai

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.

cookbook/91_tools/tavily_tools.py

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).
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