agno 2.2.13__py3-none-any.whl → 2.4.3__py3-none-any.whl

agno/tools/tavily.py

@@ -15,6 +15,7 @@ class TavilyTools(Toolkit):
     def __init__(
         self,
         api_key: Optional[str] = None,
+        api_base_url: Optional[str] = None,
         enable_search: bool = True,
         enable_search_context: bool = False,
         enable_extract: bool = False,
@@ -34,6 +35,7 @@ class TavilyTools(Toolkit):
 
         Args:
             api_key: Tavily API key. If not provided, will use TAVILY_API_KEY env var.
+            api_base_url: Tavily API base URL. If not provided, will use TAVILY_API_BASE_URL env var. Defaults to None. If None - will use https://api.tavily.com.
             enable_search: Enable web search functionality. Defaults to True.
             enable_search_context: Use search context mode instead of regular search. Defaults to False.
             enable_extract: Enable URL content extraction functionality. Defaults to False.
@@ -52,8 +54,9 @@ class TavilyTools(Toolkit):
         self.api_key = api_key or getenv("TAVILY_API_KEY")
         if not self.api_key:
             logger.error("TAVILY_API_KEY not provided")
+        self.api_base_url = api_base_url or getenv("TAVILY_API_BASE_URL")
 
-        self.client: TavilyClient = TavilyClient(api_key=self.api_key)
+        self.client: TavilyClient = TavilyClient(api_key=self.api_key, api_base_url=self.api_base_url)
         self.search_depth: Literal["basic", "advanced"] = search_depth
         self.extract_depth: Literal["basic", "advanced"] = extract_depth
         self.max_tokens: int = max_tokens

agno/tools/toolkit.py

@@ -1,15 +1,22 @@
 from collections import OrderedDict
-from typing import Any, Callable, Dict, List, Optional
+from inspect import iscoroutinefunction
+from pathlib import Path
+from typing import Any, Callable, Dict, List, Optional, Sequence, Tuple, Union
 
 from agno.tools.function import Function
-from agno.utils.log import log_debug, log_warning, logger
+from agno.utils.log import log_debug, log_error, log_warning, logger
 
 
 class Toolkit:
+    # Set to True for toolkits that require connection management (e.g., database connections)
+    # When True, the Agent will automatically call connect() before using tools and close() after
+    _requires_connect: bool = False
+
     def __init__(
         self,
         name: str = "toolkit",
-        tools: List[Callable] = [],
+        tools: Sequence[Union[Callable[..., Any], Function]] = [],
+        async_tools: Optional[Sequence[tuple[Callable[..., Any], str]]] = None,
         instructions: Optional[str] = None,
         add_instructions: bool = False,
         include_tools: Optional[list[str]] = None,
@@ -27,7 +34,10 @@ class Toolkit:
 
         Args:
             name: A descriptive name for the toolkit
-            tools: List of tools to include in the toolkit
+            tools: List of tools to include in the toolkit (can be callables or Function objects from @tool decorator)
+            async_tools: List of (async_callable, tool_name) tuples for async variants.
+                        Used when async methods have different names than sync methods.
+                        Example: [(self.anavigate_to, "navigate_to"), (self.ascreenshot, "screenshot")]
             instructions: Instructions for the toolkit
             add_instructions: Whether to add instructions to the toolkit
             include_tools: List of tool names to include in the toolkit
@@ -42,8 +52,12 @@ class Toolkit:
             show_result_tools (Optional[List[str]]): List of function names whose results should be shown.
         """
         self.name: str = name
-        self.tools: List[Callable] = tools
+        self.tools: Sequence[Union[Callable[..., Any], Function]] = tools
+        self._async_tools: Sequence[tuple[Callable[..., Any], str]] = async_tools or []
+        # Functions dict - used by agent.run() and agent.print_response()
         self.functions: Dict[str, Function] = OrderedDict()
+        # Async functions dict - used by agent.arun() and agent.aprint_response()
+        self.async_functions: Dict[str, Function] = OrderedDict()
         self.instructions: Optional[str] = instructions
         self.add_instructions: bool = add_instructions
 
@@ -54,7 +68,9 @@ class Toolkit:
         self.show_result_tools: list[str] = show_result_tools or []
 
         self._check_tools_filters(
-            available_tools=[tool.__name__ for tool in tools], include_tools=include_tools, exclude_tools=exclude_tools
+            available_tools=[self._get_tool_name(tool) for tool in tools],
+            include_tools=include_tools,
+            exclude_tools=exclude_tools,
         )
 
         self.include_tools = include_tools
@@ -65,8 +81,17 @@ class Toolkit:
         self.cache_dir: Optional[str] = cache_dir
 
         # Automatically register all methods if auto_register is True
-        if auto_register and self.tools:
-            self._register_tools()
+        if auto_register:
+            if self.tools:
+                self._register_tools()
+            if self._async_tools:
+                self._register_async_tools()
+
+    def _get_tool_name(self, tool: Union[Callable[..., Any], Function]) -> str:
+        """Get the name of a tool, whether it's a Function or callable."""
+        if isinstance(tool, Function):
+            return tool.name
+        return tool.__name__
 
     def _check_tools_filters(
         self,
@@ -100,22 +125,57 @@ class Toolkit:
                     f"External execution required tool(s) not present in the toolkit: {', '.join(missing_external_execution_required)}"
                 )
 
+        if self.stop_after_tool_call_tools:
+            missing_stop_after_tool_call = set(self.stop_after_tool_call_tools) - set(available_tools)
+            if missing_stop_after_tool_call:
+                log_warning(
+                    f"Stop after tool call tool(s) not present in the toolkit: {', '.join(missing_stop_after_tool_call)}"
+                )
+
+        if self.show_result_tools:
+            missing_show_result = set(self.show_result_tools) - set(available_tools)
+            if missing_show_result:
+                log_warning(f"Show result tool(s) not present in the toolkit: {', '.join(missing_show_result)}")
+
     def _register_tools(self) -> None:
-        """Register all tools."""
+        """Register all sync tools."""
         for tool in self.tools:
             self.register(tool)
 
-    def register(self, function: Callable[..., Any], name: Optional[str] = None):
+    def _register_async_tools(self) -> None:
+        """Register all async tools with their mapped names.
+
+        Async detection is automatic via iscoroutinefunction.
+        """
+        for async_func, tool_name in self._async_tools:
+            self.register(async_func, name=tool_name)
+
+    def register(self, function: Union[Callable[..., Any], Function], name: Optional[str] = None) -> None:
         """Register a function with the toolkit.
 
-        Args:
-            function: The callable to register
-            name: Optional custom name for the function
+        This method supports both regular callables and Function objects (from @tool decorator).
+        Automatically detects if the function is async (using iscoroutinefunction) and registers
+        it to the appropriate dict (functions for sync, async_functions for async).
 
-        Returns:
-            The registered function
+        When a Function object is passed (e.g., from a @tool decorated method), it will:
+        1. Extract the configuration from the Function object
+        2. Look for a bound method with the same name on `self`
+        3. Create a new Function with the bound method as entrypoint, preserving decorator settings
+
+        Args:
+            function: The callable or Function object to register
+            name: Optional custom name for the function (useful for aliasing)
         """
         try:
+            # Handle Function objects (from @tool decorator)
+            if isinstance(function, Function):
+                # Auto-detect if this is an async function
+                is_async = function.entrypoint is not None and iscoroutinefunction(function.entrypoint)
+                return self._register_decorated_tool(function, name, is_async=is_async)
+
+            # Handle regular callables - auto-detect async
+            is_async = iscoroutinefunction(function)
+
             tool_name = name or function.__name__
             if self.include_tools is not None and tool_name not in self.include_tools:
                 return
@@ -133,12 +193,187 @@ class Toolkit:
                 stop_after_tool_call=tool_name in self.stop_after_tool_call_tools,
                 show_result=tool_name in self.show_result_tools or tool_name in self.stop_after_tool_call_tools,
             )
-            self.functions[f.name] = f
-            log_debug(f"Function: {f.name} registered with {self.name}")
+
+            if is_async:
+                self.async_functions[f.name] = f
+                log_debug(f"Async function: {f.name} registered with {self.name}")
+            else:
+                self.functions[f.name] = f
+                log_debug(f"Function: {f.name} registered with {self.name}")
         except Exception as e:
-            logger.warning(f"Failed to create Function for: {function.__name__}")
+            func_name = self._get_tool_name(function)
+            logger.warning(f"Failed to create Function for: {func_name}")
             raise e
 
+    def _register_decorated_tool(self, function: Function, name: Optional[str] = None, is_async: bool = False) -> None:
+        """Register a Function object from @tool decorator, binding it to self.
+
+        When @tool decorator is used on a class method, it creates a Function with an unbound
+        method as entrypoint. This method creates a bound version of the entrypoint that
+        includes `self`, preserving all decorator settings.
+
+        Args:
+            function: The Function object from @tool decorator
+            name: Optional custom name override
+            is_async: If True, register to async_functions dict instead of functions
+        """
+        import inspect
+
+        tool_name = name or function.name
+        if self.include_tools is not None and len(self.include_tools) > 0 and tool_name not in self.include_tools:
+            return
+        if self.exclude_tools is not None and len(self.exclude_tools) > 0 and tool_name in self.exclude_tools:
+            return
+
+        # Get the original entrypoint from the Function
+        if function.entrypoint is None:
+            log_warning(f"Function '{tool_name}' has no entrypoint, skipping registration")
+            return
+
+        original_func = function.entrypoint
+
+        # Check if the function expects 'self' as first argument (i.e., it's an unbound method)
+        sig = inspect.signature(original_func)
+        params = list(sig.parameters.keys())
+
+        if params and params[0] == "self":
+            # Create a bound method by wrapping the function to include self
+            if is_async:
+
+                def make_bound_method(func, instance):
+                    async def bound(*args, **kwargs):
+                        return await func(instance, *args, **kwargs)
+
+                    bound.__name__ = getattr(func, "__name__", tool_name)
+                    bound.__doc__ = getattr(func, "__doc__", None)
+                    return bound
+            else:
+
+                def make_bound_method(func, instance):
+                    def bound(*args, **kwargs):
+                        return func(instance, *args, **kwargs)
+
+                    bound.__name__ = getattr(func, "__name__", tool_name)
+                    bound.__doc__ = getattr(func, "__doc__", None)
+                    return bound
+
+            bound_method = make_bound_method(original_func, self)
+        else:
+            # Function doesn't expect self (e.g., static method or already bound)
+            bound_method = original_func
+
+        # decorator settings take precedence, then toolkit settings
+        stop_after = function.stop_after_tool_call or tool_name in self.stop_after_tool_call_tools
+        show_result = function.show_result or tool_name in self.show_result_tools or stop_after
+        requires_confirmation = function.requires_confirmation or tool_name in self.requires_confirmation_tools
+        external_execution = function.external_execution or tool_name in self.external_execution_required_tools
+
+        # Create new Function with bound method, preserving decorator settings
+        f = Function(
+            name=tool_name,
+            description=function.description,
+            parameters=function.parameters,
+            strict=function.strict,
+            instructions=function.instructions,
+            add_instructions=function.add_instructions,
+            entrypoint=bound_method,
+            skip_entrypoint_processing=True,  # Parameters already processed by decorator
+            show_result=show_result,
+            stop_after_tool_call=stop_after,
+            pre_hook=function.pre_hook,
+            post_hook=function.post_hook,
+            tool_hooks=function.tool_hooks,
+            requires_confirmation=requires_confirmation,
+            requires_user_input=function.requires_user_input,
+            user_input_fields=function.user_input_fields,
+            user_input_schema=function.user_input_schema,
+            external_execution=external_execution,
+            cache_results=function.cache_results if function.cache_results else self.cache_results,
+            cache_dir=function.cache_dir if function.cache_dir else self.cache_dir,
+            cache_ttl=function.cache_ttl if function.cache_ttl != 3600 else self.cache_ttl,
+        )
+
+        if is_async:
+            self.async_functions[f.name] = f
+            log_debug(f"Async function: {f.name} registered with {self.name} (from @tool decorator)")
+        else:
+            self.functions[f.name] = f
+            log_debug(f"Function: {f.name} registered with {self.name} (from @tool decorator)")
+
+    def get_functions(self) -> Dict[str, Function]:
+        """Get sync functions dict.
+
+        Returns:
+            Dict of function name to Function for sync execution
+        """
+        return self.functions
+
+    def get_async_functions(self) -> Dict[str, Function]:
+        """Get functions dict optimized for async execution.
+
+        Returns a merged dict where async_functions take precedence over functions.
+        This allows async-optimized implementations to be automatically used in async contexts,
+        while falling back to sync implementations for tools without async variants.
+
+        Returns:
+            Dict of function name to Function, with async variants preferred
+        """
+        # Merge: start with sync functions, override with async variants
+        merged = OrderedDict(self.functions)
+        merged.update(self.async_functions)
+        return merged
+
+    @property
+    def requires_connect(self) -> bool:
+        """Whether the toolkit requires connection management."""
+        return self._requires_connect
+
+    def connect(self) -> None:
+        """
+        Establish any required connections for the toolkit.
+        Override this method in subclasses that require connection management.
+        Called automatically by the Agent when _requires_connect is True.
+        """
+        pass
+
+    def close(self) -> None:
+        """
+        Close any open connections for the toolkit.
+        Override this method in subclasses that require connection management.
+        Called automatically by the Agent when _requires_connect is True.
+        """
+        pass
+
+    def _check_path(self, file_name: str, base_dir: Path, restrict_to_base_dir: bool = True) -> Tuple[bool, Path]:
+        """Check if the file path is within the base directory.
+
+        This method validates that a given file path resolves to a location
+        within the specified base_dir, preventing directory traversal attacks.
+
+        Args:
+            file_name: The file name or relative path to check.
+            base_dir: The base directory to validate against.
+            restrict_to_base_dir: If True, reject paths outside base_dir.
+
+        Returns:
+            Tuple of (is_safe, resolved_path). If not safe, returns base_dir as the path.
+        """
+        file_path = base_dir.joinpath(file_name).resolve()
+
+        if not restrict_to_base_dir:
+            return True, file_path
+
+        if base_dir == file_path:
+            return True, file_path
+
+        try:
+            file_path.relative_to(base_dir)
+        except ValueError:
+            log_error(f"Path escapes base directory: {file_name}")
+            return False, base_dir
+
+        return True, file_path
+
     def __repr__(self):
         return f"<{self.__class__.__name__} name={self.name} functions={list(self.functions.keys())}>"
 

agno/tools/websearch.py

@@ -0,0 +1,93 @@
+import json
+from typing import Any, List, Optional
+
+from agno.tools import Toolkit
+from agno.utils.log import log_debug
+
+try:
+    from ddgs import DDGS
+except ImportError:
+    raise ImportError("`ddgs` not installed. Please install using `pip install ddgs`")
+
+
+class WebSearchTools(Toolkit):
+    """
+    Toolkit for searching the web. Uses the meta-search library DDGS.
+    Multiple search backends (e.g. google, bing, duckduckgo) are available.
+
+    Args:
+        enable_search (bool): Enable web search function.
+        enable_news (bool): Enable news search function.
+        backend (str): The backend to use for searching. Defaults to "auto" which
+            automatically selects available backends. Other options include:
+            "duckduckgo", "google", "bing", "brave", "yandex", "yahoo", etc.
+        modifier (Optional[str]): A modifier to be prepended to search queries.
+        fixed_max_results (Optional[int]): A fixed number of maximum results.
+        proxy (Optional[str]): Proxy to be used for requests.
+        timeout (Optional[int]): The maximum number of seconds to wait for a response.
+        verify_ssl (bool): Whether to verify SSL certificates.
+    """
+
+    def __init__(
+        self,
+        enable_search: bool = True,
+        enable_news: bool = True,
+        backend: str = "auto",
+        modifier: Optional[str] = None,
+        fixed_max_results: Optional[int] = None,
+        proxy: Optional[str] = None,
+        timeout: Optional[int] = 10,
+        verify_ssl: bool = True,
+        **kwargs,
+    ):
+        self.proxy: Optional[str] = proxy
+        self.timeout: Optional[int] = timeout
+        self.fixed_max_results: Optional[int] = fixed_max_results
+        self.modifier: Optional[str] = modifier
+        self.verify_ssl: bool = verify_ssl
+        self.backend: str = backend
+
+        tools: List[Any] = []
+        if enable_search:
+            tools.append(self.web_search)
+        if enable_news:
+            tools.append(self.search_news)
+
+        super().__init__(name="websearch", tools=tools, **kwargs)
+
+    def web_search(self, query: str, max_results: int = 5) -> str:
+        """Use this function to search the web for a query.
+
+        Args:
+            query(str): The query to search for.
+            max_results (optional, default=5): The maximum number of results to return.
+
+        Returns:
+            The search results from the web.
+        """
+        actual_max_results = self.fixed_max_results or max_results
+        search_query = f"{self.modifier} {query}" if self.modifier else query
+
+        log_debug(f"Searching web for: {search_query} using backend: {self.backend}")
+        with DDGS(proxy=self.proxy, timeout=self.timeout, verify=self.verify_ssl) as ddgs:
+            results = ddgs.text(query=search_query, max_results=actual_max_results, backend=self.backend)
+
+        return json.dumps(results, indent=2)
+
+    def search_news(self, query: str, max_results: int = 5) -> str:
+        """Use this function to get the latest news from the web.
+
+        Args:
+            query(str): The query to search for.
+            max_results (optional, default=5): The maximum number of results to return.
+
+        Returns:
+            The latest news from the web.
+        """
+        actual_max_results = self.fixed_max_results or max_results
+
+        log_debug(f"Searching web news for: {query} using backend: {self.backend}")
+        with DDGS(proxy=self.proxy, timeout=self.timeout, verify=self.verify_ssl) as ddgs:
+            results = ddgs.news(query=query, max_results=actual_max_results, backend=self.backend)
+
+        return json.dumps(results, indent=2)

agno/tools/website.py

@@ -36,7 +36,7 @@ class WebsiteTools(Toolkit):
             return "Knowledge base not provided"
 
         log_debug(f"Adding to knowledge base: {url}")
-        self.knowledge.add_content(url=url)
+        self.knowledge.insert(url=url)
         return "Success"
 
     def read_url(self, url: str) -> str:

agno/tools/wikipedia.py

@@ -38,7 +38,7 @@ class WikipediaTools(Toolkit):
             return "Knowledge not provided"
 
         log_debug(f"Adding to knowledge: {topic}")
-        self.knowledge.add_content(
+        self.knowledge.insert(
             topics=[topic],
             reader=WikipediaReader(),
         )