agno 2.2.13__py3-none-any.whl

agno/tools/__init__.py

@@ -0,0 +1,10 @@
+from agno.tools.decorator import tool
+from agno.tools.function import Function, FunctionCall
+from agno.tools.toolkit import Toolkit
+
+__all__ = [
+    "tool",
+    "Function",
+    "FunctionCall",
+    "Toolkit",
+]

agno/tools/agentql.py

@@ -0,0 +1,120 @@
+from os import getenv
+from typing import Any, List, Optional
+
+from agno.tools import Toolkit
+from agno.utils.log import log_info
+
+try:
+    import agentql
+    from playwright.sync_api import sync_playwright
+except ImportError:
+    raise ImportError("`agentql` not installed. Please install using `pip install agentql`")
+
+
+class AgentQLTools(Toolkit):
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        enable_scrape_website: bool = True,
+        enable_custom_scrape_website: bool = False,
+        all: bool = False,
+        agentql_query: str = "",
+        **kwargs,
+    ):
+        self.api_key = api_key or getenv("AGENTQL_API_KEY")
+        if not self.api_key:
+            raise ValueError("AGENTQL_API_KEY not set. Please set the AGENTQL_API_KEY environment variable.")
+
+        self.agentql_query = agentql_query
+
+        tools: List[Any] = []
+        if all or enable_scrape_website:
+            tools.append(self.scrape_website)
+        if all or enable_custom_scrape_website or (agentql_query and not all and not enable_custom_scrape_website):
+            if agentql_query:
+                log_info("Custom AgentQL query provided. Registering custom scrape function.")
+                tools.append(self.custom_scrape_website)
+
+        super().__init__(name="agentql_tools", tools=tools, **kwargs)
+
+    def scrape_website(self, url: str) -> str:
+        """
+        Scrape all text content from a website using AgentQL.
+
+        Args:
+            url (str): The URL of the website to scrape
+
+        Returns:
+            str: Extracted text content or error message
+        """
+        if not url:
+            return "No URL provided"
+
+        TEXT_SEARCH_QUERY = """
+        {
+            text_content[]
+        }
+        """
+
+        try:
+            with sync_playwright() as playwright, playwright.chromium.launch(headless=False) as browser:
+                page = agentql.wrap(browser.new_page())
+                page.goto(url)
+
+                try:
+                    # Get response from AgentQL query
+                    response = page.query_data(TEXT_SEARCH_QUERY)
+
+                    # Extract text based on response format
+                    if isinstance(response, dict) and "text_content" in response:
+                        text_items = [item for item in response["text_content"] if item and item.strip()]
+
+                        deduplicated = list(set(text_items))
+                        return " ".join(deduplicated)
+
+                except Exception as e:
+                    return f"Error extracting text: {e}"
+        except Exception as e:
+            return f"Error launching browser: {e}"
+
+        return "No text content found"
+
+    def custom_scrape_website(self, url: str) -> str:
+        """
+        Scrape a website using a custom AgentQL query.
+
+        Args:
+            url (str): The URL of the website to scrape
+
+        Returns:
+            str: Extracted text content or error message
+        """
+        if not url:
+            return "No URL provided"
+
+        if self.agentql_query == "":
+            return "Custom AgentQL query not provided. Please provide a custom AgentQL query."
+
+        try:
+            with sync_playwright() as playwright, playwright.chromium.launch(headless=False) as browser:
+                page = agentql.wrap(browser.new_page())
+                page.goto(url)
+
+                try:
+                    # Get response from AgentQL query
+                    response = page.query_data(self.agentql_query)
+
+                    # Extract text based on response format
+                    if isinstance(response, dict):
+                        items = [item for item in response]
+                        text_items = [text_item for text_item in items if text_item]
+
+                        deduplicated = list(set(text_items))
+                        return " ".join(deduplicated)
+
+                except Exception as e:
+                    return f"Error extracting text: {e}"
+        except Exception as e:
+            return f"Error launching browser: {e}"
+
+        return "No text content found"

agno/tools/airflow.py

