agno 2.2.1__py3-none-any.whl → 2.2.3__py3-none-any.whl

agno/tools/dalle.py

@@ -1,10 +1,8 @@
 from os import getenv
-from typing import Any, List, Literal, Optional, Union
+from typing import Any, List, Literal, Optional
 from uuid import uuid4
 
-from agno.agent import Agent
 from agno.media import Image
-from agno.team.team import Team
 from agno.tools import Toolkit
 from agno.tools.function import ToolResult
 from agno.utils.log import log_debug, logger
@@ -64,7 +62,7 @@ class DalleTools(Toolkit):
         # - Add support for saving images
         # - Add support for editing images
 
-    def create_image(self, agent: Union[Agent, Team], prompt: str) -> ToolResult:
+    def create_image(self, prompt: str) -> ToolResult:
         """Use this function to generate an image for a prompt.
 
         Args:

agno/tools/eleven_labs.py

@@ -1,4 +1,3 @@
-from base64 import b64encode
 from io import BytesIO
 from os import getenv, path
 from pathlib import Path
@@ -10,7 +9,7 @@ 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
+from agno.utils.log import log_error, log_info
 
 try:
     from elevenlabs import ElevenLabs  # type: ignore
@@ -48,7 +47,7 @@ class ElevenLabsTools(Toolkit):
     ):
         self.api_key = api_key or getenv("ELEVEN_LABS_API_KEY")
         if not self.api_key:
-            logger.error("ELEVEN_LABS_API_KEY not set. Please set the ELEVEN_LABS_API_KEY environment variable.")
+            log_error("ELEVEN_LABS_API_KEY not set. Please set the ELEVEN_LABS_API_KEY environment variable.")
 
         self.target_directory = target_directory
         self.voice_id = voice_id
@@ -73,7 +72,7 @@ class ElevenLabsTools(Toolkit):
 
     def get_voices(self) -> str:
         """
-        Use this function to get all the voices available.
+        Get all the voices available.
 
         Returns:
             result (list): A list of voices that have an ID, name and description.
@@ -94,20 +93,19 @@ class ElevenLabsTools(Toolkit):
             return str(response)
 
         except Exception as e:
-            logger.error(f"Failed to fetch voices: {e}")
+            log_error(f"Failed to fetch voices: {e}")
             return f"Error: {e}"
 
-    def _process_audio(self, audio_generator: Iterator[bytes]) -> str:
-        # Step 1: Write audio data to BytesIO
+    def _process_audio(self, audio_generator: Iterator[bytes]) -> bytes:
         audio_bytes = BytesIO()
         for chunk in audio_generator:
             audio_bytes.write(chunk)
-        audio_bytes.seek(0)  # Rewind the stream
 
-        # Step 2: Encode as Base64
-        base64_audio = b64encode(audio_bytes.read()).decode("utf-8")
+        # Read bytes
+        audio_bytes.seek(0)
+        audio_data = audio_bytes.read()
 
-        # Step 3: Optionally save to disk if target_directory exists
+        # Save to disk if target_directory exists
         if self.target_directory:
             # Determine file extension based on output format
             if self.output_format.startswith("mp3"):
@@ -122,19 +120,19 @@ class ElevenLabsTools(Toolkit):
             output_filename = f"{uuid4()}.{extension}"
             output_path = path.join(self.target_directory, output_filename)
 
-            # Write from BytesIO to disk
-            audio_bytes.seek(0)  # Reset the BytesIO stream again
             with open(output_path, "wb") as f:
-                f.write(audio_bytes.read())
+                f.write(audio_data)
 
-        return base64_audio
+            log_info(f"Audio saved to: {output_path}")
+
+        return audio_data
 
     def generate_sound_effect(self, prompt: str, duration_seconds: Optional[float] = None) -> ToolResult:
         """
-        Use this function to generate sound effect audio from a text prompt.
+        Generate a sound effect from a text description.
 
         Args:
-            prompt (str): Text to generate audio from.
+            prompt (str): Description of the sound effect
             duration_seconds (Optional[float]): Duration in seconds to generate audio from. Has to be between 0.5 and 22.
         Returns:
             ToolResult: A ToolResult containing the generated audio or error message.
@@ -144,27 +142,27 @@ class ElevenLabsTools(Toolkit):
                 text=prompt, duration_seconds=duration_seconds
             )
 
-            base64_audio = self._process_audio(audio_generator)
+            audio_data = self._process_audio(audio_generator)
 
             # Create AudioArtifact
             audio_artifact = Audio(
                 id=str(uuid4()),
-                base64_audio=base64_audio,
+                content=audio_data,
                 mime_type="audio/mpeg",
             )
 
             return ToolResult(
-                content="Audio generated successfully",
+                content="Sound effect generated successfully",
                 audios=[audio_artifact],
             )
 
         except Exception as e:
-            logger.error(f"Failed to generate audio: {e}")
+            log_error(f"Failed to generate sound effect: {e}")
             return ToolResult(content=f"Error: {e}")
 
     def text_to_speech(self, agent: Union[Agent, Team], prompt: str) -> ToolResult:
         """
-        Use this function to convert text to speech audio.
+        Convert text to speech.
 
         Args:
             prompt (str): Text to generate audio from.
@@ -179,12 +177,12 @@ class ElevenLabsTools(Toolkit):
                 output_format=self.output_format,
             )
 
-            base64_audio = self._process_audio(audio_generator)
+            audio_data = self._process_audio(audio_generator)
 
             # Create AudioArtifact
             audio_artifact = Audio(
                 id=str(uuid4()),
-                base64_audio=base64_audio,
+                content=audio_data,
                 mime_type="audio/mpeg",
             )
 
@@ -194,5 +192,5 @@ class ElevenLabsTools(Toolkit):
             )
 
         except Exception as e:
-            logger.error(f"Failed to generate audio: {e}")
+            log_error(f"Failed to generate audio: {e}")
             return ToolResult(content=f"Error: {e}")

agno/tools/function.py

@@ -139,6 +139,46 @@ class Function(BaseModel):
             include={"name", "description", "parameters", "strict", "requires_confirmation", "external_execution"},
         )
 
+    def model_copy(self, *, deep: bool = False) -> "Function":
+        """
+        Override model_copy to handle callable fields that can't be deep copied (pickled).
+        Callables should always be shallow copied (referenced), not deep copied.
+        """
+        # For deep copy, we need to handle callable fields specially
+        if deep:
+            # Fields that should NOT be deep copied (callables and complex objects)
+            shallow_fields = {
+                "entrypoint",
+                "pre_hook",
+                "post_hook",
+                "tool_hooks",
+                "_agent",
+                "_team",
+            }
+
+            # Create a copy with shallow references to callable fields
+            copied_data = {}
+            for field_name, field_value in self.__dict__.items():
+                if field_name in shallow_fields:
+                    # Shallow copy - just reference the same object
+                    copied_data[field_name] = field_value
+                elif field_name == "parameters":
+                    # Deep copy the parameters dict
+                    from copy import deepcopy
+
+                    copied_data[field_name] = deepcopy(field_value)
+                else:
+                    # For simple types, just copy the value
+                    copied_data[field_name] = field_value
+
+            # Create new instance with copied data
+            new_instance = self.__class__.model_construct(**copied_data)
+
+            return new_instance
+        else:
+            # For shallow copy, use the default Pydantic behavior
+            return super().model_copy(deep=False)
+
     @classmethod
     def from_callable(cls, c: Callable, name: Optional[str] = None, strict: bool = False) -> "Function":
         from inspect import getdoc, signature

agno/tools/mcp/__init__.py

@@ -0,0 +1,10 @@
+from agno.tools.mcp.mcp import MCPTools
+from agno.tools.mcp.multi_mcp import MultiMCPTools
+from agno.tools.mcp.params import SSEClientParams, StreamableHTTPClientParams
+
+__all__ = [
+    "MCPTools",
+    "MultiMCPTools",
+    "StreamableHTTPClientParams",
+    "SSEClientParams",
+]

