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 agno tavily-python openaiexport TAVILY_API_KEY=***
# optional: use a self-hosted Tavily-compatible API endpoint
# export TAVILY_API_BASE_URL=https://your-tavily-compatible-endpointExample
The following agent will run a search on Tavily for "language models" and print the response.
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 | Select the context helper instead of ordinary search; requires enable_search=True or all=True. |
enable_extract | bool | False | Enable URL content extraction functionality. |
all | bool | False | Enable extraction and one search implementation, selected by enable_search_context. |
max_tokens | int | 6000 | Ordinary search: serialized-character budget for adding results, not a hard output bound; the answer is retained. Context search: forwarded to the SDK as max_tokens. |
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 | Request images from Tavily; the formatted toolkit output omits the image fields. |
include_favicon | bool | False | Request favicons from Tavily; the formatted toolkit output omits favicon fields. |
extract_timeout | Optional[int] | None | Timeout in seconds for extraction requests. |
extract_format | Literal['markdown', 'text'] | 'markdown' | Wrapper heading style; not forwarded as the provider extraction format. Text output can still contain Markdown. |
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. |
The context helper forwards only query, search_depth, and max_tokens. Domain, date, topic, and other search options in this table, including search_params, apply to ordinary search.
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 selected result fields as JSON or Markdown according to 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. Selected when enable_search_context=True and search is enabled. |
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. |