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

agno/utils/knowledge.py

@@ -1,10 +1,11 @@
-from typing import Any, Dict, Optional
+from typing import Any, Dict, List, Optional, Union
 
+from agno.filters import FilterExpr
 from agno.utils.log import log_info
 
 
 def get_agentic_or_user_search_filters(
-    filters: Optional[Dict[str, Any]], effective_filters: Optional[Dict[str, Any]]
+    filters: Optional[Dict[str, Any]], effective_filters: Optional[Union[Dict[str, Any], List[FilterExpr]]]
 ) -> Dict[str, Any]:
     """Helper function to determine the final filters to use for the search.
 
@@ -15,7 +16,7 @@ def get_agentic_or_user_search_filters(
     Returns:
         Dict[str, Any]: The final filters to use for the search.
     """
-    search_filters = {}
+    search_filters = None
 
     # If agentic filters exist and manual filters (passed by user) do not, use agentic filters
     if filters and not effective_filters:
@@ -23,7 +24,13 @@ def get_agentic_or_user_search_filters(
 
     # If both agentic filters exist and manual filters (passed by user) exist, use manual filters (give priority to user and override)
     if filters and effective_filters:
-        search_filters = effective_filters
+        if isinstance(effective_filters, dict):
+            search_filters = effective_filters
+        elif isinstance(effective_filters, list):
+            # If effective_filters is a list (likely List[FilterExpr]), convert both filters and effective_filters to a dict if possible, otherwise raise
+            raise ValueError(
+                "Merging dict and list of filters is not supported; effective_filters should be a dict for search compatibility."
+            )
 
     log_info(f"Filters used by Agent: {search_filters}")
-    return search_filters
+    return search_filters or {}

agno/utils/log.py

@@ -108,6 +108,7 @@ workflow_logger: AgnoLogger = build_logger(WORKFLOW_LOGGER_NAME, source_type="wo
 # Set the default logger to the agent logger
 logger: AgnoLogger = agent_logger
 
+
 debug_on: bool = False
 debug_level: Literal[1, 2] = 1
 

agno/utils/mcp.py

@@ -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:
+            log_exception(e)
+
         try:
             log_debug(f"Calling MCP Tool '{tool_name}' with args: {kwargs}")
             result: CallToolResult = await session.call_tool(tool_name, kwargs)  # type: ignore
@@ -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,11 @@ 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
 
 
@@ -55,6 +56,17 @@ def download_image(url: str, output_path: str) -> bool:
         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)
@@ -185,3 +197,177 @@ 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):
+                file_obj = 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"),
+                )
+                # Preserve additional fields that from_base64 doesn't handle
+                if file_data.get("size") is not None:
+                    file_obj.size = file_data.get("size")
+                if file_data.get("file_type") is not None:
+                    file_obj.file_type = file_data.get("file_type")
+                if file_data.get("filepath") is not None:
+                    file_obj.filepath = file_data.get("filepath")
+                if file_data.get("url") is not None:
+                    file_obj.url = file_data.get("url")
+                return file_obj
+            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

