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

agno/tools/brandfetch.py

@@ -1,9 +1,10 @@
 """
-Going to contribute this to agno toolkits.
+Brandfetch API toolkit for retrieving brand data and searching brands.
 """
 
+import warnings
 from os import getenv
-from typing import Any, Optional
+from typing import Any, List, Optional
 
 try:
     import httpx
@@ -31,8 +32,6 @@ class BrandfetchTools(Toolkit):
     all: bool - if True, will use all tools
     enable_search_by_identifier: bool - if True, will use search by identifier
     enable_search_by_brand: bool - if True, will use search by brand
-    enable_asearch_by_identifier: bool - if True, will use async search by identifier
-    enable_asearch_by_brand: bool - if True, will use async search by brand
     """
 
     def __init__(
@@ -44,9 +43,18 @@ class BrandfetchTools(Toolkit):
         enable_search_by_identifier: bool = True,
         enable_search_by_brand: bool = False,
         all: bool = False,
-        async_tools: bool = False,
+        async_tools: bool = False,  # Deprecated
         **kwargs,
     ):
+        # Handle deprecated async_tools parameter
+        if async_tools:
+            warnings.warn(
+                "The 'async_tools' parameter is deprecated and will be removed in a future version. "
+                "Async tools are now automatically used when calling agent.arun() or agent.aprint_response().",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+
         self.api_key = api_key or getenv("BRANDFETCH_API_KEY")
         self.client_id = client_id or getenv("BRANDFETCH_CLIENT_ID")
         self.base_url = base_url
@@ -54,20 +62,21 @@ class BrandfetchTools(Toolkit):
         self.search_url = f"{self.base_url}/search"
         self.brand_url = f"{self.base_url}/brands"
 
-        tools: list[Any] = []
-        # Backward-compat mapping: prefer new enable_* flags, but honor legacy toggles
-        if async_tools:
-            if all or enable_search_by_identifier:
-                tools.append(self.asearch_by_identifier)
-            if all or enable_search_by_brand:
-                tools.append(self.asearch_by_brand)
-        else:
-            if all or enable_search_by_identifier:
-                tools.append(self.search_by_identifier)
-            if all or enable_search_by_brand:
-                tools.append(self.search_by_brand)
+        # Build tools lists
+        # sync tools: used by agent.run() and agent.print_response()
+        # async tools: used by agent.arun() and agent.aprint_response()
+        tools: List[Any] = []
+        async_tools_list: List[tuple] = []
+
+        if all or enable_search_by_identifier:
+            tools.append(self.search_by_identifier)
+            async_tools_list.append((self.asearch_by_identifier, "search_by_identifier"))
+        if all or enable_search_by_brand:
+            tools.append(self.search_by_brand)
+            async_tools_list.append((self.asearch_by_brand, "search_by_brand"))
+
         name = kwargs.pop("name", "brandfetch_tools")
-        super().__init__(name=name, tools=tools, **kwargs)
+        super().__init__(name=name, tools=tools, async_tools=async_tools_list, **kwargs)
 
     async def asearch_by_identifier(self, identifier: str) -> dict[str, Any]:
         """

agno/tools/browserbase.py

@@ -1,4 +1,5 @@
 import json
+import re
 from os import getenv
 from typing import Any, Dict, List, Optional
 
@@ -10,13 +11,6 @@ try:
 except ImportError:
     raise ImportError("`browserbase` not installed. Please install using `pip install browserbase`")
 