agno/tools/mcp/mcp.py

@@ -0,0 +1,324 @@
+import weakref
+from dataclasses import asdict
+from datetime import timedelta
+from typing import Any, Literal, Optional, Union
+
+from agno.tools import Toolkit
+from agno.tools.function import Function
+from agno.tools.mcp.params import SSEClientParams, StreamableHTTPClientParams
+from agno.utils.log import log_debug, log_error, log_info
+from agno.utils.mcp import get_entrypoint_for_tool, prepare_command
+
+try:
+    from mcp import ClientSession, StdioServerParameters
+    from mcp.client.sse import sse_client
+    from mcp.client.stdio import get_default_environment, stdio_client
+    from mcp.client.streamable_http import streamablehttp_client
+except (ImportError, ModuleNotFoundError):
+    raise ImportError("`mcp` not installed. Please install using `pip install mcp`")
+
+
+class MCPTools(Toolkit):
+    """
+    A toolkit for integrating Model Context Protocol (MCP) servers with Agno agents.
+    This allows agents to access tools, resources, and prompts exposed by MCP servers.
+
+    Can be used in three ways:
+    1. Direct initialization with a ClientSession
+    2. As an async context manager with StdioServerParameters
+    3. As an async context manager with SSE or Streamable HTTP client parameters
+    """
+
+    def __init__(
+        self,
+        command: Optional[str] = None,
+        *,
+        url: Optional[str] = None,
+        env: Optional[dict[str, str]] = None,
+        transport: Literal["stdio", "sse", "streamable-http"] = "stdio",
+        server_params: Optional[Union[StdioServerParameters, SSEClientParams, StreamableHTTPClientParams]] = None,
+        session: Optional[ClientSession] = None,
+        timeout_seconds: int = 10,
+        client=None,
+        include_tools: Optional[list[str]] = None,
+        exclude_tools: Optional[list[str]] = None,
+        refresh_connection: bool = False,
+        **kwargs,
+    ):
+        """
+        Initialize the MCP toolkit.
+
+        Args:
+            session: An initialized MCP ClientSession connected to an MCP server
+            server_params: Parameters for creating a new session
+            command: The command to run to start the server. Should be used in conjunction with env.
+            url: The URL endpoint for SSE or Streamable HTTP connection when transport is "sse" or "streamable-http".
+            env: The environment variables to pass to the server. Should be used in conjunction with command.
+            client: The underlying MCP client (optional, used to prevent garbage collection)
+            timeout_seconds: Read timeout in seconds for the MCP client
+            include_tools: Optional list of tool names to include (if None, includes all)
+            exclude_tools: Optional list of tool names to exclude (if None, excludes none)
+            transport: The transport protocol to use, either "stdio" or "sse" or "streamable-http"
+            refresh_connection: If True, the connection and tools will be refreshed on each run
+        """
+        super().__init__(name="MCPTools", **kwargs)
+
+        if transport == "sse":
+            log_info("SSE as a standalone transport is deprecated. Please use Streamable HTTP instead.")
+
+        # Set these after `__init__` to bypass the `_check_tools_filters`
+        # because tools are not available until `initialize()` is called.
+        self.include_tools = include_tools
+        self.exclude_tools = exclude_tools
+        self.refresh_connection = refresh_connection
+
+        if session is None and server_params is None:
+            if transport == "sse" and url is None:
+                raise ValueError("One of 'url' or 'server_params' parameters must be provided when using SSE transport")
+            if transport == "stdio" and command is None:
+                raise ValueError(
+                    "One of 'command' or 'server_params' parameters must be provided when using stdio transport"
+                )
+            if transport == "streamable-http" and url is None:
+                raise ValueError(
+                    "One of 'url' or 'server_params' parameters must be provided when using Streamable HTTP transport"
+                )
+
+        # Ensure the received server_params are valid for the given transport
+        if server_params is not None:
+            if transport == "sse":
+                if not isinstance(server_params, SSEClientParams):
+                    raise ValueError(
+                        "If using the SSE transport, server_params must be an instance of SSEClientParams."
+                    )
+            elif transport == "stdio":
+                if not isinstance(server_params, StdioServerParameters):
+                    raise ValueError(
+                        "If using the stdio transport, server_params must be an instance of StdioServerParameters."
+                    )
+            elif transport == "streamable-http":
+                if not isinstance(server_params, StreamableHTTPClientParams):
+                    raise ValueError(
+                        "If using the streamable-http transport, server_params must be an instance of StreamableHTTPClientParams."
+                    )
+
+        self.timeout_seconds = timeout_seconds
+        self.session: Optional[ClientSession] = session
+        self.server_params: Optional[Union[StdioServerParameters, SSEClientParams, StreamableHTTPClientParams]] = (
+            server_params
+        )
+        self.transport = transport
+        self.url = url
+
+        # Merge provided env with system env
+        if env is not None:
+            env = {
+                **get_default_environment(),
+                **env,
+            }
+        else:
+            env = get_default_environment()
+
+        if command is not None and transport not in ["sse", "streamable-http"]:
+            parts = prepare_command(command)
+            cmd = parts[0]
+            arguments = parts[1:] if len(parts) > 1 else []
+            self.server_params = StdioServerParameters(command=cmd, args=arguments, env=env)
+
+        self._client = client
+
+        self._initialized = False
+        self._connection_task = None
+        self._active_contexts: list[Any] = []
+        self._context = None
+        self._session_context = None
+
+        def cleanup():
+            """Cancel active connections"""
+            if self._connection_task and not self._connection_task.done():
+                self._connection_task.cancel()
+
+        # Setup cleanup logic before the instance is garbage collected
+        self._cleanup_finalizer = weakref.finalize(self, cleanup)
+
+    @property
+    def initialized(self) -> bool:
+        return self._initialized
+
+    async def is_alive(self) -> bool:
+        if self.session is None:
+            return False
+        try:
+            await self.session.send_ping()
+            return True
+        except (RuntimeError, BaseException):
+            return False
+
+    async def connect(self, force: bool = False):
+        """Initialize a MCPTools instance and connect to the contextual MCP server"""
+
+        if force:
+            # Clean up the session and context so we force a new connection
+            self.session = None
+            self._context = None
+            self._session_context = None
+            self._initialized = False
+            self._connection_task = None
+            self._active_contexts = []
+
+        if self._initialized:
+            return
+
+        try:
+            await self._connect()
+        except (RuntimeError, BaseException) as e:
+            log_error(f"Failed to connect to {str(self)}: {e}")
+
+    async def _connect(self) -> None:
+        """Connects to the MCP server and initializes the tools"""
+
+        if self._initialized:
+            return
+
+        if self.session is not None:
+            await self.initialize()
+            return
+
+        # Create a new studio session
+        if self.transport == "sse":
+            sse_params = asdict(self.server_params) if self.server_params is not None else {}  # type: ignore
+            if "url" not in sse_params:
+                sse_params["url"] = self.url
+            self._context = sse_client(**sse_params)  # type: ignore
+            client_timeout = min(self.timeout_seconds, sse_params.get("timeout", self.timeout_seconds))
+
+        # Create a new streamable HTTP session
+        elif self.transport == "streamable-http":
+            streamable_http_params = asdict(self.server_params) if self.server_params is not None else {}  # type: ignore
+            if "url" not in streamable_http_params:
+                streamable_http_params["url"] = self.url
+            self._context = streamablehttp_client(**streamable_http_params)  # type: ignore
+            params_timeout = streamable_http_params.get("timeout", self.timeout_seconds)
+            if isinstance(params_timeout, timedelta):
+                params_timeout = int(params_timeout.total_seconds())
+            client_timeout = min(self.timeout_seconds, params_timeout)
+
+        else:
+            if self.server_params is None:
+                raise ValueError("server_params must be provided when using stdio transport.")
+            self._context = stdio_client(self.server_params)  # type: ignore
+            client_timeout = self.timeout_seconds
+
+        session_params = await self._context.__aenter__()  # type: ignore
+        self._active_contexts.append(self._context)
+        read, write = session_params[0:2]
+
+        self._session_context = ClientSession(read, write, read_timeout_seconds=timedelta(seconds=client_timeout))  # type: ignore
+        self.session = await self._session_context.__aenter__()  # type: ignore
+        self._active_contexts.append(self._session_context)
+
+        # Initialize with the new session
+        await self.initialize()
+
+    async def close(self) -> None:
+        """Close the MCP connection and clean up resources"""
+        if not self._initialized:
+            return
+
+        try:
+            if self._session_context is not None:
+                await self._session_context.__aexit__(None, None, None)
+                self.session = None
+                self._session_context = None
+
+            if self._context is not None:
+                await self._context.__aexit__(None, None, None)
+                self._context = None
+        except (RuntimeError, BaseException) as e:
+            log_error(f"Failed to close MCP connection: {e}")
+
+        self._initialized = False
+
+    async def __aenter__(self) -> "MCPTools":
+        await self._connect()
+        return self
+
+    async def __aexit__(self, _exc_type, _exc_val, _exc_tb):
+        """Exit the async context manager."""
+        if self._session_context is not None:
+            await self._session_context.__aexit__(_exc_type, _exc_val, _exc_tb)
+            self.session = None
+            self._session_context = None
+
+        if self._context is not None:
+            await self._context.__aexit__(_exc_type, _exc_val, _exc_tb)
+            self._context = None
+
+        self._initialized = False
+
+    async def build_tools(self) -> None:
+        """Build the tools for the MCP toolkit"""
+        if self.session is None:
+            raise ValueError("Session is not initialized")
+
+        try:
+            # Get the list of tools from the MCP server
+            available_tools = await self.session.list_tools()  # type: ignore
+
+            self._check_tools_filters(
+                available_tools=[tool.name for tool in available_tools.tools],
+                include_tools=self.include_tools,
+                exclude_tools=self.exclude_tools,
+            )
+
+            # Filter tools based on include/exclude lists
+            filtered_tools = []
+            for tool in available_tools.tools:
+                if self.exclude_tools and tool.name in self.exclude_tools:
+                    continue
+                if self.include_tools is None or tool.name in self.include_tools:
+                    filtered_tools.append(tool)
+
+            # Register the tools with the toolkit
+            for tool in filtered_tools:
+                try:
+                    # Get an entrypoint for the tool
+                    entrypoint = get_entrypoint_for_tool(tool, self.session)  # type: ignore
+                    # Create a Function for the tool
+                    f = Function(
+                        name=tool.name,
+                        description=tool.description,
+                        parameters=tool.inputSchema,
+                        entrypoint=entrypoint,
+                        # Set skip_entrypoint_processing to True to avoid processing the entrypoint
+                        skip_entrypoint_processing=True,
+                    )
+
+                    # Register the Function with the toolkit
+                    self.functions[f.name] = f
+                    log_debug(f"Function: {f.name} registered with {self.name}")
+                except Exception as e:
+                    log_error(f"Failed to register tool {tool.name}: {e}")
+
+        except (RuntimeError, BaseException) as e:
+            log_error(f"Failed to get tools for {str(self)}: {e}")
+            raise
+
+    async def initialize(self) -> None:
+        """Initialize the MCP toolkit by getting available tools from the MCP server"""
+        if self._initialized:
+            return
+
+        try:
+            if self.session is None:
+                raise ValueError("Session is not initialized")
+
+            # Initialize the session if not already initialized
+            await self.session.initialize()
+
+            await self.build_tools()
+
+            self._initialized = True
+
+        except (RuntimeError, BaseException) as e:
+            log_error(f"Failed to initialize MCP toolkit: {e}")