@@ -27,7 +27,7 @@ def merge_parallel_session_states(original_state: Dict[str, Any], modified_state
     """
     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:
@@ -35,7 +35,7 @@ def merge_parallel_session_states(original_state: Dict[str, Any], 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
+        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/ai_foundry.py

@@ -5,19 +5,26 @@ from agno.utils.log import log_warning
 from agno.utils.openai import images_to_message
 
 
-def format_message(message: Message) -> Dict[str, Any]:
+def format_message(message: Message, compress_tool_results: bool = False) -> Dict[str, Any]:
     """
     Format a message into the format expected by OpenAI.
 
     Args:
         message (Message): The message to format.
+        compress_tool_results: Whether to compress tool results.
 
     Returns:
         Dict[str, Any]: The formatted message.
     """
+    # Use compressed content for tool messages if compression is active
+    content = message.content
+
+    if message.role == "tool":
+        content = message.get_content(use_compressed_content=compress_tool_results)
+
     message_dict: Dict[str, Any] = {
         "role": message.role,
-        "content": message.content,
+        "content": content,
         "name": message.name,
         "tool_call_id": message.tool_call_id,
         "tool_calls": message.tool_calls,

agno/utils/models/claude.py

@@ -1,6 +1,6 @@
 import json
 from dataclasses import dataclass, field
-from typing import Any, Dict, List, Optional, Tuple
+from typing import Any, Dict, List, Optional, Tuple, Union
 
 from agno.media import File, Image
 from agno.models.message import Message
@@ -32,6 +32,7 @@ class MCPServerConfiguration:
 
 ROLE_MAP = {
     "system": "system",
+    "developer": "system",
     "user": "user",
     "assistant": "assistant",
     "tool": "user",
@@ -67,6 +68,8 @@ 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"):
             content_bytes = image.content
@@ -75,6 +78,16 @@ def _format_image_for_message(image: Image) -> Optional[Dict[str, Any]]:
         if image.url is not None:
             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:
             from pathlib import Path
@@ -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")
@@ -202,22 +221,26 @@ def _format_file_for_message(file: File) -> Optional[Dict[str, Any]]:
     return None
 
 
-def format_messages(messages: List[Message]) -> Tuple[List[Dict[str, str]], str]:
+def format_messages(
+    messages: List[Message], compress_tool_results: bool = False
+) -> Tuple[List[Dict[str, Union[str, list]]], str]:
     """
     Process the list of messages and separate them into API messages and system messages.
 
     Args:
         messages (List[Message]): The list of messages to process.
+        compress_tool_results: Whether to compress tool results.
 
     Returns:
-        Tuple[List[Dict[str, str]], str]: A tuple containing the list of API messages and the concatenated system messages.
+        Tuple[List[Dict[str, Union[str, list]]], str]: A tuple containing the list of API messages and the concatenated system messages.
     """
-    chat_messages: List[Dict[str, str]] = []
+    chat_messages: List[Dict[str, Union[str, list]]] = []
     system_messages: List[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
@@ -281,11 +304,15 @@ def format_messages(messages: List[Message]) -> Tuple[List[Dict[str, str]], str]
                     )
         elif message.role == "tool":
             content = []
+
+            # Use compressed content for tool messages if compression is active
+            tool_result = message.get_content(use_compressed_content=compress_tool_results)
+
             content.append(
                 {
                     "type": "tool_result",
                     "tool_use_id": message.tool_call_id,
-                    "content": str(message.content),
+                    "content": str(tool_result),
                 }
             )
 
@@ -300,6 +327,7 @@ def format_messages(messages: List[Message]) -> Tuple[List[Dict[str, str]], str]
 def format_tools_for_model(tools: Optional[List[Dict[str, Any]]] = None) -> Optional[List[Dict[str, Any]]]:
     """
     Transforms function definitions into a format accepted by the Anthropic API.
+    Now supports strict mode for structured outputs.
     """
     if not tools:
         return None
@@ -332,7 +360,14 @@ def format_tools_for_model(tools: Optional[List[Dict[str, Any]]] = None) -> Opti
                 "type": parameters.get("type", "object"),
                 "properties": input_properties,
                 "required": required_params,
+                "additionalProperties": False,
             },
         }
+
+        # Add strict mode if specified (check both function dict and tool_def top level)
+        strict_mode = func_def.get("strict") or tool_def.get("strict")
+        if strict_mode is True:
+            tool["strict"] = True
+
         parsed_tools.append(tool)
     return parsed_tools

agno/utils/models/cohere.py

@@ -46,21 +46,28 @@ def _format_images_for_message(message: Message, images: Sequence[Image]) -> Lis
     return message_content_with_image
 
 
-def format_messages(messages: List[Message]) -> List[Dict[str, Any]]:
+def format_messages(messages: List[Message], compress_tool_results: bool = False) -> List[Dict[str, Any]]:
     """
     Format messages for the Cohere API.
 
     Args:
         messages (List[Message]): The list of messages.
+        compress_tool_results: Whether to compress tool results.
 
     Returns:
         List[Dict[str, Any]]: The formatted messages.
     """
     formatted_messages = []
     for message in messages:
+        # Use compressed content for tool messages if compression is active
+        content = message.content
+
+        if message.role == "tool":
+            content = message.get_content(use_compressed_content=compress_tool_results)
+
         message_dict = {
             "role": message.role,
-            "content": message.content,
+            "content": content,
             "name": message.name,
             "tool_call_id": message.tool_call_id,
             "tool_calls": message.tool_calls,