-try:
-    from playwright.sync_api import sync_playwright
-except ImportError:
-    raise ImportError(
-        "`playwright` not installed. Please install using `pip install playwright` and run `playwright install`"
-    )
-
 
 class BrowserbaseTools(Toolkit):
     def __init__(
@@ -29,6 +23,8 @@ class BrowserbaseTools(Toolkit):
         enable_get_page_content: bool = True,
         enable_close_session: bool = True,
         all: bool = False,
+        parse_html: bool = True,
+        max_content_length: Optional[int] = 100000,
         **kwargs,
     ):
         """Initialize BrowserbaseTools.
@@ -36,8 +32,21 @@ class BrowserbaseTools(Toolkit):
         Args:
             api_key (str, optional): Browserbase API key.
             project_id (str, optional): Browserbase project ID.
-            base_url (str, optional): Custom Browserbase API endpoint URL (NOT the target website URL). Only use this if you're using a self-hosted Browserbase instance or need to connect to a different region.
+            base_url (str, optional): Custom Browserbase API endpoint URL (NOT the target website URL).
+                Only use this if you're using a self-hosted Browserbase instance or need to connect to a different region.
+            enable_navigate_to (bool): Enable the navigate_to tool. Defaults to True.
+            enable_screenshot (bool): Enable the screenshot tool. Defaults to True.
+            enable_get_page_content (bool): Enable the get_page_content tool. Defaults to True.
+            enable_close_session (bool): Enable the close_session tool. Defaults to True.
+            all (bool): Enable all tools. Defaults to False.
+            parse_html (bool): If True, extract only visible text content instead of raw HTML. Defaults to True.
+                This significantly reduces token usage and is recommended for most use cases.
+            max_content_length (int, optional): Maximum character length for page content. Defaults to 100000.
+                Content exceeding this limit will be truncated with a notice. Set to None for no limit.
         """
