agno 2.0.0rc2__py3-none-any.whl → 2.3.0__py3-none-any.whl

agno/tools/parallel.py

@@ -0,0 +1,314 @@
+import json
+from os import getenv
+from typing import Any, Dict, List, Optional
+
+from agno.tools import Toolkit
+from agno.utils.log import log_error
+
+try:
+    from parallel import Parallel as ParallelClient
+except ImportError:
+    raise ImportError("`parallel-web` not installed. Please install using `pip install parallel-web`")
+
+
+class CustomJSONEncoder(json.JSONEncoder):
+    """Custom JSON encoder that handles non-serializable types by converting them to strings."""
+
+    def default(self, obj):
+        try:
+            return super().default(obj)
+        except TypeError:
+            return str(obj)
+
+
+class ParallelTools(Toolkit):
+    """
+    ParallelTools provides access to Parallel's web search and extraction APIs.
+
+    Parallel offers powerful APIs optimized for AI agents:
+    - Search API: AI-optimized web search that returns relevant excerpts tailored for LLMs
+    - Extract API: Extract content from specific URLs in clean markdown format, handling JavaScript-heavy pages and PDFs
+
+    Args:
+        api_key (Optional[str]): Parallel API key. If not provided, will use PARALLEL_API_KEY environment variable.
+        enable_search (bool): Enable Search API functionality. Default is True.
+        enable_extract (bool): Enable Extract API functionality. Default is True.
+        all (bool): Enable all tools. Overrides individual flags when True. Default is False.
+        max_results (int): Default maximum number of results for search operations. Default is 10.
+        max_chars_per_result (int): Default maximum characters per result for search operations. Default is 10000.
+        beta_version (str): Beta API version header. Default is "search-extract-2025-10-10".
+        mode (Optional[str]): Default search mode. Options: "one-shot" or "agentic". Default is None.
+        include_domains (Optional[List[str]]): Default domains to restrict results to. Default is None.
+        exclude_domains (Optional[List[str]]): Default domains to exclude from results. Default is None.
+        max_age_seconds (Optional[int]): Default cache age threshold (minimum 600). Default is None.
+        timeout_seconds (Optional[float]): Default timeout for content retrieval. Default is None.
+        disable_cache_fallback (Optional[bool]): Default cache fallback behavior. Default is None.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        enable_search: bool = True,
+        enable_extract: bool = True,
+        all: bool = False,
+        max_results: int = 10,
+        max_chars_per_result: int = 10000,
+        beta_version: str = "search-extract-2025-10-10",
+        mode: Optional[str] = None,
+        include_domains: Optional[List[str]] = None,
+        exclude_domains: Optional[List[str]] = None,
+        max_age_seconds: Optional[int] = None,
+        timeout_seconds: Optional[float] = None,
+        disable_cache_fallback: Optional[bool] = None,
+        **kwargs,
+    ):
+        self.api_key: Optional[str] = api_key or getenv("PARALLEL_API_KEY")
+        if not self.api_key:
+            log_error("PARALLEL_API_KEY not set. Please set the PARALLEL_API_KEY environment variable.")
+
+        self.max_results = max_results
+        self.max_chars_per_result = max_chars_per_result
+        self.beta_version = beta_version
+        self.mode = mode
+        self.include_domains = include_domains
+        self.exclude_domains = exclude_domains
+        self.max_age_seconds = max_age_seconds
+        self.timeout_seconds = timeout_seconds
+        self.disable_cache_fallback = disable_cache_fallback
+
+        self.parallel_client = ParallelClient(
+            api_key=self.api_key, default_headers={"parallel-beta": self.beta_version}
+        )
+
+        tools: List[Any] = []
+        if all or enable_search:
+            tools.append(self.parallel_search)
+        if all or enable_extract:
+            tools.append(self.parallel_extract)
+
+        super().__init__(name="parallel_tools", tools=tools, **kwargs)
+
+    def parallel_search(
+        self,
+        objective: Optional[str] = None,
+        search_queries: Optional[List[str]] = None,
+        max_results: Optional[int] = None,
+        max_chars_per_result: Optional[int] = None,
+    ) -> str:
+        """Use this function to search the web using Parallel's Search API with a natural language objective.
+        You must provide at least one of objective or search_queries.
+
+        Args:
+            objective (Optional[str]): Natural-language description of what the web search is trying to find.
+            search_queries (Optional[List[str]]): Traditional keyword queries with optional search operators.
+            max_results (Optional[int]): Upper bound on results returned. Overrides constructor default.
+            max_chars_per_result (Optional[int]): Upper bound on total characters per url for excerpts.
+
+        Returns:
+            str: A JSON formatted string containing the search results with URLs, titles, publish dates, and relevant excerpts.
+        """
+        try:
+            if not objective and not search_queries:
+                return json.dumps({"error": "Please provide at least one of: objective or search_queries"}, indent=2)
+
+            # Use instance defaults if not provided
+            final_max_results = max_results if max_results is not None else self.max_results
+
+            search_params: Dict[str, Any] = {
+                "max_results": final_max_results,
+            }
+
+            # Add objective if provided
+            if objective:
+                search_params["objective"] = objective
+
+            # Add search_queries if provided
+            if search_queries:
+                search_params["search_queries"] = search_queries
+
+            # Add mode from constructor default
+            if self.mode:
+                search_params["mode"] = self.mode
+
+            # Add excerpts configuration
+            excerpts_config: Dict[str, Any] = {}
+            final_max_chars = max_chars_per_result if max_chars_per_result is not None else self.max_chars_per_result
+            if final_max_chars is not None:
+                excerpts_config["max_chars_per_result"] = final_max_chars
+
+            if excerpts_config:
+                search_params["excerpts"] = excerpts_config
+
+            # Add source_policy from constructor defaults
+            source_policy: Dict[str, Any] = {}
+            if self.include_domains:
+                source_policy["include_domains"] = self.include_domains
+            if self.exclude_domains:
+                source_policy["exclude_domains"] = self.exclude_domains
+
+            if source_policy:
+                search_params["source_policy"] = source_policy
+
+            # Add fetch_policy from constructor defaults
+            fetch_policy: Dict[str, Any] = {}
+            if self.max_age_seconds is not None:
+                fetch_policy["max_age_seconds"] = self.max_age_seconds
+            if self.timeout_seconds is not None:
+                fetch_policy["timeout_seconds"] = self.timeout_seconds
+            if self.disable_cache_fallback is not None:
+                fetch_policy["disable_cache_fallback"] = self.disable_cache_fallback
+
+            if fetch_policy:
+                search_params["fetch_policy"] = fetch_policy
+
+            search_result = self.parallel_client.beta.search(**search_params)
+
+            # Use model_dump() if available, otherwise convert to dict
+            try:
+                if hasattr(search_result, "model_dump"):
+                    return json.dumps(search_result.model_dump(), cls=CustomJSONEncoder)
+            except Exception:
+                pass
+
+            # Manually format the results
+            formatted_results: Dict[str, Any] = {
+                "search_id": getattr(search_result, "search_id", ""),
+                "results": [],
+            }
+
+            if hasattr(search_result, "results") and search_result.results:
+                results_list: List[Dict[str, Any]] = []
+                for result in search_result.results:
+                    formatted_result: Dict[str, Any] = {
+                        "title": getattr(result, "title", ""),
+                        "url": getattr(result, "url", ""),
+                        "publish_date": getattr(result, "publish_date", ""),
+                        "excerpt": getattr(result, "excerpt", ""),
+                    }
+                    results_list.append(formatted_result)
+                formatted_results["results"] = results_list
+
+            if hasattr(search_result, "warnings"):
+                formatted_results["warnings"] = search_result.warnings
+
+            if hasattr(search_result, "usage"):
+                formatted_results["usage"] = search_result.usage
+
+            return json.dumps(formatted_results, cls=CustomJSONEncoder, indent=2)
+
+        except Exception as e:
+            log_error(f"Error searching Parallel for objective '{objective}': {e}")
+            return json.dumps({"error": f"Search failed: {str(e)}"}, indent=2)
+
+    def parallel_extract(
+        self,
+        urls: List[str],
+        objective: Optional[str] = None,
+        search_queries: Optional[List[str]] = None,
+        excerpts: bool = True,
+        max_chars_per_excerpt: Optional[int] = None,
+        full_content: bool = False,
+        max_chars_for_full_content: Optional[int] = None,
+    ) -> str:
+        """Use this function to extract content from specific URLs using Parallel's Extract API.
+
+        Args:
+            urls (List[str]): List of public URLs to extract content from.
+            objective (Optional[str]): Search focus to guide content extraction.
+            search_queries (Optional[List[str]]): Keywords for targeting relevant content.
+            excerpts (bool): Include relevant text snippets.
+            max_chars_per_excerpt (Optional[int]): Upper bound on total characters per url. Only used when excerpts is True.
+            full_content (bool): Include complete page text.
+            max_chars_for_full_content (Optional[int]): Limit on characters per url. Only used when full_content is True.
+
+        Returns:
+            str: A JSON formatted string containing extracted content with titles, publish dates, excerpts and/or full content.
+        """
+        try:
+            if not urls:
+                return json.dumps({"error": "Please provide at least one URL to extract"}, indent=2)
+
+            extract_params: Dict[str, Any] = {
+                "urls": urls,
+            }
+
+            # Add objective if provided
+            if objective:
+                extract_params["objective"] = objective
+
+            # Add search_queries if provided
+            if search_queries:
+                extract_params["search_queries"] = search_queries
+
+            # Add excerpts configuration
+            if excerpts and max_chars_per_excerpt is not None:
+                extract_params["excerpts"] = {"max_chars_per_result": max_chars_per_excerpt}
+            else:
+                extract_params["excerpts"] = excerpts
+
+            # Add full_content configuration
+            if full_content and max_chars_for_full_content is not None:
+                extract_params["full_content"] = {"max_chars_per_result": max_chars_for_full_content}
+            else:
+                extract_params["full_content"] = full_content
+
+            # Add fetch_policy from constructor defaults
+            fetch_policy: Dict[str, Any] = {}
+            if self.max_age_seconds is not None:
+                fetch_policy["max_age_seconds"] = self.max_age_seconds
+            if self.timeout_seconds is not None:
+                fetch_policy["timeout_seconds"] = self.timeout_seconds
+            if self.disable_cache_fallback is not None:
+                fetch_policy["disable_cache_fallback"] = self.disable_cache_fallback
+
+            if fetch_policy:
+                extract_params["fetch_policy"] = fetch_policy
+
+            extract_result = self.parallel_client.beta.extract(**extract_params)
+
+            # Use model_dump() if available, otherwise convert to dict
+            try:
+                if hasattr(extract_result, "model_dump"):
+                    return json.dumps(extract_result.model_dump(), cls=CustomJSONEncoder)
+            except Exception:
+                pass
+
+            # Manually format the results
+            formatted_results: Dict[str, Any] = {
+                "extract_id": getattr(extract_result, "extract_id", ""),
+                "results": [],
+                "errors": [],
+            }
+
+            if hasattr(extract_result, "results") and extract_result.results:
+                results_list: List[Dict[str, Any]] = []
+                for result in extract_result.results:
+                    formatted_result: Dict[str, Any] = {
+                        "url": getattr(result, "url", ""),
+                        "title": getattr(result, "title", ""),
+                        "publish_date": getattr(result, "publish_date", ""),
+                    }
+
+                    if excerpts and hasattr(result, "excerpts"):
+                        formatted_result["excerpts"] = result.excerpts
+
+                    if full_content and hasattr(result, "full_content"):
+                        formatted_result["full_content"] = result.full_content
+
+                    results_list.append(formatted_result)
+                formatted_results["results"] = results_list
+
+            if hasattr(extract_result, "errors") and extract_result.errors:
+                formatted_results["errors"] = extract_result.errors
+
+            if hasattr(extract_result, "warnings"):
+                formatted_results["warnings"] = extract_result.warnings
+
+            if hasattr(extract_result, "usage"):
+                formatted_results["usage"] = extract_result.usage
+
+            return json.dumps(formatted_results, cls=CustomJSONEncoder, indent=2)
+
+        except Exception as e:
+            log_error(f"Error extracting from Parallel: {e}")
+            return json.dumps({"error": f"Extract failed: {str(e)}"}, indent=2)

agno/tools/replicate.py

@@ -5,7 +5,7 @@ from urllib.parse import urlparse
 from uuid import uuid4
 
 from agno.agent import Agent
-from agno.media import ImageArtifact, VideoArtifact
+from agno.media import Image, Video
 from agno.team.team import Team
 from agno.tools import Toolkit
 from agno.tools.function import ToolResult
@@ -72,9 +72,9 @@ class ReplicateTools(Toolkit):
                 result_msg, media_artifact = self._parse_output(output)
                 results.append(result_msg)
 
-                if isinstance(media_artifact, ImageArtifact):
+                if isinstance(media_artifact, Image):
                     images.append(media_artifact)
-                elif isinstance(media_artifact, VideoArtifact):
+                elif isinstance(media_artifact, Video):
                     videos.append(media_artifact)
 
             content = "\n".join(results)
@@ -87,7 +87,7 @@ class ReplicateTools(Toolkit):
             logger.error(f"Failed to generate media: {e}")
             return ToolResult(content=f"Error: {e}")
 
-    def _parse_output(self, output: FileOutput) -> Tuple[str, Union[ImageArtifact, VideoArtifact]]:
+    def _parse_output(self, output: FileOutput) -> Tuple[str, Union[Image, Video]]:
         """
         Parse the outputs from the replicate model.
         """
@@ -101,14 +101,14 @@ class ReplicateTools(Toolkit):
         video_extensions = {".mp4", ".mov", ".avi", ".mkv", ".flv", ".wmv", ".webm"}
 
         media_id = str(uuid4())
-        artifact: Union[ImageArtifact, VideoArtifact]
+        artifact: Union[Image, Video]
         media_type: str
 
         if ext in image_extensions:
-            artifact = ImageArtifact(id=media_id, url=output.url)
+            artifact = Image(id=media_id, url=output.url)
             media_type = "image"
         elif ext in video_extensions:
-            artifact = VideoArtifact(id=media_id, url=output.url)
+            artifact = Video(id=media_id, url=output.url)
             media_type = "video"
         else:
             logger.error(f"Unsupported media type with extension '{ext}' for URL: {output.url}")

agno/tools/scrapegraph.py

@@ -3,6 +3,7 @@ from os import getenv
 from typing import Any, List, Optional
 
 from agno.tools import Toolkit
+from agno.utils.log import log_debug, log_error
 
 try:
     from scrapegraph_py import Client
@@ -23,11 +24,14 @@ class ScrapeGraphTools(Toolkit):
         enable_crawl: bool = False,
         enable_searchscraper: bool = False,
         enable_agentic_crawler: bool = False,
+        enable_scrape: bool = False,
+        render_heavy_js: bool = False,
         all: bool = False,
         **kwargs,
     ):
         self.api_key: Optional[str] = api_key or getenv("SGAI_API_KEY")
         self.client = Client(api_key=self.api_key)
+        self.render_heavy_js = render_heavy_js
 
         # Start with smartscraper by default
         # Only enable markdownify if smartscraper is False
@@ -45,6 +49,8 @@ class ScrapeGraphTools(Toolkit):
             tools.append(self.searchscraper)
         if enable_agentic_crawler or all:
             tools.append(self.agentic_crawler)
+        if enable_scrape or all:
+            tools.append(self.scrape)
 
         super().__init__(name="scrapegraph_tools", tools=tools, **kwargs)
 
@@ -57,10 +63,13 @@ class ScrapeGraphTools(Toolkit):
             The structured data extracted from the webpage
         """
         try:
+            log_debug(f"ScrapeGraph smartscraper request for URL: {url}")
             response = self.client.smartscraper(website_url=url, user_prompt=prompt)
             return json.dumps(response["result"])
         except Exception as e:
-            return json.dumps({"error": str(e)})
+            error_msg = f"Smartscraper failed: {str(e)}"
+            log_error(error_msg)
+            return f"Error: {error_msg}"
 
     def markdownify(self, url: str) -> str:
         """Convert a webpage to markdown format.
@@ -70,10 +79,13 @@ class ScrapeGraphTools(Toolkit):
             The markdown version of the webpage
         """
         try:
+            log_debug(f"ScrapeGraph markdownify request for URL: {url}")
             response = self.client.markdownify(website_url=url)
             return response["result"]
         except Exception as e:
-            return f"Error converting to markdown: {str(e)}"
+            error_msg = f"Markdownify failed: {str(e)}"
+            log_error(error_msg)
+            return f"Error: {error_msg}"
 
     def crawl(
         self,
@@ -100,10 +112,11 @@ class ScrapeGraphTools(Toolkit):
             The structured data extracted from the website
         """
         try:
+            log_debug(f"ScrapeGraph crawl request for URL: {url}")
             response = self.client.crawl(
                 url=url,
                 prompt=prompt,
-                schema=schema,
+                data_schema=schema,
                 cache_website=cache_website,
                 depth=depth,
                 max_pages=max_pages,
@@ -112,7 +125,9 @@ class ScrapeGraphTools(Toolkit):
             )
             return json.dumps(response, indent=2)
         except Exception as e:
-            return json.dumps({"error": str(e)})
+            error_msg = f"Crawl failed: {str(e)}"
+            log_error(error_msg)
+            return f"Error: {error_msg}"
 
     def agentic_crawler(
         self,
@@ -143,21 +158,7 @@ class ScrapeGraphTools(Toolkit):
             JSON string containing the scraping results, including request_id, status, and extracted data
         """
         try:
-            # Validate required parameters for AI extraction
-            if ai_extraction and not user_prompt:
-                return json.dumps({"error": "user_prompt is required when ai_extraction=True"})
-
-            # Validate URL format
-            if not url.strip():
-                return json.dumps({"error": "URL cannot be empty"})
-            if not (url.startswith("http://") or url.startswith("https://")):
-                return json.dumps({"error": "Invalid URL - must start with http:// or https://"})
-
-            # Validate steps
-            if not steps:
-                return json.dumps({"error": "Steps cannot be empty"})
-            if any(not step.strip() for step in steps):
-                return json.dumps({"error": "All steps must contain valid instructions"})
+            log_debug(f"ScrapeGraph agentic_crawler request for URL: {url}")
 
             # Prepare parameters for the API call
             params = {"url": url, "steps": steps, "use_session": use_session, "ai_extraction": ai_extraction}
@@ -170,26 +171,52 @@ class ScrapeGraphTools(Toolkit):
 
             # Call the agentic scraper API
             response = self.client.agenticscraper(**params)
-
             return json.dumps(response, indent=2)
 
         except Exception as e:
-            return json.dumps({"error": str(e)})
+            error_msg = f"Agentic crawler failed: {str(e)}"
+            log_error(error_msg)
+            return f"Error: {error_msg}"
 
-    def searchscraper(self, prompt: str) -> str:
+    def searchscraper(self, user_prompt: str) -> str:
         """Search the web and extract information from the web.
         Args:
-            prompt (str): Search query
+            user_prompt (str): Search query
         Returns:
             JSON of the search results
         """
         try:
-            response = self.client.searchscraper(user_prompt=prompt)
-            if hasattr(response, "result"):
-                return json.dumps(response.result)
-            elif isinstance(response, dict) and "result" in response:
-                return json.dumps(response["result"])
-            else:
-                return json.dumps(response)
+            log_debug(f"ScrapeGraph searchscraper request with prompt: {user_prompt}")
+            response = self.client.searchscraper(user_prompt=user_prompt)
+            return json.dumps(response["result"])
+        except Exception as e:
+            error_msg = f"Searchscraper failed: {str(e)}"
+            log_error(error_msg)
+            return f"Error: {error_msg}"
+
+    def scrape(
+        self,
+        website_url: str,
+        headers: Optional[dict] = None,
+    ) -> str:
+        """Get raw HTML content from a website using the ScrapeGraphAI scrape API.
+
+        Args:
+            website_url (str): The URL of the website to scrape
+            headers (Optional[dict]): Optional headers to send with the request
+
+        Returns:
+            JSON string containing the HTML content and metadata
+        """
+        try:
+            log_debug(f"ScrapeGraph scrape request for URL: {website_url}")
+            response = self.client.scrape(
+                website_url=website_url,
+                headers=headers,
+                render_heavy_js=self.render_heavy_js,
+            )
+            return json.dumps(response, indent=2)
         except Exception as e:
-            return json.dumps({"error": str(e)})
+            error_msg = f"Scrape failed: {str(e)}"
+            log_error(error_msg)
+            return f"Error: {error_msg}"

agno/tools/searxng.py

@@ -21,7 +21,7 @@ class Searxng(Toolkit):
         self.fixed_max_results = fixed_max_results
 
         tools: List[Any] = [
-            self.search,
+            self.search_web,
             self.image_search,
             self.it_search,
             self.map_search,
@@ -33,7 +33,7 @@ class Searxng(Toolkit):
 
         super().__init__(name="searxng", tools=tools, **kwargs)
 
-    def search(self, query: str, max_results: int = 5) -> str:
+    def search_web(self, query: str, max_results: int = 5) -> str:
         """Use this function to search the web.
 
         Args:

agno/tools/serper.py

@@ -44,7 +44,7 @@ class SerperTools(Toolkit):
 
         tools: List[Any] = []
         if all or enable_search:
-            tools.append(self.search)
+            tools.append(self.search_web)
         if all or enable_search_news:
             tools.append(self.search_news)
         if all or enable_search_scholar:
@@ -97,7 +97,7 @@ class SerperTools(Toolkit):
             log_error(f"Serper API error: {str(e)}")
             return {"success": False, "error": str(e)}
 
-    def search(
+    def search_web(
         self,
         query: str,
         num_results: Optional[int] = None,

agno/tools/slack.py

@@ -16,6 +16,7 @@ class SlackTools(Toolkit):
     def __init__(
         self,
         token: Optional[str] = None,
+        markdown: bool = True,
         enable_send_message: bool = True,
         enable_send_message_thread: bool = True,
         enable_list_channels: bool = True,
@@ -23,10 +24,22 @@ class SlackTools(Toolkit):
         all: bool = False,
         **kwargs,
     ):
+        """
+        Initialize the SlackTools class.
+        Args:
+            token: The Slack API token. Defaults to the SLACK_TOKEN environment variable.
+            markdown: Whether to enable Slack markdown formatting. Defaults to True.
+            enable_send_message: Whether to enable the send_message tool. Defaults to True.
+            enable_send_message_thread: Whether to enable the send_message_thread tool. Defaults to True.
+            enable_list_channels: Whether to enable the list_channels tool. Defaults to True.
+            enable_get_channel_history: Whether to enable the get_channel_history tool. Defaults to True.
+            all: Whether to enable all tools. Defaults to False.
+        """
         self.token: Optional[str] = token or getenv("SLACK_TOKEN")
         if self.token is None or self.token == "":
             raise ValueError("SLACK_TOKEN is not set")
         self.client = WebClient(token=self.token)
+        self.markdown = markdown
 
         tools: List[Any] = []
         if enable_send_message or all:
@@ -52,7 +65,7 @@ class SlackTools(Toolkit):
             str: A JSON string containing the response from the Slack API.
         """
         try:
-            response = self.client.chat_postMessage(channel=channel, text=text)
+            response = self.client.chat_postMessage(channel=channel, text=text, mrkdwn=self.markdown)
             return json.dumps(response.data)
         except SlackApiError as e:
             logger.error(f"Error sending message: {e}")
@@ -65,13 +78,15 @@ class SlackTools(Toolkit):
         Args:
             channel (str): The channel ID or name to send the message to.
             text (str): The text of the message to send.
-            thread_ts (ts): The thread to reply to
+            thread_ts (ts): The thread to reply to.
 
         Returns:
             str: A JSON string containing the response from the Slack API.
         """
         try:
-            response = self.client.chat_postMessage(channel=channel, text=text, thread_ts=thread_ts)
+            response = self.client.chat_postMessage(
+                channel=channel, text=text, thread_ts=thread_ts, mrkdwn=self.markdown
+            )
             return json.dumps(response.data)
         except SlackApiError as e:
             logger.error(f"Error sending message: {e}")

agno/tools/spider.py

@@ -42,7 +42,7 @@ class SpiderTools(Toolkit):
 
         tools: List[Any] = []
         if enable_search or all:
-            tools.append(self.search)
+            tools.append(self.search_web)
         if enable_scrape or all:
             tools.append(self.scrape)
         if enable_crawl or all:
@@ -50,7 +50,7 @@ class SpiderTools(Toolkit):
 
         super().__init__(name="spider", tools=tools, **kwargs)
 
-    def search(self, query: str, max_results: int = 5) -> str:
+    def search_web(self, query: str, max_results: int = 5) -> str:
         """Use this function to search the web.
         Args:
             query (str): The query to search the web with.