Add DuckDuckGoSearch tool (#997)

Author: Kludex

docs/common_tools.md

@@ -0,0 +1,67 @@
+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).
+
+```py {title="main.py" test="skip"}
+from pydantic_ai import Agent
+from pydantic_ai.toolsets.duckduckgo import duckduckgo_search_tool
+
+agent = Agent(
+    'openai:o3-mini',
+    tools=[duckduckgo_search_tool()],
+    system_prompt='Search DuckDuckGo for the given query and return the results.',
+)
+
+result = agent.run_sync(
+    'Can you list the top five highest-grossing animated films of 2025?'
+)
+print(result.data)
+"""
+I looked into several sources on animated box‐office performance in 2025, and while detailed
+rankings can shift as more money is tallied, multiple independent reports have already
+highlighted a couple of record‐breaking shows. For example:
+
+• Ne Zha 2 – News outlets (Variety, Wikipedia's "List of animated feature films of 2025", and others)
+    have reported that this Chinese title not only became the highest‑grossing animated film of 2025
+    but also broke records as the highest‑grossing non‑English animated film ever. One article noted
+    its run exceeded US$1.7 billion.
+• Inside Out 2 – According to data shared on Statista and in industry news, this Pixar sequel has been
+    on pace to set new records (with some sources even noting it as the highest‑grossing animated film
+    ever, as of January 2025).
+
+Beyond those two, some entertainment trade sites (for example, a Just Jared article titled
+"Top 10 Highest-Earning Animated Films at the Box Office Revealed") have begun listing a broader
+top‑10. Although full consolidated figures can sometimes differ by source and are updated daily during
+a box‑office run, many of the industry trackers have begun to single out five films as the biggest
+earners so far in 2025.
+
+Unfortunately, although multiple articles discuss the "top animated films" of 2025, there isn't yet a
+single, universally accepted list with final numbers that names the complete top five. (Box‑office
+rankings, especially mid‑year, can be fluid as films continue to add to their totals.)
+
+Based on what several sources note so far, the two undisputed leaders are:
+1. Ne Zha 2
+2. Inside Out 2
+
+The remaining top spots (3–5) are reported by some outlets in their "Top‑10 Animated Films"
+lists for 2025 but the titles and order can vary depending on the source and the exact cut‑off
+date of the data. For the most up‑to‑date and detailed ranking (including the 3rd, 4th, and 5th
+highest‑grossing films), I recommend checking resources like:
+• Wikipedia's "List of animated feature films of 2025" page
+• Box‑office tracking sites (such as Box Office Mojo or The Numbers)
+• Trade articles like the one on Just Jared
+
+To summarize with what is clear from the current reporting:
+1. Ne Zha 2
+2. Inside Out 2
+3–5. Other animated films (yet to be definitively finalized across all reporting outlets)
+
+If you're looking for a final, consensus list of the top five, it may be best to wait until
+the 2025 year‑end box‑office tallies are in or to consult a regularly updated entertainment industry source.
+
+Would you like help finding a current source or additional details on where to look for the complete updated list?
+"""
+```

mkdocs.yml

@@ -20,6 +20,7 @@ nav:
       - models.md
       - dependencies.md
       - tools.md
+      - common_tools.md
       - results.md
       - message-history.md
       - testing-evals.md

pydantic_ai_slim/pydantic_ai/common_tools/__init__.py

@@ -0,0 +1,63 @@
+from dataclasses import dataclass
+from typing import TypedDict
+
+import anyio
+import anyio.to_thread
+from pydantic import TypeAdapter
+
+from pydantic_ai.tools import Tool
+
+try:
+    from duckduckgo_search import DDGS
+except ImportError as _import_error:
+    raise ImportError(
+        'Please install `duckduckgo-search` to use the DuckDuckGo search tool, '
+        "you can use the `duckduckgo` optional group — `pip install 'pydantic-ai-slim[duckduckgo]'`"
+    ) from _import_error
+
+__all__ = ('duckduckgo_search_tool',)
+
+
+class DuckDuckGoResult(TypedDict):
+    """A DuckDuckGo search result."""
+
+    title: str
+    """The title of the search result."""
+    href: str
+    """The URL of the search result."""
+    body: str
+    """The body of the search result."""
+
+
+duckduckgo_ta = TypeAdapter(list[DuckDuckGoResult])
+
+
+@dataclass
+class DuckDuckGoSearchTool:
+    """The DuckDuckGo search tool."""
+
+    client: DDGS
+    """The DuckDuckGo search client."""
+
+    async def __call__(self, query: str) -> list[DuckDuckGoResult]:
+        """Searches DuckDuckGo for the given query and returns the results.
+
+        Args:
+            query: The query to search for.
+
+        Returns:
+            The search results.
+        """
+        results = await anyio.to_thread.run_sync(self.client.text, query)
+        if len(results) == 0:
+            raise RuntimeError('No search results found.')
+        return duckduckgo_ta.validate_python(results)
+
+
+def duckduckgo_search_tool(duckduckgo_client: DDGS | None = None):
+    """Creates a DuckDuckGo search tool."""
+    return Tool(
+        DuckDuckGoSearchTool(client=duckduckgo_client or DDGS()).__call__,
+        name='duckduckgo_search',
+        description='Searches DuckDuckGo for the given query and returns the results.',
+    )