+        self.parse_html = parse_html
+        self.max_content_length = max_content_length
+
         self.api_key = api_key or getenv("BROWSERBASE_API_KEY")
         if not self.api_key:
             raise ValueError(
@@ -59,23 +68,40 @@ class BrowserbaseTools(Toolkit):
         else:
             self.app = Browserbase(api_key=self.api_key)
 
+        # Sync playwright state
         self._playwright = None
         self._browser = None
         self._page = None
+
+        # Async playwright state
+        self._async_playwright = None
+        self._async_browser = None
+        self._async_page = None
+
+        # Shared session state
         self._session = None
         self._connect_url = None
 
+        # Build tools lists
+        # sync tools: used by agent.run() and agent.print_response()
+        # async tools: used by agent.arun() and agent.aprint_response()
         tools: List[Any] = []
+        async_tools: List[tuple] = []
+
         if all or enable_navigate_to:
             tools.append(self.navigate_to)
+            async_tools.append((self.anavigate_to, "navigate_to"))
         if all or enable_screenshot:
             tools.append(self.screenshot)
+            async_tools.append((self.ascreenshot, "screenshot"))
         if all or enable_get_page_content:
             tools.append(self.get_page_content)
+            async_tools.append((self.aget_page_content, "get_page_content"))
         if all or enable_close_session:
             tools.append(self.close_session)
+            async_tools.append((self.aclose_session, "close_session"))
 
-        super().__init__(name="browserbase_tools", tools=tools, **kwargs)
+        super().__init__(name="browserbase_tools", tools=tools, async_tools=async_tools, **kwargs)
 
     def _ensure_session(self):
         """Ensures a session exists, creating one if needed."""
@@ -91,9 +117,16 @@ class BrowserbaseTools(Toolkit):
 
     def _initialize_browser(self, connect_url: Optional[str] = None):
         """
-        Initialize browser connection if not already initialized.
+        Initialize sync browser connection if not already initialized.
         Use provided connect_url or ensure we have a session with a connect_url
         """
+        try:
+            from playwright.sync_api import sync_playwright  # type: ignore[import-not-found]
+        except ImportError:
+            raise ImportError(
+                "`playwright` not installed. Please install using `pip install playwright` and run `playwright install`"
+            )
+
         if connect_url:
             self._connect_url = connect_url if connect_url else ""  # type: ignore
         elif not self._connect_url:
@@ -107,7 +140,7 @@ class BrowserbaseTools(Toolkit):
             self._page = context.pages[0] or context.new_page()  # type: ignore
 
     def _cleanup(self):
-        """Clean up browser resources."""
+        """Clean up sync browser resources."""
         if self._browser:
             self._browser.close()
             self._browser = None
@@ -168,26 +201,77 @@ class BrowserbaseTools(Toolkit):
             self._cleanup()
             raise e
 
+    def _extract_text_content(self, html: str) -> str:
+        """Extract visible text content from HTML, removing scripts, styles, and tags.
+
+        Args:
+            html: Raw HTML content
+
+        Returns:
+            Cleaned text content
+        """
+        # Remove script and style elements
+        html = re.sub(r"<script[^>]*>.*?</script>", "", html, flags=re.DOTALL | re.IGNORECASE)
+        html = re.sub(r"<style[^>]*>.*?</style>", "", html, flags=re.DOTALL | re.IGNORECASE)
+        # Remove HTML comments
+        html = re.sub(r"<!--.*?-->", "", html, flags=re.DOTALL)
+        # Remove all HTML tags
+        html = re.sub(r"<[^>]+>", " ", html)
+        # Decode common HTML entities
+        html = html.replace("&nbsp;", " ")
+        html = html.replace("&amp;", "&")
+        html = html.replace("&lt;", "<")
+        html = html.replace("&gt;", ">")
+        html = html.replace("&quot;", '"')
+        html = html.replace("&#39;", "'")
+        # Normalize whitespace
+        html = re.sub(r"\s+", " ", html)
+        return html.strip()
+
+    def _truncate_content(self, content: str) -> str:
+        """Truncate content if it exceeds max_content_length.
+
+        Args:
+            content: The content to potentially truncate
+
+        Returns:
+            Original or truncated content with notice
+        """
+        if self.max_content_length is None or len(content) <= self.max_content_length:
+            return content
+
+        truncated = content[: self.max_content_length]
+        return f"{truncated}\n\n[Content truncated. Original length: {len(content)} characters. Showing first {self.max_content_length} characters.]"
+
     def get_page_content(self, connect_url: Optional[str] = None) -> str:
-        """Gets the HTML content of the current page.
+        """Gets the content of the current page.
 
         Args:
             connect_url (str, optional): The connection URL from an existing session
 
         Returns:
-            The page HTML content
+            The page content (text-only if parse_html=True, otherwise raw HTML)
         """
         try:
             self._initialize_browser(connect_url)
-            return self._page.content() if self._page else ""
+            if not self._page:
+                return ""
+
+            raw_content = self._page.content()
+
+            if self.parse_html:
+                content = self._extract_text_content(raw_content)
+            else:
+                content = raw_content
+
+            return self._truncate_content(content)
         except Exception as e:
             self._cleanup()
             raise e
 
     def close_session(self) -> str:
         """Closes a browser session.
-        Args:
-            session_id (str, optional): The session ID to close. If not provided, will use the current session.
+
         Returns:
             JSON string with closure status
         """
@@ -207,3 +291,128 @@ class BrowserbaseTools(Toolkit):
             )
         except Exception as e:
             return json.dumps({"status": "warning", "message": f"Cleanup completed with warning: {str(e)}"})
+
+    async def _ainitialize_browser(self, connect_url: Optional[str] = None):
+        """
+        Initialize async browser connection if not already initialized.
+        Use provided connect_url or ensure we have a session with a connect_url
+        """
+        try:
+            from playwright.async_api import async_playwright  # type: ignore[import-not-found]
+        except ImportError:
+            raise ImportError(
+                "`playwright` not installed. Please install using `pip install playwright` and run `playwright install`"
+            )
+
+        if connect_url:
+            self._connect_url = connect_url if connect_url else ""  # type: ignore
+        elif not self._connect_url:
+            self._ensure_session()
+
+        if not self._async_playwright:
+            self._async_playwright = await async_playwright().start()  # type: ignore
+            if self._async_playwright:
+                self._async_browser = await self._async_playwright.chromium.connect_over_cdp(self._connect_url)
+            context = self._async_browser.contexts[0] if self._async_browser else None
+            if context:
+                self._async_page = context.pages[0] if context.pages else await context.new_page()
+
+    async def _acleanup(self):
+        """Clean up async browser resources."""
+        if self._async_browser:
+            await self._async_browser.close()
+            self._async_browser = None
+        if self._async_playwright:
+            await self._async_playwright.stop()
+            self._async_playwright = None
+        self._async_page = None
+
+    async def anavigate_to(self, url: str, connect_url: Optional[str] = None) -> str:
+        """Navigates to a URL asynchronously.
+
+        Args:
+            url (str): The URL to navigate to
+            connect_url (str, optional): The connection URL from an existing session
+
+        Returns:
+            JSON string with navigation status
+        """
+        try:
+            await self._ainitialize_browser(connect_url)
+            if self._async_page:
+                await self._async_page.goto(url, wait_until="networkidle")
+            title = await self._async_page.title() if self._async_page else ""
+            result = {"status": "complete", "title": title, "url": url}
+            return json.dumps(result)
+        except Exception as e:
+            await self._acleanup()
+            raise e
+
+    async def ascreenshot(self, path: str, full_page: bool = True, connect_url: Optional[str] = None) -> str:
+        """Takes a screenshot of the current page asynchronously.
+
+        Args:
+            path (str): Where to save the screenshot
+            full_page (bool): Whether to capture the full page
+            connect_url (str, optional): The connection URL from an existing session
+
+        Returns:
+            JSON string confirming screenshot was saved
+        """
+        try:
+            await self._ainitialize_browser(connect_url)
+            if self._async_page:
+                await self._async_page.screenshot(path=path, full_page=full_page)
+            return json.dumps({"status": "success", "path": path})
+        except Exception as e:
+            await self._acleanup()
+            raise e
+
+    async def aget_page_content(self, connect_url: Optional[str] = None) -> str:
+        """Gets the content of the current page asynchronously.
+
+        Args:
+            connect_url (str, optional): The connection URL from an existing session
+
+        Returns:
+            The page content (text-only if parse_html=True, otherwise raw HTML)
+        """
+        try:
+            await self._ainitialize_browser(connect_url)
+            if not self._async_page:
+                return ""
+
+            raw_content = await self._async_page.content()
+
+            if self.parse_html:
+                content = self._extract_text_content(raw_content)
+            else:
+                content = raw_content
+
+            return self._truncate_content(content)
+        except Exception as e:
+            await self._acleanup()
+            raise e
+
+    async def aclose_session(self) -> str:
+        """Closes a browser session asynchronously.
+
+        Returns:
+            JSON string with closure status
+        """
+        try:
+            # First cleanup our local browser resources
+            await self._acleanup()
+
+            # Reset session state
+            self._session = None
+            self._connect_url = None
+
+            return json.dumps(
+                {
+                    "status": "closed",
+                    "message": "Browser resources cleaned up. Session will auto-close if not already closed.",
+                }
+            )
+        except Exception as e:
+            return json.dumps({"status": "warning", "message": f"Cleanup completed with warning: {str(e)}"})

agno/tools/crawl4ai.py

@@ -20,6 +20,7 @@ class Crawl4aiTools(Toolkit):
         bm25_threshold: float = 1.0,
         headless: bool = True,
         wait_until: str = "domcontentloaded",
+        proxy_config: Optional[Dict[str, Any]] = None,
         enable_crawl: bool = True,
         all: bool = False,
         **kwargs,
@@ -36,6 +37,7 @@ class Crawl4aiTools(Toolkit):
         self.bm25_threshold = bm25_threshold
         self.wait_until = wait_until
         self.headless = headless
+        self.proxy_config = proxy_config or {}
 
     def _build_config(self, search_query: Optional[str] = None) -> Dict[str, Any]:
         """Build CrawlerRunConfig parameters from toolkit settings."""
@@ -103,6 +105,7 @@ class Crawl4aiTools(Toolkit):
             browser_config = BrowserConfig(
                 headless=self.headless,
                 verbose=False,
+                **self.proxy_config,
             )
 
             async with AsyncWebCrawler(config=browser_config) as crawler:

agno/tools/duckduckgo.py

@@ -1,36 +1,26 @@
-import json
-from typing import Any, List, Optional
+from typing import Optional
 
-from agno.tools import Toolkit
-from agno.utils.log import log_debug
+from agno.tools.websearch import WebSearchTools
 
-try:
-    from ddgs import DDGS
-except ImportError:
-    raise ImportError("`ddgs` not installed. Please install using `pip install ddgs`")
 
-
-class DuckDuckGoTools(Toolkit):
+class DuckDuckGoTools(WebSearchTools):
     """
-    DuckDuckGo is a toolkit for searching using DuckDuckGo easily.
-    It uses the meta-search library DDGS, so it also has access to other backends.
+    DuckDuckGoTools is a convenience wrapper around WebSearchTools with the backend
+    defaulting to "duckduckgo".
     Args:
-        enable_search (bool): Enable DDGS search function.
-        enable_news (bool): Enable DDGS news function.
-        modifier (Optional[str]): A modifier to be used in the search request.
+        enable_search (bool): Enable web search function.
+        enable_news (bool): Enable news search function.
+        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 in the search request.
+        proxy (Optional[str]): Proxy to be used for requests.
         timeout (Optional[int]): The maximum number of seconds to wait for a response.
-        backend (Optional[str]): The backend to be used in the search request.
-
+        verify_ssl (bool): Whether to verify SSL certificates.
     """
 
     def __init__(
         self,
         enable_search: bool = True,
         enable_news: bool = True,
-        all: bool = False,
-        backend: str = "duckduckgo",
         modifier: Optional[str] = None,
         fixed_max_results: Optional[int] = None,
         proxy: Optional[str] = None,
@@ -38,54 +28,18 @@ class DuckDuckGoTools(Toolkit):
         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 all or enable_search:
-            tools.append(self.duckduckgo_search)
-        if all or enable_news:
-            tools.append(self.duckduckgo_news)
-
-        super().__init__(name="duckduckgo", tools=tools, **kwargs)
-
-    def duckduckgo_search(self, query: str, max_results: int = 5) -> str:
-        """Use this function to search DDGS 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 result from DDGS.
-        """
-        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 DDG 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 duckduckgo_news(self, query: str, max_results: int = 5) -> str:
-        """Use this function to get the latest news from DDGS.
-
-        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 DDGS.
-        """
-        actual_max_results = self.fixed_max_results or max_results
-
-        log_debug(f"Searching DDG 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)
+        super().__init__(
+            enable_search=enable_search,
+            enable_news=enable_news,
+            backend="duckduckgo",
+            modifier=modifier,
+            fixed_max_results=fixed_max_results,
+            proxy=proxy,
+            timeout=timeout,
+            verify_ssl=verify_ssl,
+            **kwargs,
+        )
+
+        # Backward compatibility aliases for old method names
+        self.duckduckgo_search = self.web_search
+        self.duckduckgo_news = self.search_news

agno/tools/exa.py

@@ -27,14 +27,12 @@ class ExaTools(Toolkit):
         all (bool): Enable all tools. Overrides individual flags when True. Default is False.
         text (bool): Retrieve text content from results. Default is True.
         text_length_limit (int): Max length of text content per result. Default is 1000.
-        highlights (bool): Include highlighted snippets. Deprecated since it was removed in the Exa API. It will be removed from Agno in a future release.
         api_key (Optional[str]): Exa API key. Retrieved from `EXA_API_KEY` env variable if not provided.
         num_results (Optional[int]): Default number of search results. Overrides individual searches if set.
         start_crawl_date (Optional[str]): Include results crawled on/after this date (`YYYY-MM-DD`).
         end_crawl_date (Optional[str]): Include results crawled on/before this date (`YYYY-MM-DD`).
         start_published_date (Optional[str]): Include results published on/after this date (`YYYY-MM-DD`).
         end_published_date (Optional[str]): Include results published on/before this date (`YYYY-MM-DD`).
-        use_autoprompt (Optional[bool]): Enable autoprompt features in queries. Deprecated since it was removed in the Exa API. It will be removed from Agno in a future release.
         type (Optional[str]): Specify content type (e.g., article, blog, video).
         category (Optional[str]): Filter results by category. Options are "company", "research paper", "news", "pdf", "github", "tweet", "personal site", "linkedin profile", "financial report".
         include_domains (Optional[List[str]]): Restrict results to these domains.
@@ -54,7 +52,6 @@ class ExaTools(Toolkit):
         all: bool = False,
         text: bool = True,
         text_length_limit: int = 1000,
-        highlights: Optional[bool] = None,  # Deprecated
         summary: bool = False,
         api_key: Optional[str] = None,
         num_results: Optional[int] = None,
@@ -63,7 +60,6 @@ class ExaTools(Toolkit):
         end_crawl_date: Optional[str] = None,
         start_published_date: Optional[str] = None,
         end_published_date: Optional[str] = None,
-        use_autoprompt: Optional[bool] = None,
         type: Optional[str] = None,
         category: Optional[str] = None,
         include_domains: Optional[List[str]] = None,
@@ -85,23 +81,6 @@ class ExaTools(Toolkit):
         self.text: bool = text
         self.text_length_limit: int = text_length_limit
 
-        if highlights:
-            import warnings
-
-            warnings.warn(
-                "The 'highlights' parameter is deprecated since it was removed in the Exa API. It will be removed from Agno in a future release.",
-                DeprecationWarning,
-                stacklevel=2,
-            )
-        if use_autoprompt:
-            import warnings
-
-            warnings.warn(
-                "The 'use_autoprompt' parameter is deprecated since it was removed in the Exa API. It will be removed from Agno in a future release.",
-                DeprecationWarning,
-                stacklevel=2,
-            )
-
         self.summary: bool = summary
         self.num_results: Optional[int] = num_results
         self.livecrawl: str = livecrawl

agno/tools/file.py

@@ -24,8 +24,7 @@ class FileTools(Toolkit):
         all: bool = False,
         **kwargs,
     ):
-        self.base_dir: Path = base_dir or Path.cwd()
-        self.base_dir = self.base_dir.resolve()
+        self.base_dir: Path = (base_dir or Path.cwd()).resolve()
 
         tools: List[Any] = []
         self.max_file_length = max_file_length
@@ -49,6 +48,19 @@ class FileTools(Toolkit):
 
         super().__init__(name="file_tools", tools=tools, **kwargs)
 
+    def check_escape(self, relative_path: str) -> Tuple[bool, Path]:
+        """Check if the file path is within the base directory.
+
+        Alias for _check_path maintained for backward compatibility.
+
+        Args:
+            relative_path: The file name or relative path to check.
+
+        Returns:
+            Tuple of (is_safe, resolved_path). If not safe, returns base_dir as the path.
+        """
+        return self._check_path(relative_path, self.base_dir)
+
     def save_file(self, contents: str, file_name: str, overwrite: bool = True, encoding: str = "utf-8") -> str:
         """Saves the contents to a file called `file_name` and returns the file name if successful.
 
@@ -173,17 +185,6 @@ class FileTools(Toolkit):
             log_error(f"Error removing {file_name}: {e}")
             return f"Error removing file: {e}"
 
-    def check_escape(self, relative_path: str) -> Tuple[bool, Path]:
-        d = self.base_dir.joinpath(Path(relative_path)).resolve()
-        if self.base_dir == d:
-            return True, d
-        try:
-            d.relative_to(self.base_dir)
-        except ValueError:
-            log_error("Attempted to escape base_dir")
-            return False, self.base_dir
-        return True, d
-
     def list_files(self, **kwargs) -> str:
         """Returns a list of files in directory
         :param directory: (Optional) name of directory to list.