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

agno/utils/mcp.py

@@ -12,7 +12,7 @@ except (ImportError, ModuleNotFoundError):
     raise ImportError("`mcp` not installed. Please install using `pip install mcp`")
 
 
-from agno.media import ImageArtifact
+from agno.media import Image
 from agno.tools.function import ToolResult
 
 
@@ -27,9 +27,13 @@ def get_entrypoint_for_tool(tool: MCPTool, session: ClientSession):
     Returns:
         Callable: The entrypoint function for the tool
     """
-    from agno.agent import Agent
 
-    async def call_tool(agent: Agent, tool_name: str, **kwargs) -> ToolResult:
+    async def call_tool(tool_name: str, **kwargs) -> ToolResult:
+        try:
+            await session.send_ping()
+        except Exception as e:
+            print(e)
+
         try:
             log_debug(f"Calling MCP Tool '{tool_name}' with args: {kwargs}")
             result: CallToolResult = await session.call_tool(tool_name, kwargs)  # type: ignore
@@ -70,7 +74,7 @@ def get_entrypoint_for_tool(tool: MCPTool, session: ClientSession):
                                     image_bytes = None
 
                                 if image_bytes:
-                                    img_artifact = ImageArtifact(
+                                    img_artifact = Image(
                                         id=str(uuid4()),
                                         url=None,
                                         content=image_bytes,
@@ -98,7 +102,7 @@ def get_entrypoint_for_tool(tool: MCPTool, session: ClientSession):
                             log_debug(f"Failed to decode base64 image data: {e}")
                             image_data = None
 
-                    img_artifact = ImageArtifact(
+                    img_artifact = Image(
                         id=str(uuid4()),
                         url=getattr(content_item, "url", None),
                         content=image_data,
@@ -122,3 +126,89 @@ def get_entrypoint_for_tool(tool: MCPTool, session: ClientSession):
             return ToolResult(content=f"Error: {e}")
 
     return partial(call_tool, tool_name=tool.name)
+
+
+def prepare_command(command: str) -> list[str]:
+    """Sanitize a command and split it into parts before using it to run a MCP server."""
+    import os
+    import shutil
+    from shlex import split
+
+    # Block dangerous characters
+    if any(char in command for char in ["&", "|", ";", "`", "$", "(", ")"]):
+        raise ValueError("MCP command can't contain shell metacharacters")
+
+    parts = split(command)
+    if not parts:
+        raise ValueError("MCP command can't be empty")
+
+    # Only allow specific executables
+    ALLOWED_COMMANDS = {
+        # Python
+        "python",
+        "python3",
+        "uv",
+        "uvx",
+        "pipx",
+        # Node
+        "node",
+        "npm",
+        "npx",
+        "yarn",
+        "pnpm",
+        "bun",
+        # Other runtimes
+        "deno",
+        "java",
+        "ruby",
+        "docker",
+    }
+
+    executable = parts[0].split("/")[-1]
+
+    # Check if it's a relative path starting with ./ or ../
+    if executable.startswith("./") or executable.startswith("../"):
+        # Allow relative paths to binaries
+        return parts
+
+    # Check if it's an absolute path to a binary
+    if executable.startswith("/") and os.path.isfile(executable):
+        # Allow absolute paths to existing files
+        return parts
+
+    # Check if it's a binary in current directory without ./
+    if "/" not in executable and os.path.isfile(executable):
+        # Allow binaries in current directory
+        return parts
+
+    # Check if it's a binary in PATH
+    if shutil.which(executable):
+        return parts
+
+    if executable not in ALLOWED_COMMANDS:
+        raise ValueError(f"MCP command needs to use one of the following executables: {ALLOWED_COMMANDS}")
+
+    first_part = parts[0]
+    executable = first_part.split("/")[-1]
+
+    # Allow known commands
+    if executable in ALLOWED_COMMANDS:
+        return parts
+
+    # Allow relative paths to custom binaries
+    if first_part.startswith(("./", "../")):
+        return parts
+
+    # Allow absolute paths to existing files
+    if first_part.startswith("/") and os.path.isfile(first_part):
+        return parts
+
+    # Allow binaries in current directory without ./
+    if "/" not in first_part and os.path.isfile(first_part):
+        return parts
+
+    # Allow binaries in PATH
+    if shutil.which(first_part):
+        return parts
+
+    raise ValueError(f"MCP command needs to use one of the following executables: {ALLOWED_COMMANDS}")

agno/utils/media.py

@@ -2,10 +2,13 @@ import base64
 import time
 from enum import Enum
 from pathlib import Path
-from typing import List
+from typing import List, Optional
 
 import httpx
 
+from agno.media import Audio, File, Image, Video
+from agno.utils.log import log_info, log_warning
+
 
 class SampleDataFileExtension(str, Enum):
     DOCX = "docx"
@@ -30,7 +33,7 @@ def download_image(url: str, output_path: str) -> bool:
         # Check if the response contains image content
         content_type = response.headers.get("Content-Type")
         if not content_type or not content_type.startswith("image"):
-            print(f"URL does not point to an image. Content-Type: {content_type}")
+            log_warning(f"URL does not point to an image. Content-Type: {content_type}")
             return False
 
         path = Path(output_path)
@@ -42,17 +45,28 @@ def download_image(url: str, output_path: str) -> bool:
                 if chunk:
                     file.write(chunk)
 
-        print(f"Image successfully downloaded and saved to '{output_path}'.")
+        log_info(f"Image successfully downloaded and saved to '{output_path}'.")
         return True
 
     except httpx.HTTPError as e:
-        print(f"Error downloading the image: {e}")
+        log_warning(f"Error downloading the image: {e}")
         return False
     except IOError as e:
-        print(f"Error saving the image to '{output_path}': {e}")
+        log_warning(f"Error saving the image to '{output_path}': {e}")
         return False
 
 
+def download_audio(url: str, output_path: str) -> str:
+    """Download audio from URL"""
+    response = httpx.get(url)
+    response.raise_for_status()
+
+    with open(output_path, "wb") as f:
+        for chunk in response.iter_bytes(chunk_size=8192):
+            f.write(chunk)
+    return output_path
+
+
 def download_video(url: str, output_path: str) -> str:
     """Download video from URL"""
     response = httpx.get(url)
@@ -109,7 +123,7 @@ def save_base64_data(base64_data: str, output_path: str) -> bool:
         with open(path, "wb") as file:
             file.write(decoded_data)
 
-        print(f"Data successfully saved to '{path}'.")
+        log_info(f"Data successfully saved to '{path}'.")
         return True
     except Exception as e:
         raise Exception(f"An unexpected error occurred while saving data to '{output_path}': {e}")
@@ -131,25 +145,25 @@ def wait_for_media_ready(url: str, timeout: int = 120, interval: int = 5, verbos
     max_attempts = timeout // interval
 
     if verbose:
-        print("Media generated! Waiting for upload to complete...")
+        log_info("Media generated! Waiting for upload to complete...")
 
     for attempt in range(max_attempts):
         try:
             response = httpx.head(url, timeout=10)
             response.raise_for_status()
             if verbose:
-                print(f"Media ready: {url}")
+                log_info(f"Media ready: {url}")
             return True
         except httpx.HTTPError:
             pass
 
         if verbose and (attempt + 1) % 3 == 0:
-            print(f"Still processing... ({(attempt + 1) * interval}s elapsed)")
+            log_info(f"Still processing... ({(attempt + 1) * interval}s elapsed)")
 
         time.sleep(interval)
 
     if verbose:
-        print(f"Timeout waiting for media. Try this URL later: {url}")
+        log_warning(f"Timeout waiting for media. Try this URL later: {url}")
     return False
 
 
@@ -183,3 +197,167 @@ def download_knowledge_filters_sample_data(
         )
         file_paths.append(str(download_path))
     return file_paths
+
+
+def reconstruct_image_from_dict(img_data):
+    """
+    Reconstruct an Image object from dictionary data.
+
+    Handles both base64-encoded content (from database) and regular image data (url/filepath).
+    """
+    try:
+        if isinstance(img_data, dict):
+            # If content is base64 string, decode it back to bytes
+            if "content" in img_data and isinstance(img_data["content"], str):
+                return Image.from_base64(
+                    img_data["content"],
+                    id=img_data.get("id"),
+                    mime_type=img_data.get("mime_type"),
+                    format=img_data.get("format"),
+                    detail=img_data.get("detail"),
+                    original_prompt=img_data.get("original_prompt"),
+                    revised_prompt=img_data.get("revised_prompt"),
+                    alt_text=img_data.get("alt_text"),
+                )
+            else:
+                # Regular image (filepath/url)
+                return Image(**img_data)
+        return img_data
+    except Exception as e:
+        log_warning(f"Failed to reconstruct image from dict: {e}")
+        return None
+
+
+def reconstruct_video_from_dict(vid_data):
+    """
+    Reconstruct a Video object from dictionary data.
+
+    Handles both base64-encoded content (from database) and regular video data (url/filepath).
+    """
+    try:
+        if isinstance(vid_data, dict):
+            # If content is base64 string, decode it back to bytes
+            if "content" in vid_data and isinstance(vid_data["content"], str):
+                return Video.from_base64(
+                    vid_data["content"],
+                    id=vid_data.get("id"),
+                    mime_type=vid_data.get("mime_type"),
+                    format=vid_data.get("format"),
+                )
+            else:
+                # Regular video (filepath/url)
+                return Video(**vid_data)
+        return vid_data
+    except Exception as e:
+        log_warning(f"Failed to reconstruct video from dict: {e}")
+        return None
+
+
+def reconstruct_audio_from_dict(aud_data):
+    """
+    Reconstruct an Audio object from dictionary data.
+
+    Handles both base64-encoded content (from database) and regular audio data (url/filepath).
+    """
+    try:
+        if isinstance(aud_data, dict):
+            # If content is base64 string, decode it back to bytes
+            if "content" in aud_data and isinstance(aud_data["content"], str):
+                return Audio.from_base64(
+                    aud_data["content"],
+                    id=aud_data.get("id"),
+                    mime_type=aud_data.get("mime_type"),
+                    transcript=aud_data.get("transcript"),
+                    expires_at=aud_data.get("expires_at"),
+                    sample_rate=aud_data.get("sample_rate", 24000),
+                    channels=aud_data.get("channels", 1),
+                )
+            else:
+                # Regular audio (filepath/url)
+                return Audio(**aud_data)
+        return aud_data
+    except Exception as e:
+        log_warning(f"Failed to reconstruct audio from dict: {e}")
+        return None
+
+
+def reconstruct_file_from_dict(file_data):
+    """
+    Reconstruct a File object from dictionary data.
+
+    Handles both base64-encoded content (from database) and regular file data (url/filepath).
+    """
+    try:
+        if isinstance(file_data, dict):
+            # If content is base64 string, decode it back to bytes
+            if "content" in file_data and isinstance(file_data["content"], str):
+                return File.from_base64(
+                    file_data["content"],
+                    id=file_data.get("id"),
+                    mime_type=file_data.get("mime_type"),
+                    filename=file_data.get("filename"),
+                    name=file_data.get("name"),
+                    format=file_data.get("format"),
+                )
+            else:
+                # Regular file (filepath/url)
+                return File(**file_data)
+        return file_data
+    except Exception as e:
+        log_warning(f"Failed to reconstruct file from dict: {e}")
+        return None
+
+
+def reconstruct_images(images: Optional[List[dict]]) -> Optional[List[Image]]:
+    """Reconstruct a list of Image objects from list of dictionaries.
+
+    Failed reconstructions are skipped with a warning logged.
+    """
+    if not images:
+        return None
+    reconstructed = [reconstruct_image_from_dict(img_data) for img_data in images]
+    valid_images = [img for img in reconstructed if img is not None]
+    return valid_images if valid_images else None
+
+
+def reconstruct_videos(videos: Optional[List[dict]]) -> Optional[List[Video]]:
+    """Reconstruct a list of Video objects from list of dictionaries.
+
+    Failed reconstructions are skipped with a warning logged.
+    """
+    if not videos:
+        return None
+    reconstructed = [reconstruct_video_from_dict(vid_data) for vid_data in videos]
+    valid_videos = [vid for vid in reconstructed if vid is not None]
+    return valid_videos if valid_videos else None
+
+
+def reconstruct_audio_list(audio: Optional[List[dict]]) -> Optional[List[Audio]]:
+    """Reconstruct a list of Audio objects from list of dictionaries.
+
+    Failed reconstructions are skipped with a warning logged.
+    """
+    if not audio:
+        return None
+    reconstructed = [reconstruct_audio_from_dict(aud_data) for aud_data in audio]
+    valid_audio = [aud for aud in reconstructed if aud is not None]
+    return valid_audio if valid_audio else None
+
+
+def reconstruct_files(files: Optional[List[dict]]) -> Optional[List[File]]:
+    """Reconstruct a list of File objects from list of dictionaries.
+
+    Failed reconstructions are skipped with a warning logged.
+    """
+    if not files:
+        return None
+    reconstructed = [reconstruct_file_from_dict(file_data) for file_data in files]
+    valid_files = [f for f in reconstructed if f is not None]
+    return valid_files if valid_files else None
+
+
+def reconstruct_response_audio(audio: Optional[dict]) -> Optional[Audio]:
+    """Reconstruct a single Audio object for response audio."""
+    if not audio:
+        return None
+    return reconstruct_audio_from_dict(audio)

agno/utils/merge_dict.py

@@ -1,4 +1,4 @@
-from typing import Any, Dict
+from typing import Any, Dict, List
 
 
 def merge_dictionaries(a: Dict[str, Any], b: Dict[str, Any]) -> None:
@@ -18,3 +18,24 @@ def merge_dictionaries(a: Dict[str, Any], b: Dict[str, Any]) -> None:
             merge_dictionaries(a[key], b[key])
         else:
             a[key] = b[key]
+
+
+def merge_parallel_session_states(original_state: Dict[str, Any], modified_states: List[Dict[str, Any]]) -> None:
+    """
+    Smart merge for parallel session states that only applies actual changes.
+    This prevents parallel steps from overwriting each other's changes.
+    """
+    if not original_state or not modified_states:
+        return
+
+    # Collect all actual changes (keys where value differs from original)
+    all_changes = {}
+    for modified_state in modified_states:
+        if modified_state:
+            for key, value in modified_state.items():
+                if key not in original_state or original_state[key] != value:
+                    all_changes[key] = value
+
+    # Apply all collected changes to the original state
+    for key, value in all_changes.items():
+        original_state[key] = value

agno/utils/message.py

@@ -1,8 +1,68 @@
+from copy import deepcopy
 from typing import Dict, List, Union
 
 from pydantic import BaseModel
 
 from agno.models.message import Message
+from agno.utils.log import log_debug
+
+
+def filter_tool_calls(messages: List[Message], max_tool_calls: int) -> None:
+    """
+    Filter messages (in-place) to keep only the most recent N tool calls.
+
+    Args:
+        messages: List of messages to filter (modified in-place)
+        max_tool_calls: Number of recent tool calls to keep
+    """
+    # Count total tool calls
+    tool_call_count = sum(1 for m in messages if m.role == "tool")
+
+    # No filtering needed
+    if tool_call_count <= max_tool_calls:
+        return
+
+    # Collect tool_call_ids to keep (most recent N)
+    tool_call_ids_list: List[str] = []
+    for msg in reversed(messages):
+        if msg.role == "tool" and len(tool_call_ids_list) < max_tool_calls:
+            if msg.tool_call_id:
+                tool_call_ids_list.append(msg.tool_call_id)
+
+    tool_call_ids_to_keep: set[str] = set(tool_call_ids_list)
+
+    # Filter messages in-place
+    filtered_messages = []
+    for msg in messages:
+        if msg.role == "tool":
+            # Keep only tool results in our window
+            if msg.tool_call_id in tool_call_ids_to_keep:
+                filtered_messages.append(msg)
+        elif msg.role == "assistant" and msg.tool_calls:
+            # Filter tool_calls within the assistant message
+            # Use deepcopy to ensure complete isolation of the filtered message
+            filtered_msg = deepcopy(msg)
+            # Filter tool_calls
+            if filtered_msg.tool_calls is not None:
+                filtered_msg.tool_calls = [
+                    tc for tc in filtered_msg.tool_calls if tc.get("id") in tool_call_ids_to_keep
+                ]
+
+            if filtered_msg.tool_calls:
+                # Has tool_calls remaining, keep it
+                filtered_messages.append(filtered_msg)
+            # skip empty messages
+            elif filtered_msg.content:
+                filtered_msg.tool_calls = None
+                filtered_messages.append(filtered_msg)
+        else:
+            filtered_messages.append(msg)
+
+    messages[:] = filtered_messages
+
+    # Log filtering information
+    num_filtered = tool_call_count - len(tool_call_ids_to_keep)
+    log_debug(f"Filtered {num_filtered} tool calls, kept {len(tool_call_ids_to_keep)}")
 
 
 def get_text_from_message(message: Union[List, Dict, str, Message, BaseModel]) -> str:

agno/utils/models/claude.py

@@ -32,6 +32,7 @@ class MCPServerConfiguration:
 
 ROLE_MAP = {
     "system": "system",
+    "developer": "system",
     "user": "user",
     "assistant": "assistant",
     "tool": "user",
@@ -67,13 +68,25 @@ def _format_image_for_message(image: Image) -> Optional[Dict[str, Any]]:
     }
 
     try:
+        img_type = None
+
         # Case 0: Image is an Anthropic uploaded file
         if image.content is not None and hasattr(image.content, "id"):
-            return {"type": "image", "source": {"type": "file", "file_id": image.content.id}}
+            content_bytes = image.content
 
         # Case 1: Image is a URL
         if image.url is not None:
-            return {"type": "image", "source": {"type": "url", "url": image.url}}
+            content_bytes = image.get_content_bytes()  # type: ignore
+
+            # If image URL has a suffix, use it as the type (without dot)
+            import os
+            from urllib.parse import urlparse
+
+            if image.url:
+                parsed_url = urlparse(image.url)
+                _, ext = os.path.splitext(parsed_url.path)
+                if ext:
+                    img_type = ext.lstrip(".").lower()
 
         # Case 2: Image is a local file path
         elif image.filepath is not None:
@@ -83,6 +96,11 @@ def _format_image_for_message(image: Image) -> Optional[Dict[str, Any]]:
             if path.exists() and path.is_file():
                 with open(image.filepath, "rb") as f:
                     content_bytes = f.read()
+
+                # If image file path has a suffix, use it as the type (without dot)
+                path_ext = path.suffix.lstrip(".")
+                if path_ext:
+                    img_type = path_ext.lower()
             else:
                 log_error(f"Image file not found: {image}")
                 return None
@@ -95,15 +113,16 @@ def _format_image_for_message(image: Image) -> Optional[Dict[str, Any]]:
             log_error(f"Unsupported image type: {type(image)}")
             return None
 
-        if using_filetype:
-            kind = filetype.guess(content_bytes)
-            if not kind:
-                log_error("Unable to determine image type")
-                return None
+        if not img_type:
+            if using_filetype:
+                kind = filetype.guess(content_bytes)
+                if not kind:
+                    log_error("Unable to determine image type")
+                    return None
 
-            img_type = kind.extension
-        else:
-            img_type = imghdr.what(None, h=content_bytes)  # type: ignore
+                img_type = kind.extension
+            else:
+                img_type = imghdr.what(None, h=content_bytes)  # type: ignore
 
         if not img_type:
             log_error("Unable to determine image type")
@@ -217,7 +236,8 @@ def format_messages(messages: List[Message]) -> Tuple[List[Dict[str, str]], str]
 
     for message in messages:
         content = message.content or ""
-        if message.role == "system":
+        # Both "system" and "developer" roles should be extracted as system messages
+        if message.role in ("system", "developer"):
             if content is not None:
                 system_messages.append(content)  # type: ignore
             continue
@@ -279,6 +299,15 @@ def format_messages(messages: List[Message]) -> Tuple[List[Dict[str, str]], str]
                             type="tool_use",
                         )
                     )
+        elif message.role == "tool":
+            content = []
+            content.append(
+                {
+                    "type": "tool_result",
+                    "tool_use_id": message.tool_call_id,
+                    "content": str(message.content),
+                }
+            )
 
         # Skip empty assistant responses
         if message.role == "assistant" and not content:

agno/utils/models/cohere.py

@@ -20,7 +20,7 @@ def _format_images_for_message(message: Message, images: Sequence[Image]) -> Lis
             if image.content is not None:
                 image_content = image.content
             elif image.url is not None:
-                image_content = image.image_url_content
+                image_content = image.get_content_bytes()  # type: ignore
             elif image.filepath is not None:
                 if isinstance(image.filepath, Path):
                     image_content = image.filepath.read_bytes()

agno/utils/models/watsonx.py

@@ -19,7 +19,7 @@ def format_images_for_message(message: Message, images: Sequence[Image]) -> Mess
             if image.content is not None:
                 image_content = image.content
             elif image.url is not None:
-                image_content = image.image_url_content
+                image_content = image.get_content_bytes()  # type: ignore
             else:
                 log_warning(f"Unsupported image format: {image}")
                 continue

agno/utils/openai.py

@@ -39,7 +39,7 @@ def audio_to_message(audio: Sequence[Audio]) -> List[Dict[str, Any]]:
 
         # The audio is a URL
         elif audio_snippet.url:
-            audio_bytes = audio_snippet.audio_url_content
+            audio_bytes = audio_snippet.get_content_bytes()
             if audio_bytes is not None:
                 encoded_string = base64.b64encode(audio_bytes).decode("utf-8")
                 if not audio_format: