agno 0.1.2__py3-none-any.whl → 2.3.13__py3-none-any.whl

agno/tools/decorator.py

@@ -1,12 +1,55 @@
 from functools import update_wrapper, wraps
-from typing import Any, Callable, Optional, TypeVar, Union, overload
+from typing import Any, Callable, Dict, List, Optional, TypeVar, Union, overload
 
-from agno.tools.function import Function
+from agno.tools.function import Function, get_entrypoint_docstring
 from agno.utils.log import logger
 
 # Type variable for better type hints
 F = TypeVar("F", bound=Callable[..., Any])
-ToolConfig = TypeVar("ToolConfig", bound=dict[str, Any])
+ToolConfig = TypeVar("ToolConfig", bound=Dict[str, Any])
+
+
+def _is_async_function(func: Callable) -> bool:
+    """
+    Check if a function is async, even when wrapped by decorators like @staticmethod.
+
+    This function tries to detect async functions by:
+    1. Checking the function directly with inspect functions
+    2. Looking at the original function if it's wrapped
+    3. Checking the function's code object for async indicators
+    """
+    from inspect import iscoroutine, iscoroutinefunction
+
+    # First, try the standard inspect functions
+    if iscoroutinefunction(func) or iscoroutine(func):
+        return True
+
+    # If the function has a __wrapped__ attribute, check the original function
+    if hasattr(func, "__wrapped__"):
+        original_func = func.__wrapped__
+        if iscoroutinefunction(original_func) or iscoroutine(original_func):
+            return True
+
+    # Check if the function has CO_COROUTINE flag in its code object
+    try:
+        if hasattr(func, "__code__") and func.__code__.co_flags & 0x80:  # CO_COROUTINE flag
+            return True
+    except (AttributeError, TypeError):
+        pass
+
+    # For static methods, try to get the original function
+    try:
+        if hasattr(func, "__func__"):
+            original_func = func.__func__
+            if iscoroutinefunction(original_func) or iscoroutine(original_func):
+                return True
+            # Check the code object of the original function
+            if hasattr(original_func, "__code__") and original_func.__code__.co_flags & 0x80:
+                return True
+    except (AttributeError, TypeError):
+        pass
+
+    return False
 
 
 @overload
@@ -19,11 +62,20 @@ def tool(
     name: Optional[str] = None,
     description: Optional[str] = None,
     strict: Optional[bool] = None,
-    sanitize_arguments: Optional[bool] = None,
+    instructions: Optional[str] = None,
+    add_instructions: bool = True,
     show_result: Optional[bool] = None,
-    stop_after_call: Optional[bool] = None,
+    stop_after_tool_call: Optional[bool] = None,
+    requires_confirmation: Optional[bool] = None,
+    requires_user_input: Optional[bool] = None,
+    user_input_fields: Optional[List[str]] = None,
+    external_execution: Optional[bool] = None,
     pre_hook: Optional[Callable] = None,
     post_hook: Optional[Callable] = None,
+    tool_hooks: Optional[List[Callable]] = None,
+    cache_results: bool = False,
+    cache_dir: Optional[str] = None,
+    cache_ttl: int = 3600,
 ) -> Callable[[F], Function]: ...
 
 
@@ -38,11 +90,20 @@ def tool(*args, **kwargs) -> Union[Function, Callable[[F], Function]]:
         name: Optional[str] - Override for the function name
         description: Optional[str] - Override for the function description
         strict: Optional[bool] - Flag for strict parameter checking
-        sanitize_arguments: Optional[bool] - If True, arguments are sanitized before passing to function
+        instructions: Optional[str] - Instructions for using the tool
+        add_instructions: bool - If True, add instructions to the system message
         show_result: Optional[bool] - If True, shows the result after function call
-        stop_after_call: Optional[bool] - If True, the agent will stop after the function call.
+        stop_after_tool_call: Optional[bool] - If True, the agent will stop after the function call.
+        requires_confirmation: Optional[bool] - If True, the function will require user confirmation before execution
+        requires_user_input: Optional[bool] - If True, the function will require user input before execution
+        user_input_fields: Optional[List[str]] - List of fields that will be provided to the function as user input
+        external_execution: Optional[bool] - If True, the function will be executed outside of the agent's context
         pre_hook: Optional[Callable] - Hook that runs before the function is executed.
         post_hook: Optional[Callable] - Hook that runs after the function is executed.
+        tool_hooks: Optional[List[Callable]] - List of hooks that run before and after the function is executed.
+        cache_results: bool - If True, enable caching of function results
+        cache_dir: Optional[str] - Directory to store cache files
+        cache_ttl: int - Time-to-live for cached results in seconds
 
     Returns:
         Union[Function, Callable[[F], Function]]: Decorated function or decorator
@@ -55,6 +116,10 @@ def tool(*args, **kwargs) -> Union[Function, Callable[[F], Function]]:
         @tool(name="custom_name", description="Custom description")
         def another_function():
             pass
+
+        @tool
+        async def my_async_function():
+            pass
     """
     # Move valid kwargs to a frozen set at module level
     VALID_KWARGS = frozenset(
@@ -62,11 +127,20 @@ def tool(*args, **kwargs) -> Union[Function, Callable[[F], Function]]:
             "name",
             "description",
             "strict",
-            "sanitize_arguments",
+            "instructions",
+            "add_instructions",
             "show_result",
-            "stop_after_call",
+            "stop_after_tool_call",
+            "requires_confirmation",
+            "requires_user_input",
+            "user_input_fields",
+            "external_execution",
             "pre_hook",
             "post_hook",
+            "tool_hooks",
+            "cache_results",
+            "cache_dir",
+            "cache_ttl",
         }
     )
 
@@ -77,28 +151,109 @@ def tool(*args, **kwargs) -> Union[Function, Callable[[F], Function]]:
             f"Invalid tool configuration arguments: {invalid_kwargs}. Valid arguments are: {sorted(VALID_KWARGS)}"
         )
 
+    # Check that only one of requires_user_input, requires_confirmation, and external_execution is set at the same time
+    exclusive_flags = [
+        kwargs.get("requires_user_input", False),
+        kwargs.get("requires_confirmation", False),
+        kwargs.get("external_execution", False),
+    ]
+    true_flags_count = sum(1 for flag in exclusive_flags if flag)
+
+    if true_flags_count > 1:
+        raise ValueError(
+            "Only one of 'requires_user_input', 'requires_confirmation', or 'external_execution' can be set to True at the same time."
+        )
+
     def decorator(func: F) -> Function:
+        from inspect import isasyncgenfunction
+
         @wraps(func)
-        def wrapper(*args: Any, **kwargs: Any) -> Any:
+        def sync_wrapper(*args: Any, **kwargs: Any) -> Any:
             try:
                 return func(*args, **kwargs)
             except Exception as e:
                 logger.error(
                     f"Error in tool {func.__name__!r}: {e!r}",
-                    exc_info=True,  # Include stack trace
+                    exc_info=True,
                 )
                 raise
 
-        # Preserve the original signature
+        @wraps(func)
+        async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
+            try:
+                return await func(*args, **kwargs)
+            except Exception as e:
+                logger.error(
+                    f"Error in async tool {func.__name__!r}: {e!r}",
+                    exc_info=True,
+                )
+                raise
+
+        @wraps(func)
+        async def async_gen_wrapper(*args: Any, **kwargs: Any) -> Any:
+            try:
+                return func(*args, **kwargs)
+            except Exception as e:
+                logger.error(
+                    f"Error in async generator tool {func.__name__!r}: {e!r}",
+                    exc_info=True,
+                )
+                raise
+
+        # Choose appropriate wrapper based on function type
+        if isasyncgenfunction(func):
+            wrapper = async_gen_wrapper
+        elif _is_async_function(func):
+            wrapper = async_wrapper
+        else:
+            wrapper = sync_wrapper
+
+        # Preserve the original signature and metadata
         update_wrapper(wrapper, func)
 
+        if kwargs.get("requires_user_input", True):
+            kwargs["user_input_fields"] = kwargs.get("user_input_fields", [])
+
+        if kwargs.get("user_input_fields"):
+            kwargs["requires_user_input"] = True
+
         # Create Function instance with any provided kwargs
         tool_config = {
             "name": kwargs.get("name", func.__name__),
+            "description": kwargs.get(
+                "description", get_entrypoint_docstring(wrapper)
+            ),  # Get docstring if description not provided
+            "instructions": kwargs.get("instructions"),
+            "add_instructions": kwargs.get("add_instructions", True),
             "entrypoint": wrapper,
-            **{k: v for k, v in kwargs.items() if k != "name" and v is not None},
+            "cache_results": kwargs.get("cache_results", False),
+            "cache_dir": kwargs.get("cache_dir"),
+            "cache_ttl": kwargs.get("cache_ttl", 3600),
+            **{
+                k: v
+                for k, v in kwargs.items()
+                if k
+                not in [
+                    "name",
+                    "description",
+                    "instructions",
+                    "add_instructions",
+                    "cache_results",
+                    "cache_dir",
+                    "cache_ttl",
+                ]
+                and v is not None
+            },
         }
-        return Function(**tool_config)
+
+        # Automatically set show_result=True if stop_after_tool_call=True (unless explicitly set to False)
+        if kwargs.get("stop_after_tool_call") is True:
+            if "show_result" not in kwargs or kwargs.get("show_result") is None:
+                tool_config["show_result"] = True
+        function = Function(**tool_config)
+        # Determine parameters for the function
+        function.process_entrypoint()
+        return function
 
     # Handle both @tool and @tool() cases
     if len(args) == 1 and callable(args[0]) and not kwargs:

agno/tools/desi_vocal.py

@@ -1,12 +1,14 @@
 from os import getenv
-from typing import Optional
+from typing import Any, List, Optional, Union
 from uuid import uuid4
 
 import requests
 
 from agno.agent import Agent
-from agno.media import AudioArtifact
+from agno.media import Audio
+from agno.team.team import Team
 from agno.tools import Toolkit
+from agno.tools.function import ToolResult
 from agno.utils.log import logger
 
 
@@ -15,17 +17,24 @@ class DesiVocalTools(Toolkit):
         self,
         api_key: Optional[str] = None,
         voice_id: Optional[str] = "f27d74e5-ea71-4697-be3e-f04bbd80c1a8",
+        enable_get_voices: bool = True,
+        enable_text_to_speech: bool = True,
+        all: bool = False,
+        **kwargs,
     ):
-        super().__init__(name="desi_vocal_tools")
-
         self.api_key = api_key or getenv("DESI_VOCAL_API_KEY")
         if not self.api_key:
             logger.error("DESI_VOCAL_API_KEY not set. Please set the DESI_VOCAL_API_KEY environment variable.")
 
         self.voice_id = voice_id
 
-        self.register(self.get_voices)
-        self.register(self.text_to_speech)
+        tools: List[Any] = []
+        if all or enable_get_voices:
+            tools.append(self.get_voices)
+        if all or enable_text_to_speech:
+            tools.append(self.text_to_speech)
+
+        super().__init__(name="desi_vocal_tools", tools=tools, **kwargs)
 
     def get_voices(self) -> str:
         """
@@ -60,13 +69,13 @@ class DesiVocalTools(Toolkit):
             logger.error(f"Failed to get voices: {e}")
             return f"Error: {e}"
 
-    def text_to_speech(self, agent: Agent, prompt: str, voice_id: Optional[str] = None) -> str:
+    def text_to_speech(self, agent: Union[Agent, Team], prompt: str, voice_id: Optional[str] = None) -> ToolResult:
         """
         Use this function to generate audio from text.
         Args:
             prompt (str): The text to generate audio from.
         Returns:
-            result (str): The URL of the generated audio.
+            ToolResult: A ToolResult containing the generated audio or error message.
         """
         try:
             url = "https://prod-api2.desivocal.com/dv/api/v0/tts_api/generate"
@@ -88,9 +97,12 @@ class DesiVocalTools(Toolkit):
             response_json = response.json()
             audio_url = response_json["s3_path"]
 
-            agent.add_audio(AudioArtifact(id=str(uuid4()), url=audio_url))
+            audio_artifact = Audio(id=str(uuid4()), url=audio_url)
 
-            return audio_url
+            return ToolResult(
+                content=f"Audio generated successfully: {audio_url}",
+                audios=[audio_artifact],
+            )
         except Exception as e:
             logger.error(f"Failed to generate audio: {e}")
-            return f"Error: {e}"
+            return ToolResult(content=f"Error: {e}")

agno/tools/discord.py

@@ -2,7 +2,7 @@
 
 import json
 from os import getenv
-from typing import Any, Dict, Optional
+from typing import Any, Dict, List, Optional
 
 import requests
 
@@ -14,14 +14,14 @@ class DiscordTools(Toolkit):
     def __init__(
         self,
         bot_token: Optional[str] = None,
-        enable_messaging: bool = True,
-        enable_history: bool = True,
-        enable_channel_management: bool = True,
-        enable_message_management: bool = True,
+        enable_send_message: bool = True,
+        enable_get_channel_messages: bool = True,
+        enable_get_channel_info: bool = True,
+        enable_list_channels: bool = True,
+        enable_delete_message: bool = True,
+        all: bool = False,
+        **kwargs,
     ):
-        """Initialize Discord tools."""
-        super().__init__(name="discord")
-
         self.bot_token = bot_token or getenv("DISCORD_BOT_TOKEN")
         if not self.bot_token:
             logger.error("Discord bot token is required")
@@ -33,16 +33,19 @@ class DiscordTools(Toolkit):
             "Content-Type": "application/json",
         }
 
-        # Register tools based on enabled features
-        if enable_messaging:
-            self.register(self.send_message)
-        if enable_history:
-            self.register(self.get_channel_messages)
-        if enable_channel_management:
-            self.register(self.get_channel_info)
-            self.register(self.list_channels)
-        if enable_message_management:
-            self.register(self.delete_message)
+        tools: List[Any] = []
+        if enable_send_message or all:
+            tools.append(self.send_message)
+        if enable_get_channel_messages or all:
+            tools.append(self.get_channel_messages)
+        if enable_get_channel_info or all:
+            tools.append(self.get_channel_info)
+        if enable_list_channels or all:
+            tools.append(self.list_channels)
+        if enable_delete_message or all:
+            tools.append(self.delete_message)
+
+        super().__init__(name="discord", tools=tools, **kwargs)
 
     def _make_request(self, method: str, endpoint: str, data: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
         """Make a request to Discord API."""
@@ -51,12 +54,12 @@ class DiscordTools(Toolkit):
         response.raise_for_status()
         return response.json() if response.text else {}
 
-    def send_message(self, channel_id: int, message: str) -> str:
+    def send_message(self, channel_id: str, message: str) -> str:
         """
         Send a message to a Discord channel.
 
         Args:
-            channel_id (int): The ID of the channel to send the message to.
+            channel_id (str): The ID of the channel to send the message to.
             message (str): The text of the message to send.
 
         Returns:
@@ -70,12 +73,12 @@ class DiscordTools(Toolkit):
             logger.error(f"Error sending message: {e}")
             return f"Error sending message: {str(e)}"
 
-    def get_channel_info(self, channel_id: int) -> str:
+    def get_channel_info(self, channel_id: str) -> str:
         """
         Get information about a Discord channel.
 
         Args:
-            channel_id (int): The ID of the channel to get information about.
+            channel_id (str): The ID of the channel to get information about.
 
         Returns:
             str: A JSON string containing the channel information.
@@ -87,12 +90,12 @@ class DiscordTools(Toolkit):
             logger.error(f"Error getting channel info: {e}")
             return f"Error getting channel info: {str(e)}"
 
-    def list_channels(self, guild_id: int) -> str:
+    def list_channels(self, guild_id: str) -> str:
         """
         List all channels in a Discord server.
 
         Args:
-            guild_id (int): The ID of the server to list channels from.
+            guild_id (str): The ID of the server to list channels from.
 
         Returns:
             str: A JSON string containing the list of channels.
@@ -104,12 +107,12 @@ class DiscordTools(Toolkit):
             logger.error(f"Error listing channels: {e}")
             return f"Error listing channels: {str(e)}"
 
-    def get_channel_messages(self, channel_id: int, limit: int = 100) -> str:
+    def get_channel_messages(self, channel_id: str, limit: int = 100) -> str:
         """
         Get the message history of a Discord channel.
 
         Args:
-            channel_id (int): The ID of the channel to fetch messages from.
+            channel_id (str): The ID of the channel to fetch messages from.
             limit (int): The maximum number of messages to fetch. Defaults to 100.
 
         Returns:
@@ -122,13 +125,13 @@ class DiscordTools(Toolkit):
             logger.error(f"Error getting messages: {e}")
             return f"Error getting messages: {str(e)}"
 
-    def delete_message(self, channel_id: int, message_id: int) -> str:
+    def delete_message(self, channel_id: str, message_id: str) -> str:
         """
         Delete a message from a Discord channel.
 
         Args:
-            channel_id (int): The ID of the channel containing the message.
-            message_id (int): The ID of the message to delete.
+            channel_id (str): The ID of the channel containing the message.
+            message_id (str): The ID of the message to delete.
 
         Returns:
             str: A success message or error message.