Add TavilySearchTool (#1001)

Author: Kludex

docs/api/common_tools.md

@@ -0,0 +1,5 @@
+# `pydantic_ai.common_tools`
+
+::: pydantic_ai.common_tools.duckduckgo
+
+::: pydantic_ai.common_tools.tavily

docs/common_tools.md

@@ -1,10 +1,25 @@
+# Common Tools
+
 PydanticAI ships with native tools that can be used to enhance your agent's capabilities.
 
 ## DuckDuckGo Search Tool
 
 The DuckDuckGo search tool allows you to search the web for information. It is built on top of the
 [DuckDuckGo API](https://github.com/deedy5/duckduckgo_search).
 
+### Installation
+
+To use [`duckduckgo_search_tool`][pydantic_ai.common_tools.duckduckgo.duckduckgo_search_tool], you need to install
+[`pydantic-ai-slim`](install.md#slim-install) with the `duckduckgo` optional group:
+
+```bash
+pip/uv-add 'pydantic-ai-slim[duckduckgo]'
+```
+
+### Usage
+
+Here's an example of how you can use the DuckDuckGo search tool with an agent:
+
 ```py {title="main.py" test="skip"}
 from pydantic_ai import Agent
 from pydantic_ai.toolsets.duckduckgo import duckduckgo_search_tool
@@ -65,3 +80,62 @@ the 2025 year‑end box‑office tallies are in or to consult a regularly update
 Would you like help finding a current source or additional details on where to look for the complete updated list?
 """
 ```
+
+## Tavily Search Tool
+
+!!! info
+    Tavily is a paid service, but they have free credits to explore their product.
+
+    You need to [sign up for an account](https://app.tavily.com/home) and get an API key to use the Tavily search tool.
+
+The Tavily search tool allows you to search the web for information. It is built on top of the [Tavily API](https://tavily.com/).
+
+### Installation
+
+To use [`tavily_search_tool`][pydantic_ai.common_tools.tavily.tavily_search_tool], you need to install
+[`pydantic-ai-slim`](install.md#slim-install) with the `tavily` optional group:
+
+```bash
+pip/uv-add 'pydantic-ai-slim[tavily]'
+```
+
+### Usage
+
+Here's an example of how you can use the Tavily search tool with an agent:
+
+```py {title="main.py" test="skip"}
+import os
+
+from pydantic_ai.agent import Agent
+from pydantic_ai.common_tools.tavily import tavily_search_tool
+
+api_key = os.getenv('TAVILY_API_KEY')
+assert api_key is not None
+
+
+agent = Agent(
+    'openai:o3-mini',
+    tools=[tavily_search_tool(api_key)],
+    system_prompt='Search Tavily for the given query and return the results.',
+)
+
+result = agent.run_sync('Tell me the top news in the GenAI world, give me links.')
+print(result.data)
+"""
+Here are some of the top recent news articles related to GenAI:
+
+1. How CLEAR users can improve risk analysis with GenAI – Thomson Reuters
+   Read more: https://legal.thomsonreuters.com/blog/how-clear-users-can-improve-risk-analysis-with-genai/
+   (This article discusses how CLEAR's new GenAI-powered tool streamlines risk analysis by quickly summarizing key information from various public data sources.)
+
+2. TELUS Digital Survey Reveals Enterprise Employees Are Entering Sensitive Data Into AI Assistants More Than You Think – FT.com
+   Read more: https://markets.ft.com/data/announce/detail?dockey=600-202502260645BIZWIRE_USPRX____20250226_BW490609-1
+   (This news piece highlights findings from a TELUS Digital survey showing that many enterprise employees use public GenAI tools and sometimes even enter sensitive data.)
+
+3. The Essential Guide to Generative AI – Virtualization Review
+   Read more: https://virtualizationreview.com/Whitepapers/2025/02/SNOWFLAKE-The-Essential-Guide-to-Generative-AI.aspx
+   (This guide provides insights into how GenAI is revolutionizing enterprise strategies and productivity, with input from industry leaders.)
+
+Feel free to click on the links to dive deeper into each story!
+"""
+```

docs/install.md

@@ -53,6 +53,8 @@ pip/uv-add 'pydantic-ai-slim[openai]'
 * `groq` — installs `groq` [PyPI ↗](https://pypi.org/project/groq){:target="_blank"}
 * `mistral` — installs `mistralai` [PyPI ↗](https://pypi.org/project/mistralai){:target="_blank"}
 * `cohere` - installs `cohere` [PyPI ↗](https://pypi.org/project/cohere){:target="_blank"}
+* `duckduckgo` - installs `duckduckgo-search` [PyPI ↗](https://pypi.org/project/duckduckgo-search){:target="_blank"}
+* `tavily` - installs `tavily-python` [PyPI ↗](https://pypi.org/project/tavily-python){:target="_blank"}
 
 See the [models](models.md) documentation for information on which optional dependencies are required for each model.
 

mkdocs.yml

@@ -43,6 +43,7 @@ nav:
   - API Reference:
       - api/agent.md
       - api/tools.md
+      - api/common_tools.md
       - api/result.md
       - api/messages.md
       - api/exceptions.md

pydantic_ai_slim/pydantic_ai/common_tools/tavily.py

@@ -0,0 +1,82 @@
+from dataclasses import dataclass
+from typing import Literal, TypedDict
+
+from pydantic import TypeAdapter
+
+from pydantic_ai.tools import Tool
+
+try:
+    from tavily import AsyncTavilyClient
+except ImportError as _import_error:
+    raise ImportError(
+        'Please install `tavily-python` to use the Tavily search tool, '
+        "you can use the `tavily` optional group — `pip install 'pydantic-ai-slim[tavily]'`"
+    ) from _import_error
+
+__all__ = ('tavily_search_tool',)
+
+
+class TavilySearchResult(TypedDict):
+    """A Tavily search result.
+
+    See [Tavily Search Endpoint documentation](https://docs.tavily.com/api-reference/endpoint/search)
+    for more information.
+    """
+
+    title: str
+    """The title of the search result."""
+    url: str
+    """The URL of the search result.."""
+    content: str
+    """A short description of the search result."""
+    score: float
+    """The relevance score of the search result."""
+
+
+tavily_search_ta = TypeAdapter(list[TavilySearchResult])
+
+
+@dataclass
+class TavilySearchTool:
+    """The Tavily search tool."""
+
+    client: AsyncTavilyClient
+    """The Tavily search client."""
+
+    async def __call__(
+        self,
+        query: str,
+        search_deep: Literal['basic', 'advanced'] = 'basic',
+        topic: Literal['general', 'news'] = 'general',
+        time_range: Literal['day', 'week', 'month', 'year', 'd', 'w', 'm', 'y'] | None = None,
+    ):
+        """Searches Tavily for the given query and returns the results.
+
+        Args:
+            query: The search query to execute with Tavily.
+            search_deep: The depth of the search.
+            topic: The category of the search.
+            time_range: The time range back from the current date to filter results.
+
+        Returns:
+            The search results.
+        """
+        results = await self.client.search(query, search_depth=search_deep, topic=topic, time_range=time_range)  # type: ignore[reportUnknownMemberType]
+        if not results['results']:
+            raise RuntimeError('No search results found.')
+        return tavily_search_ta.validate_python(results['results'])
+
+
+def tavily_search_tool(api_key: str):
+    """Creates a Tavily search tool.
+
+    Args:
+        api_key: The Tavily API key.
+
+            You can get one by signing up at [https://app.tavily.com/home](https://app.tavily.com/home).
+    """
+    return Tool(
+        TavilySearchTool(client=AsyncTavilyClient(api_key)).__call__,
+        name='tavily_search',
+        description='Searches Tavily for the given query and returns the results.',
+    )

pydantic_ai_slim/pyproject.toml

@@ -53,6 +53,7 @@ groq = ["groq>=0.12.0"]
 mistral = ["mistralai>=1.2.5"]
 # Tools
 duckduckgo = ["duckduckgo-search>=7.0.0"]
+tavily = ["tavily-python>=0.5.0"]
 
 [dependency-groups]
 dev = [