pydantic_ai_slim/pydantic_ai/common_tools/duckduckgo.py

@@ -44,12 +44,15 @@ dependencies = [
 [project.optional-dependencies]
 # WARNING if you add optional groups, please update docs/install.md
 logfire = ["logfire>=2.3"]
+# Models
 openai = ["openai>=1.61.0"]
 cohere = ["cohere>=5.13.11"]
 vertexai = ["google-auth>=2.36.0", "requests>=2.32.3"]
 anthropic = ["anthropic>=0.40.0"]
 groq = ["groq>=0.12.0"]
 mistral = ["mistralai>=1.2.5"]
+# Tools
+duckduckgo = ["duckduckgo-search>=7.0.0"]
 
 [dependency-groups]
 dev = [

pydantic_ai_slim/pyproject.toml

@@ -6,9 +6,7 @@ build-backend = "hatchling.build"
 name = "pydantic-ai"
 version = "0.0.27"
 description = "Agent Framework / shim to use Pydantic with LLMs"
-authors = [
-    { name = "Samuel Colvin", email = "[email protected]" },
-]
+authors = [{ name = "Samuel Colvin", email = "[email protected]" }]
 license = "MIT"
 readme = "README.md"
 classifiers = [
@@ -33,7 +31,9 @@ classifiers = [
 ]
 requires-python = ">=3.9"
 
-dependencies = ["pydantic-ai-slim[openai,vertexai,groq,anthropic,mistral,cohere]==0.0.27"]
+dependencies = [
+    "pydantic-ai-slim[openai,vertexai,groq,anthropic,mistral,cohere]==0.0.27",
+]
 
 [project.urls]
 Homepage = "https://ai.pydantic.dev"
@@ -55,11 +55,7 @@ members = ["pydantic_ai_slim", "pydantic_graph", "examples"]
 
 [dependency-groups]
 # dev dependencies are defined in `pydantic-ai-slim/pyproject.toml` to allow for minimal testing
-lint = [
-    "mypy>=1.11.2",
-    "pyright>=1.1.388,<1.1.390",
-    "ruff>=0.6.9",
-]
+lint = ["mypy>=1.11.2", "pyright>=1.1.388,<1.1.390", "ruff>=0.6.9"]
 docs = [
     "black>=24.10.0",
     "bs4>=0.0.2",
@@ -69,10 +65,7 @@ docs = [
     "mkdocs-material[imaging]>=9.5.45",
     "mkdocstrings-python>=1.12.2",
 ]
-docs-upload = [
-    "algoliasearch>=4.12.0",
-    "pydantic>=2.10.1",
-]
+docs-upload = ["algoliasearch>=4.12.0", "pydantic>=2.10.1"]
 
 [tool.hatch.build.targets.wheel]
 only-include = ["/README.md"]
@@ -92,14 +85,7 @@ include = [
 ]
 
 [tool.ruff.lint]
-extend-select = [
-    "Q",
-    "RUF100",
-    "C90",
-    "UP",
-    "I",
-    "D",
-]
+extend-select = ["Q", "RUF100", "C90", "UP", "I", "D"]
 flake8-quotes = { inline-quotes = "single", multiline-quotes = "double" }
 isort = { combine-as-imports = true, known-first-party = ["pydantic_ai"] }
 mccabe = { max-complexity = 15 }
@@ -133,9 +119,7 @@ include = ["pydantic_ai_slim", "pydantic_graph", "tests", "examples"]
 venvPath = ".venv"
 # see https://github.com/microsoft/pyright/issues/7771 - we don't want to error on decorated functions in tests
 # which are not otherwise used
-executionEnvironments = [
-  { root = "tests", reportUnusedFunction = false },
-]
+executionEnvironments = [{ root = "tests", reportUnusedFunction = false }]
 exclude = ["examples/pydantic_ai_examples/weather_agent_gradio.py"]
 
 [tool.mypy]
@@ -145,14 +129,16 @@ strict = true
 [tool.pytest.ini_options]
 testpaths = "tests"
 xfail_strict = true
-filterwarnings = [
-    "error",
-]
+filterwarnings = ["error"]
 
 # https://coverage.readthedocs.io/en/latest/config.html#run
 [tool.coverage.run]
 # required to avoid warnings about files created by create_module fixture
-include = ["pydantic_ai_slim/**/*.py", "pydantic_graph/**/*.py","tests/**/*.py"]
+include = [
+    "pydantic_ai_slim/**/*.py",
+    "pydantic_graph/**/*.py",
+    "tests/**/*.py",
+]
 omit = ["tests/test_live.py", "tests/example_modules/*.py"]
 branch = true
 
@@ -180,8 +166,8 @@ exclude_lines = [
 ignore_no_config = true
 
 [tool.inline-snapshot.shortcuts]
-snap-fix=["create", "fix"]
-snap=["create"]
+snap-fix = ["create", "fix"]
+snap = ["create"]
 
 [tool.codespell]
 # Ref: https://github.com/codespell-project/codespell#using-a-config-file