@@ -0,0 +1,69 @@
+from pathlib import Path
+from typing import Any, List, Optional, Union
+
+from agno.tools import Toolkit
+from agno.utils.log import log_debug, log_info, logger
+
+
+class AirflowTools(Toolkit):
+    def __init__(
+        self,
+        dags_dir: Optional[Union[Path, str]] = None,
+        enable_save_dag_file: bool = True,
+        enable_read_dag_file: bool = True,
+        all: bool = False,
+        **kwargs,
+    ):
+        """
+        quick start to work with airflow : https://airflow.apache.org/docs/apache-airflow/stable/start.html
+        """
+
+        _dags_dir: Optional[Path] = None
+        if dags_dir is not None:
+            if isinstance(dags_dir, str):
+                _dags_dir = Path.cwd().joinpath(dags_dir)
+            else:
+                _dags_dir = dags_dir
+        self.dags_dir: Path = _dags_dir or Path.cwd()
+
+        tools: List[Any] = []
+        if all or enable_save_dag_file:
+            tools.append(self.save_dag_file)
+        if all or enable_read_dag_file:
+            tools.append(self.read_dag_file)
+
+        super().__init__(name="AirflowTools", tools=tools, **kwargs)
+
+    def save_dag_file(self, contents: str, dag_file: str) -> str:
+        """Saves python code for an Airflow DAG to a file called `dag_file` and returns the file path if successful.
+
+        :param contents: The contents of the DAG.
+        :param dag_file: The name of the file to save to.
+        :return: The file path if successful, otherwise returns an error message.
+        """
+        try:
+            file_path = self.dags_dir.joinpath(dag_file)
+            log_debug(f"Saving contents to {file_path}")
+            if not file_path.parent.exists():
+                file_path.parent.mkdir(parents=True, exist_ok=True)
+            file_path.write_text(contents)
+            log_info(f"Saved: {file_path}")
+            return str(file_path)
+        except Exception as e:
+            logger.error(f"Error saving to file: {e}")
+            return f"Error saving to file: {e}"
+
+    def read_dag_file(self, dag_file: str) -> str:
+        """Reads an Airflow DAG file `dag_file` and returns the contents if successful.
+
+        :param dag_file: The name of the file to read
+        :return: The contents of the file if successful, otherwise returns an error message.
+        """
+        try:
+            log_info(f"Reading file: {dag_file}")
+            file_path = self.dags_dir.joinpath(dag_file)
+            contents = file_path.read_text()
+            return str(contents)
+        except Exception as e:
+            logger.error(f"Error reading file: {e}")
+            return f"Error reading file: {e}"

agno/tools/api.py

@@ -0,0 +1,122 @@
+import json
+from typing import Any, Dict, List, Literal, Optional
+
+from agno.tools import Toolkit
+from agno.utils.log import log_debug, logger
+
+try:
+    import requests
+    from requests.auth import HTTPBasicAuth
+except ImportError:
+    raise ImportError("`requests` not installed. Please install using `pip install requests`")
+
+
+class CustomApiTools(Toolkit):
+    def __init__(
+        self,
+        base_url: Optional[str] = None,
+        username: Optional[str] = None,
+        password: Optional[str] = None,
+        api_key: Optional[str] = None,
+        headers: Optional[Dict[str, str]] = None,
+        verify_ssl: bool = True,
+        timeout: int = 30,
+        enable_make_request: bool = True,
+        all: bool = False,
+        **kwargs,
+    ):
+        self.base_url = base_url
+        self.username = username
+        self.password = password
+        self.api_key = api_key
+        self.default_headers = headers or {}
+        self.verify_ssl = verify_ssl
+        self.timeout = timeout
+
+        tools: List[Any] = []
+        if all or enable_make_request:
+            tools.append(self.make_request)
+
+        super().__init__(name="api_tools", tools=tools, **kwargs)
+
+    def _get_auth(self) -> Optional[HTTPBasicAuth]:
+        """Get authentication object if credentials are provided."""
+        if self.username and self.password:
+            return HTTPBasicAuth(self.username, self.password)
+        return None
+
+    def _get_headers(self, additional_headers: Optional[Dict[str, str]] = None) -> Dict[str, str]:
+        """Combine default headers with additional headers."""
+        headers = self.default_headers.copy()
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        if additional_headers:
+            headers.update(additional_headers)
+        return headers
+
+    def make_request(
+        self,
+        endpoint: str,
+        method: Literal["GET", "POST", "PUT", "DELETE", "PATCH"] = "GET",
+        params: Optional[Dict[str, Any]] = None,
+        data: Optional[Dict[str, Any]] = None,
+        headers: Optional[Dict[str, str]] = None,
+        json_data: Optional[Dict[str, Any]] = None,
+    ) -> str:
+        """Make an HTTP request to the API.
+
+        Args:
+            method (str): HTTP method (GET, POST, PUT, DELETE, PATCH)
+            endpoint (str): API endpoint (will be combined with base_url if set)
+            params (Optional[Dict[str, Any]]): Query parameters
+            data (Optional[Dict[str, Any]]): Form data to send
+            headers (Optional[Dict[str, str]]): Additional headers
+            json_data (Optional[Dict[str, Any]]): JSON data to send
+
+        Returns:
+            str: JSON string containing response data or error message
+        """
+        try:
+            if self.base_url:
+                url = f"{self.base_url.rstrip('/')}/{endpoint.lstrip('/')}"
+            else:
+                url = endpoint
+            log_debug(f"Making {method} request to {url}")
+
+            response = requests.request(
+                method=method,
+                url=url,
+                params=params,
+                data=data,
+                json=json_data,
+                headers=self._get_headers(headers),
+                auth=self._get_auth(),
+                verify=self.verify_ssl,
+                timeout=self.timeout,
+            )
+
+            try:
+                response_data = response.json()
+            except json.JSONDecodeError:
+                response_data = {"text": response.text}
+
+            result = {
+                "status_code": response.status_code,
+                "headers": dict(response.headers),
+                "data": response_data,
+            }
+
+            if not response.ok:
+                logger.error(f"Request failed with status {response.status_code}: {response.text}")
+                result["error"] = "Request failed"
+
+            return json.dumps(result, indent=2)
+
+        except requests.exceptions.RequestException as e:
+            error_message = f"Request failed: {str(e)}"
+            logger.error(error_message)
+            return json.dumps({"error": error_message}, indent=2)
+        except Exception as e:
+            error_message = f"Unexpected error: {str(e)}"
+            logger.error(error_message)
+            return json.dumps({"error": error_message}, indent=2)

