Skip to content

Building AI agents, atomically

feat(tools): add TavilySearchTool with max_results fix (fix #132/#219)

ueveu97d9940e036b
diff --git a/atomic-forge/atomic_tools/tavily_search/pyproject.toml b/atomic-forge/atomic_tools/tavily_search/pyproject.toml
new file mode 100644
index 0000000..379a599
--- /dev/null
+++ b/atomic-forge/atomic_tools/tavily_search/pyproject.toml
@@ -0,0 +1,16 @@
+[project]
+name = "atomic-tools-tavily-search"
+version = "0.1.0"
+description = "Tavily search tool for atomic-agents"
+requires-python = ">=3.10"
+dependencies = ["aiohttp", "pydantic"]
+
+[project.optional-dependencies]
+dev = ["pytest", "pytest-asyncio"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
diff --git a/atomic-forge/atomic_tools/tavily_search/requirements.txt b/atomic-forge/atomic_tools/tavily_search/requirements.txt
new file mode 100644
index 0000000..74408d9
--- /dev/null
+++ b/atomic-forge/atomic_tools/tavily_search/requirements.txt
@@ -0,0 +1,2 @@
+aiohttp>=3.9.0
+pydantic>=2.0.0
diff --git a/atomic-forge/atomic_tools/tavily_search/tests/test_tavily_search.py b/atomic-forge/atomic_tools/tavily_search/tests/test_tavily_search.py
new file mode 100644
index 0000000..3e0f3eb
--- /dev/null
+++ b/atomic-forge/atomic_tools/tavily_search/tests/test_tavily_search.py
@@ -0,0 +1,117 @@
+from unittest.mock import AsyncMock, MagicMock, patch
+import pytest
+from tavily_search import TavilySearchTool, TavilySearchToolConfig, TavilySearchToolInputSchema
+
+
+def mock_config():
+ return TavilySearchToolConfig(api_key="test_api_key", max_results=5)
+
+
+def tool(mock_config):
+ return TavilySearchTool(config=mock_config)
+
+
+class TestTavilySearchTool:
+ @pytest.mark.asyncio
+ async def test_fetch_search_results_respects_max_results_override(self, tool):
+ """Regression test: max_results override must propagate to the API call, not be ignored."""
+ mock_session = AsyncMock()
+ mock_response = AsyncMock()
+ mock_response.status = 200
+ mock_response.json = AsyncMock(
+ return_value={
+ "results": [
+ {"title": f"Result {i}", "url": f"http://example.com/{i}", "content": "...", "score": 1.0 - i * 0.1}
+ for i in range(5)
+ ],
+ "answer": "test answer",
+ }
+ )
+ mock_response.reason = "OK"
+ mock_session.post = AsyncMock(return_value=mock_response)
+ mock_session.__aenter__ = AsyncMock(return_value=mock_session)
+ mock_session.__aexit__ = AsyncMock(return_value=None)
+
+ result = await tool._fetch_search_results(mock_session, "test query", max_results=2)
+
+ # The key assertion: the API must have been called with max_results=2, not self.max_results=5
+ call_args = mock_session.post.call_args
+ json_data = call_args.kwargs["json"]
+ assert json_data["max_results"] == 2, "max_results override was ignored in API call"
+
+ @pytest.mark.asyncio
+ async def test_run_async_respects_max_results_override(self, tool):
+ """Runtime max_results override must reach the API and limit result count."""
+ mock_session = AsyncMock()
+
+ async def mock_post(*args, **kwargs):
+ max_override = kwargs["json"]["max_results"]
+ return AsyncMock(
+ status=200,
+ reason="OK",
+ json=AsyncMock(
+ return_value={
+ "results": [
+ {"title": f"Result {i}", "url": f"http://example.com/{i}", "content": "...", "score": 1.0}
+ for i in range(max_override + 3) # Return MORE than requested
+ ],
+ "answer": "test answer",
+ }
+ ),
+ )
+
+ mock_session.post = mock_post
+ mock_session.__aenter__ = AsyncMock(return_value=mock_session)
+ mock_session.__aexit__ = AsyncMock(return_value=None)
+
+ params = TavilySearchToolInputSchema(queries=["test query"])
+ output = await tool.run_async(params, max_results=2)
+
+ # Should have exactly 2 results since we requested 2, even though API returned 5
+ assert len(output.results) == 2
+ for call in mock_session.post.call_args_list:
+ assert call.kwargs["json"]["max_results"] == 2
+
+ @pytest.mark.asyncio
+ async def test_run_async_uses_default_when_no_override(self, tool):
+ """When no override is passed, self.max_results should be used."""
+ mock_session = AsyncMock()
+
+ async def mock_post(*args, **kwargs):
+ return AsyncMock(
+ status=200,
+ reason="OK",
+ json=AsyncMock(
+ return_value={
+ "results": [
+ {"title": f"Result {i}", "url": f"http://example.com/{i}", "content": "...", "score": 1.0}
+ for i in range(5)
+ ],
+ "answer": "test answer",
+ }
+ ),
+ )
+
+ mock_session.post = mock_post
+ mock_session.__aenter__ = AsyncMock(return_value=mock_session)
+ mock_session.__aexit__ = AsyncMock(return_value=None)
+
+ params = TavilySearchToolInputSchema(queries=["test query"])
+ output = await tool.run_async(params) # No max_results override
+
+ for call in mock_session.post.call_args_list:
+ assert call.kwargs["json"]["max_results"] == 5 # Should use config default (5)
+
+ def test_init_defaults(self):
+ """Default config should set max_results to 5."""
+ tool = TavilySearchTool()
+ assert tool.max_results == 5
+ assert tool.search_depth == "basic"
+
+ def test_config_respects_custom_max_results(self):
+ """Config should accept and store custom max_results."""
+ config = TavilySearchToolConfig(max_results=10)
+ tool = TavilySearchTool(config=config)
+ assert tool.max_results == 10
diff --git a/atomic-forge/atomic_tools/tavily_search/tool/__init__.py b/atomic-forge/atomic_tools/tavily_search/tool/__init__.py
new file mode 100644
index 0000000..8807f5d
--- /dev/null
+++ b/atomic-forge/atomic_tools/tavily_search/tool/__init__.py
@@ -0,0 +1,8 @@
+from tavily_search import TavilySearchTool, TavilySearchToolConfig, TavilySearchToolInputSchema, TavilySearchToolOutputSchema
+
+__all__ = [
+ "TavilySearchTool",
+ "TavilySearchToolConfig",
+ "TavilySearchToolInputSchema",
+ "TavilySearchToolOutputSchema",
+]
diff --git a/atomic-forge/atomic_tools/tavily_search/tool/tavily_search.py b/atomic-forge/atomic_tools/tavily_search/tool/tavily_search.py
new file mode 100644
index 0000000..a14195b
--- /dev/null
+++ b/atomic-forge/atomic_tools/tavily_search/tool/tavily_search.py
@@ -0,0 +1,171 @@
+import os
+from typing import List, Literal, Optional
+import asyncio
+from concurrent.futures import ThreadPoolExecutor
+
+import aiohttp
+from pydantic import Field
+
+from atomic_agents import BaseIOSchema, BaseTool, BaseToolConfig
+
+
+################
+# INPUT SCHEMA #
+################
+class TavilySearchToolInputSchema(BaseIOSchema):
+ """
+ Schema for input to a tool for searching for information, news, references, and other content using Tavily.
+ Returns a list of search results with a short description or content snippet and URLs for further exploration
+ """
+
+ queries: List[str] = Field(..., description="List of search queries.")
+
+
+####################
+# OUTPUT SCHEMA(S) #
+####################
+class TavilySearchResultItemSchema(BaseIOSchema):
+ """This schema represents a single search result item"""
+
+ title: str = Field(..., description="The title of the search result")
+ url: str = Field(..., description="The URL of the search result")
+ content: str = Field(None, description="The content snippet of the search result")
+ score: float = Field(..., description="The score of the search result")
+ raw_content: Optional[str] = Field(None, description="The raw content of the search result")
+ query: Optional[str] = Field(..., description="The query used to obtain this search result")
+ answer: Optional[str] = Field(..., description="The answer to the query provided by Tavily")
+
+
+class TavilySearchToolOutputSchema(BaseIOSchema):
+ """This schema represents the output of the Tavily search tool."""
+
+ results: List[TavilySearchResultItemSchema] = Field(..., description="List of search result items")
+
+
+##############
+# TOOL LOGIC #
+##############
+class TavilySearchToolConfig(BaseToolConfig):
+ api_key: str = ""
+ max_results: int = 5
+ search_depth: Literal["basic", "advanced"] = "basic"
+ include_domains: Optional[List[str]] = None
+ exclude_domains: Optional[List[str]] = None
+
+
+class TavilySearchTool(BaseTool[TavilySearchToolInputSchema, TavilySearchToolOutputSchema]):
+ """
+ Tool for performing searches using the Tavily search API.
+
+ Attributes:
+ input_schema (TavilySearchToolInputSchema): The schema for the input data.
+ output_schema (TavilySearchToolOutputSchema): The schema for the output data.
+ max_results (int): The maximum number of search results to return.
+ api_key (str): The API key for the Tavily API.
+ """
+
+ def __init__(self, config: TavilySearchToolConfig = TavilySearchToolConfig()):
+ """
+ Initializes the TavilySearchTool.
+
+ Args:
+ config (TavilySearchToolConfig):
+ Configuration for the tool, including API key, max results, and optional title and description overrides.
+ """
+ super().__init__(config)
+ self.api_key = config.api_key or os.getenv("TAVILY_API_KEY", "")
+ self.max_results = config.max_results
+ self.search_depth = config.search_depth
+ self.include_domains = config.include_domains
+ self.exclude_domains = config.exclude_domains
+ self.include_answer = False
+
+ async def _fetch_search_results(self, session: aiohttp.ClientSession, query: str, max_results: int) -> dict:
+ headers = {
+ "accept": "/",
+ "content-type": "application/json",
+ "origin": "https://app.tavily.com/",
+ "referer": "https://app.tavily.com/",
+ "user-agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36",
+ }
+
+ json_data = {
+ "query": query,
+ "api_key": self.api_key,
+ "search_depth": self.search_depth,
+ "include_domains": self.include_domains,
+ "exclude_domains": self.exclude_domains,
+ "max_results": max_results,
+ "include_answer": self.include_answer,
+ }
+
+ async with session.post("https://api.tavily.com/search", headers=headers, json=json_data) as response:
+ if response.status != 200:
+ error_message = await response.text()
+ raise Exception(
+ f"Failed to fetch search results for query '{query}': {response.status} {response.reason}. Details: {error_message}"
+ )
+ data = await response.json()
+
+ results = data.get("results", [])
+ answer = data.get("answer", "")
+
+ for result in results:
+ result["query"] = query
+
+ return {"results": results, "answer": answer}
+
+ async def run_async(
+ self, params: TavilySearchToolInputSchema, max_results: Optional[int] = None
+ ) -> TavilySearchToolOutputSchema:
+ effective_max_results = self.max_results if max_results is None else max_results
+
+ async with aiohttp.ClientSession() as session:
+ tasks = [self._fetch_search_results(session, query, effective_max_results) for query in params.queries]
+ raw_responses = await asyncio.gather(*tasks)
+
+ processed_results = []
+ for response in raw_responses:
+ query_results = response["results"]
+ answer = response["answer"]
+
+ query_processed = []
+ for result in query_results:
+ if all(key in result for key in ["title", "url", "content", "score"]):
+ query_processed.append(
+ TavilySearchResultItemSchema(
+ title=result["title"],
+ url=result["url"],
+ content=result.get("content", ""),
+ score=result.get("score", 0),
+ raw_content=result.get("raw_content"),
+ query=result.get("query"),
+ answer=answer,
+ )
+ )
+ else:
+ print(f"Skipping result due to missing keys: {result}")
+
+ query_processed = query_processed[:effective_max_results]
+ processed_results.extend(query_processed)
+
+ return TavilySearchToolOutputSchema(results=processed_results)
+
+ def run(self, params: TavilySearchToolInputSchema, max_results: Optional[int] = None) -> TavilySearchToolOutputSchema:
+ """
+ Runs the TavilyTool synchronously with the given parameters.
+
+ Args:
+ params (TavilySearchToolInputSchema): The input parameters for the tool, adhering to the input schema.
+ max_results (Optional[int]): The maximum number of search results to return.
+
+ Returns:
+ TavilySearchToolOutputSchema: The output of the tool, adhering to the output schema.
+ """
+ with ThreadPoolExecutor() as executor:
+ result = executor.submit(
+ asyncio.run,
+ self.run_async(params, max_results),
+ ).result()
+
+ return result