agno/tools/apify.py

@@ -0,0 +1,314 @@
+import json
+import string
+from os import getenv
+from typing import Any, Dict, List, Optional, Tuple, Union
+
+import requests
+
+from agno.tools import Toolkit
+from agno.utils.log import log_info, logger
+
+try:
+    from apify_client import ApifyClient
+except ImportError:
+    raise ImportError("`apify-client` not installed. Please install using `pip install apify-client`")
+
+
+class ApifyTools(Toolkit):
+    def __init__(self, actors: Optional[Union[str, List[str]]] = None, apify_api_token: Optional[str] = None):
+        """Initialize ApifyTools with specific Actors.
+
+        Args:
+            actors (Optional[Union[str, List[str]]]): Single Actor ID as string or list of Actor IDs to register as individual tools
+            apify_api_token (Optional[str]): Apify API token (defaults to APIFY_API_TOKEN env variable)
+        """
+        # Get API token from args or environment
+        self.apify_api_token = apify_api_token or getenv("APIFY_API_TOKEN")
+        if not self.apify_api_token:
+            raise ValueError("APIFY_API_TOKEN environment variable or apify_api_token parameter must be set")
+
+        self.client = create_apify_client(self.apify_api_token)
+
+        tools: List[Any] = []
+        if actors:
+            actor_list = [actors] if isinstance(actors, str) else actors
+            for actor_id in actor_list:
+                tools.append(actor_id)
+
+        super().__init__(name="ApifyTools", tools=[], auto_register=False)
+
+        for actor_id in tools:
+            self.register_actor(actor_id)
+
+    def register_actor(self, actor_id: str) -> None:
+        """Register an Apify Actor as a function in the toolkit.
+
+        Args:
+            actor_id (str): ID of the Apify Actor to register (e.g., 'apify/web-scraper')
+        """
+        try:
+            # Get actor metadata
+            build = get_actor_latest_build(self.client, actor_id)
+            tool_name = actor_id_to_tool_name(actor_id)
+
+            # Get actor description
+            actor_description = build.get("actorDefinition", {}).get("description", "")
+            if len(actor_description) > MAX_DESCRIPTION_LEN:
+                actor_description = actor_description[:MAX_DESCRIPTION_LEN] + "...(TRUNCATED, TOO LONG)"
+
+            # Get input schema
+            actor_input = build.get("actorDefinition", {}).get("input")
+            if not actor_input:
+                raise ValueError(f"Input schema not found in the Actor build for Actor: {actor_id}")
+
+            properties, required = prune_actor_input_schema(actor_input)
+
+            # Create a wrapper function that calls the Actor
+            def actor_function(**kwargs) -> str:
+                """Actor function wrapper."""
+                try:
+                    # Params are nested under 'kwargs' key
+                    if len(kwargs) == 1 and "kwargs" in kwargs:
+                        kwargs = kwargs["kwargs"]
+
+                    log_info(f"Running Apify Actor {actor_id} with parameters: {kwargs}")
+
+                    # Run the Actor directly with the client
+                    details = self.client.actor(actor_id=actor_id).call(run_input=kwargs)
+                    if details is None:
+                        error_msg = (
+                            f"Actor: {actor_id} was not started properly and details about the run were not returned"
+                        )
+                        raise ValueError(error_msg)
+
+                    run_id = details.get("id")
+                    if run_id is None:
+                        error_msg = f"Run ID not found in the run details for Actor: {actor_id}"
+                        raise ValueError(error_msg)
+
+                    # Get the results
+                    run = self.client.run(run_id=run_id)
+                    results = run.dataset().list_items(clean=True).items
+
+                    return json.dumps(results)
+
+                except Exception as e:
+                    error_msg = f"Error running Apify Actor {actor_id}: {str(e)}"
+                    logger.error(error_msg)
+                    return json.dumps([{"error": error_msg}])
+
+            docstring = f"{actor_description}\n\nArgs:\n"
+
+            for param_name, param_info in properties.items():
+                param_type = param_info.get("type", "any")
+                param_desc = param_info.get("description", "No description available")
+                required_marker = "(required)" if param_name in required else "(optional)"
+                docstring += f"    {param_name} ({param_type}): {required_marker} {param_desc}\n"
+
+            docstring += """
+Returns:
+    str: JSON string containing the Actor's output dataset
+"""
+
+            # Update function metadata
+            actor_function.__name__ = tool_name
+            actor_function.__doc__ = docstring
+
+            # Register the function with the toolkit
+            self.register(actor_function)
+            # Fix params schema
+            self.functions[tool_name].parameters = props_to_json_schema(properties, required)
+            log_info(f"Registered Apify Actor '{actor_id}' as function '{tool_name}'")
+
+        except Exception as e:
+            logger.error(f"Failed to register Apify Actor '{actor_id}': {str(e)}")
+
+
+# Constants
+MAX_DESCRIPTION_LEN = 350
+REQUESTS_TIMEOUT_SECS = 300
+APIFY_API_ENDPOINT_GET_DEFAULT_BUILD = "https://api.apify.com/v2/acts/{actor_id}/builds/default"
+
+
+# Utility functions
+def props_to_json_schema(input_dict, required_fields=None):
+    schema: Dict[str, Any] = {"type": "object", "properties": {}, "required": required_fields or []}
+
+    def infer_array_item_type(prop):
+        type_map = {
+            "string": "string",
+            "int": "number",
+            "float": "number",
+            "dict": "object",
+            "list": "array",
+            "bool": "boolean",
+            "none": "null",
+        }
+        if prop.get("items", {}).get("type"):
+            return prop["items"]["type"]
+        if "prefill" in prop and prop["prefill"] and len(prop["prefill"]) > 0:
+            return type_map.get(type(prop["prefill"][0]).__name__.lower(), "string")
+        if "default" in prop and prop["default"] and len(prop["default"]) > 0:
+            return type_map.get(type(prop["default"][0]).__name__.lower(), "string")
+        return "string"  # Fallback for arrays like searchStringsArray
+
+    for key, value in input_dict.items():
+        prop_schema: Dict[str, Any] = {}
+        prop_type = value.get("type")
+
+        if "enum" in value:
+            prop_schema["enum"] = value["enum"]
+
+        if "default" in value:
+            prop_schema["default"] = value["default"]
+        elif "prefill" in value:
+            prop_schema["default"] = value["prefill"]
+
+        if "description" in value:
+            prop_schema["description"] = value["description"]
+
+        # Handle Apify special types first
+        if prop_type == "object" and value.get("editor") == "proxy":
+            prop_schema["type"] = "object"
+            prop_schema["properties"] = {
+                "useApifyProxy": {
+                    "title": "Use Apify Proxy",
+                    "type": "boolean",
+                    "description": "Whether to use Apify Proxy - ALWAYS SET TO TRUE.",
+                    "default": True,
+                    "examples": [True],
+                }
+            }
+            prop_schema["required"] = ["useApifyProxy"]
+            if "default" in value:
+                prop_schema["default"] = value["default"]
+
+        elif prop_type == "array" and value.get("editor") == "requestListSources":
+            prop_schema["type"] = "array"
+            prop_schema["items"] = {
+                "type": "object",
+                "title": "Request list source",
+                "description": "Request list source",
+                "properties": {
+                    "url": {"title": "URL", "type": "string", "description": "URL of the request list source"}
+                },
+            }
+
+        elif prop_type == "array":
+            prop_schema["type"] = "array"
+            prop_schema["items"] = {
+                "type": infer_array_item_type(value),
+                "title": value.get("title", "Item"),
+                "description": "Item",
+            }
+
+        elif prop_type == "object":
+            prop_schema["type"] = "object"
+            if "default" in value:
+                prop_schema["default"] = value["default"]
+                prop_schema["properties"] = {}
+                for k, v in value.get("properties", value["default"]).items():
+                    prop_type = v["type"] if isinstance(v, dict) else type(v).__name__.lower()
+                    if prop_type == "bool":
+                        prop_type = "boolean"
+                    prop_schema["properties"][k] = {"type": prop_type}
+
+        else:
+            prop_schema["type"] = prop_type
+
+        schema["properties"][key] = prop_schema
+
+    return schema
+
+
+def create_apify_client(token: str) -> ApifyClient:
+    """Create an Apify client instance with a custom user-agent.
+
+    Args:
+        token (str): API token
+
+    Returns:
+        ApifyClient: Apify client instance
+
+    Raises:
+        ValueError: If the API token is not provided
+    """
+    if not token:
+        raise ValueError("API token is required to create an Apify client.")
+
+    client = ApifyClient(token)
+    if http_client := getattr(client.http_client, "httpx_client", None):
+        http_client.headers["user-agent"] += "; Origin/agno"
+    return client
+
+
+def actor_id_to_tool_name(actor_id: str) -> str:
+    """Turn actor_id into a valid tool name.
+
+    Args:
+        actor_id (str): Actor ID from Apify store
+
+    Returns:
+        str: A valid tool name
+    """
+    valid_chars = string.ascii_letters + string.digits + "_-"
+    return "apify_actor_" + "".join(char if char in valid_chars else "_" for char in actor_id)
+
+
+def get_actor_latest_build(apify_client: ApifyClient, actor_id: str) -> Dict[str, Any]:
+    """Get the latest build of an Actor from the default build tag.
+
+    Args:
+        apify_client (ApifyClient): An instance of the ApifyClient class
+        actor_id (str): Actor name from Apify store to run
+
+    Returns:
+        Dict[str, Any]: The latest build of the Actor
+
+    Raises:
+        ValueError: If the Actor is not found or the build data is not found
+        TypeError: If the build is not a dictionary
+    """
+    if not (actor := apify_client.actor(actor_id).get()):
+        raise ValueError(f"Actor {actor_id} not found.")
+
+    if not (actor_obj_id := actor.get("id")):
+        raise ValueError(f"Failed to get the Actor object ID for {actor_id}.")
+
+    url = APIFY_API_ENDPOINT_GET_DEFAULT_BUILD.format(actor_id=actor_obj_id)
+    response = requests.request("GET", url, timeout=REQUESTS_TIMEOUT_SECS)
+
+    build = response.json()
+    if not isinstance(build, dict):
+        raise TypeError(f"Failed to get the latest build of the Actor {actor_id}.")
+
+    if (data := build.get("data")) is None:
+        raise ValueError(f"Failed to get the latest build data of the Actor {actor_id}.")
+
+    return data
+
+
+def prune_actor_input_schema(input_schema: Dict[str, Any]) -> Tuple[Dict[str, Any], List[str]]:
+    """Get the input schema from the Actor build and trim descriptions.
+
+    Args:
+        input_schema (Dict[str, Any]): The input schema from the Actor build
+
+    Returns:
+        Tuple[Dict[str, Any], List[str]]: A tuple containing the pruned properties and required fields
+    """
+    properties = input_schema.get("properties", {})
+    required = input_schema.get("required", [])
+
+    properties_out: Dict[str, Any] = {}
+    for item, meta in properties.items():
+        properties_out[item] = {}
+        if desc := meta.get("description"):
+            properties_out[item]["description"] = (
+                desc[:MAX_DESCRIPTION_LEN] + "..." if len(desc) > MAX_DESCRIPTION_LEN else desc
+            )
+        for key_name in ("type", "default", "prefill", "enum"):
+            if value := meta.get(key_name):
+                properties_out[item][key_name] = value
+
+    return properties_out, required