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

agno/utils/agent.py

@@ -1,8 +1,9 @@
 from asyncio import Future, Task
-from typing import AsyncIterator, Iterator, List, Optional, Sequence, Union
+from typing import TYPE_CHECKING, Any, AsyncIterator, Dict, Iterator, List, Optional, Sequence, Union
 
 from agno.media import Audio, File, Image, Video
 from agno.models.message import Message
+from agno.models.metrics import Metrics
 from agno.run.agent import RunEvent, RunInput, RunOutput, RunOutputEvent
 from agno.run.team import RunOutputEvent as TeamRunOutputEvent
 from agno.run.team import TeamRunOutput
@@ -16,6 +17,10 @@ from agno.utils.events import (
 )
 from agno.utils.log import log_debug, log_warning
 
+if TYPE_CHECKING:
+    from agno.agent.agent import Agent
+    from agno.team.team import Team
+
 
 async def await_for_background_tasks(
     memory_task: Optional[Task] = None,
@@ -370,3 +375,363 @@ def scrub_history_messages_from_run_output(run_response: Union[RunOutput, TeamRu
     # Remove messages with from_history=True
     if run_response.messages:
         run_response.messages = [msg for msg in run_response.messages if not msg.from_history]
+
+
+def get_run_output_util(
+    entity: Union["Agent", "Team"], run_id: str, session_id: Optional[str] = None
+) -> Optional[Union[RunOutput, TeamRunOutput]]:
+    """
+    Get a RunOutput from the database.
+
+    Args:
+        run_id (str): The run_id to load from storage.
+        session_id (Optional[str]): The session_id to load from storage.
+    """
+    if session_id is not None:
+        if entity._has_async_db():
+            raise ValueError("Async database not supported for sync functions")
+
+        session = entity.get_session(session_id=session_id)
+        if session is not None:
+            run_response = session.get_run(run_id=run_id)
+            if run_response is not None:
+                return run_response
+            else:
+                log_warning(f"RunOutput {run_id} not found in Session {session_id}")
+    elif entity.cached_session is not None:
+        run_response = entity.cached_session.get_run(run_id=run_id)
+        if run_response is not None:
+            return run_response
+        else:
+            log_warning(f"RunOutput {run_id} not found in Session {entity.cached_session.session_id}")
+            return None
+    return None
+
+
+async def aget_run_output_util(
+    entity: Union["Agent", "Team"], run_id: str, session_id: Optional[str] = None
+) -> Optional[Union[RunOutput, TeamRunOutput]]:
+    """
+    Get a RunOutput from the database.
+
+    Args:
+        run_id (str): The run_id to load from storage.
+        session_id (Optional[str]): The session_id to load from storage.
+    """
+    if session_id is not None:
+        session = await entity.aget_session(session_id=session_id)
+        if session is not None:
+            run_response = session.get_run(run_id=run_id)
+            if run_response is not None:
+                return run_response
+            else:
+                log_warning(f"RunOutput {run_id} not found in Session {session_id}")
+    elif entity.cached_session is not None:
+        run_response = entity.cached_session.get_run(run_id=run_id)
+        if run_response is not None:
+            return run_response
+        else:
+            log_warning(f"RunOutput {run_id} not found in Session {entity.cached_session.session_id}")
+            return None
+    return None
+
+
+def get_last_run_output_util(
+    entity: Union["Agent", "Team"], session_id: Optional[str] = None
+) -> Optional[Union[RunOutput, TeamRunOutput]]:
+    """
+    Get the last run response from the database.
+
+    Args:
+        session_id (Optional[str]): The session_id to load from storage.
+
+    Returns:
+        RunOutput: The last run response from the database.
+    """
+    if session_id is not None:
+        if entity._has_async_db():
+            raise ValueError("Async database not supported for sync functions")
+
+        session = entity.get_session(session_id=session_id)
+        if session is not None and session.runs is not None and len(session.runs) > 0:
+            for run_output in reversed(session.runs):
+                if entity.__class__.__name__ == "Agent":
+                    if hasattr(run_output, "agent_id") and run_output.agent_id == entity.id:
+                        return run_output
+                elif entity.__class__.__name__ == "Team":
+                    if hasattr(run_output, "team_id") and run_output.team_id == entity.id:
+                        return run_output
+        else:
+            log_warning(f"No run responses found in Session {session_id}")
+
+    elif (
+        entity.cached_session is not None
+        and entity.cached_session.runs is not None
+        and len(entity.cached_session.runs) > 0
+    ):
+        for run_output in reversed(entity.cached_session.runs):
+            if entity.__class__.__name__ == "Agent":
+                if hasattr(run_output, "agent_id") and run_output.agent_id == entity.id:
+                    return run_output
+            elif entity.__class__.__name__ == "Team":
+                if hasattr(run_output, "team_id") and run_output.team_id == entity.id:
+                    return run_output
+    return None
+
+
+async def aget_last_run_output_util(
+    entity: Union["Agent", "Team"], session_id: Optional[str] = None
+) -> Optional[Union[RunOutput, TeamRunOutput]]:
+    """
+    Get the last run response from the database.
+
+    Args:
+        session_id (Optional[str]): The session_id to load from storage.
+
+    Returns:
+        RunOutput: The last run response from the database.
+    """
+    if session_id is not None:
+        session = await entity.aget_session(session_id=session_id)
+        if session is not None and session.runs is not None and len(session.runs) > 0:
+            for run_output in reversed(session.runs):
+                if entity.__class__.__name__ == "Agent":
+                    if hasattr(run_output, "agent_id") and run_output.agent_id == entity.id:
+                        return run_output
+                elif entity.__class__.__name__ == "Team":
+                    if hasattr(run_output, "team_id") and run_output.team_id == entity.id:
+                        return run_output
+        else:
+            log_warning(f"No run responses found in Session {session_id}")
+
+    elif (
+        entity.cached_session is not None
+        and entity.cached_session.runs is not None
+        and len(entity.cached_session.runs) > 0
+    ):
+        for run_output in reversed(entity.cached_session.runs):
+            if entity.__class__.__name__ == "Agent":
+                if hasattr(run_output, "agent_id") and run_output.agent_id == entity.id:
+                    return run_output
+            elif entity.__class__.__name__ == "Team":
+                if hasattr(run_output, "team_id") and run_output.team_id == entity.id:
+                    return run_output
+    return None
+
+
+def set_session_name_util(
+    entity: Union["Agent", "Team"], session_id: str, autogenerate: bool = False, session_name: Optional[str] = None
+) -> Union[AgentSession, TeamSession]:
+    """Set the session name and save to storage"""
+    if entity._has_async_db():
+        raise ValueError("Async database not supported for sync functions")
+
+    session = entity.get_session(session_id=session_id)  # type: ignore
+
+    if session is None:
+        raise Exception("No session found")
+
+    # -*- Generate name for session
+    if autogenerate:
+        session_name = entity.generate_session_name(session=session)  # type: ignore
+        log_debug(f"Generated Session Name: {session_name}")
+    elif session_name is None:
+        raise Exception("No session name provided")
+
+    # -*- Rename session
+    if session.session_data is None:
+        session.session_data = {"session_name": session_name}
+    else:
+        session.session_data["session_name"] = session_name
+    # -*- Save to storage
+    entity.save_session(session=session)  # type: ignore
+
+    return session
+
+
+async def aset_session_name_util(
+    entity: Union["Agent", "Team"], session_id: str, autogenerate: bool = False, session_name: Optional[str] = None
+) -> Union[AgentSession, TeamSession]:
+    """Set the session name and save to storage"""
+    session = await entity.aget_session(session_id=session_id)  # type: ignore
+
+    if session is None:
+        raise Exception("Session not found")
+
+    # -*- Generate name for session
+    if autogenerate:
+        session_name = entity.generate_session_name(session=session)  # type: ignore
+        log_debug(f"Generated Session Name: {session_name}")
+    elif session_name is None:
+        raise Exception("No session name provided")
+
+    # -*- Rename session
+    if session.session_data is None:
+        session.session_data = {"session_name": session_name}
+    else:
+        session.session_data["session_name"] = session_name
+
+    # -*- Save to storage
+    await entity.asave_session(session=session)  # type: ignore
+
+    return session
+
+
+def get_session_name_util(entity: Union["Agent", "Team"], session_id: str) -> str:
+    """Get the session name for the given session ID and user ID."""
+
+    if entity._has_async_db():
+        raise ValueError("Async database not supported for sync functions")
+
+    session = entity.get_session(session_id=session_id)  # type: ignore
+    if session is None:
+        raise Exception("Session not found")
+    return session.session_data.get("session_name", "") if session.session_data is not None else ""  # type: ignore
+
+
+async def aget_session_name_util(entity: Union["Agent", "Team"], session_id: str) -> str:
+    """Get the session name for the given session ID and user ID."""
+    session = await entity.aget_session(session_id=session_id)  # type: ignore
+    if session is None:
+        raise Exception("Session not found")
+    return session.session_data.get("session_name", "") if session.session_data is not None else ""  # type: ignore
+
+
+def get_session_state_util(entity: Union["Agent", "Team"], session_id: str) -> Dict[str, Any]:
+    """Get the session state for the given session ID and user ID."""
+    if entity._has_async_db():
+        raise ValueError("Async database not supported for sync functions")
+
+    session = entity.get_session(session_id=session_id)  # type: ignore
+    if session is None:
+        raise Exception("Session not found")
+    return session.session_data.get("session_state", {}) if session.session_data is not None else {}  # type: ignore
+
+
+async def aget_session_state_util(entity: Union["Agent", "Team"], session_id: str) -> Dict[str, Any]:
+    """Get the session state for the given session ID and user ID."""
+    session = await entity.aget_session(session_id=session_id)  # type: ignore
+    if session is None:
+        raise Exception("Session not found")
+    return session.session_data.get("session_state", {}) if session.session_data is not None else {}  # type: ignore
+
+
+def update_session_state_util(
+    entity: Union["Agent", "Team"], session_state_updates: Dict[str, Any], session_id: str
+) -> str:
+    """
+    Update the session state for the given session ID and user ID.
+    Args:
+        session_state_updates: The updates to apply to the session state. Should be a dictionary of key-value pairs.
+        session_id: The session ID to update. If not provided, the current cached session ID is used.
+    Returns:
+        dict: The updated session state.
+    """
+    if entity._has_async_db():
+        raise ValueError("Async database not supported for sync functions")
+
+    session = entity.get_session(session_id=session_id)  # type: ignore
+    if session is None:
+        raise Exception("Session not found")
+
+    if session.session_data is not None and "session_state" not in session.session_data:
+        session.session_data["session_state"] = {}
+
+    for key, value in session_state_updates.items():
+        session.session_data["session_state"][key] = value  # type: ignore
+
+    entity.save_session(session=session)  # type: ignore
+
+    return session.session_data["session_state"]  # type: ignore
+
+
+async def aupdate_session_state_util(
+    entity: Union["Agent", "Team"], session_state_updates: Dict[str, Any], session_id: str
+) -> str:
+    """
+    Update the session state for the given session ID and user ID.
+    Args:
+        session_state_updates: The updates to apply to the session state. Should be a dictionary of key-value pairs.
+        session_id: The session ID to update. If not provided, the current cached session ID is used.
+    Returns:
+        dict: The updated session state.
+    """
+    session = await entity.aget_session(session_id=session_id)  # type: ignore
+    if session is None:
+        raise Exception("Session not found")
+
+    if session.session_data is not None and "session_state" not in session.session_data:
+        session.session_data["session_state"] = {}
+
+    for key, value in session_state_updates.items():
+        session.session_data["session_state"][key] = value  # type: ignore
+
+    await entity.asave_session(session=session)  # type: ignore
+
+    return session.session_data["session_state"]  # type: ignore
+
+
+def get_session_metrics_util(entity: Union["Agent", "Team"], session_id: str) -> Optional[Metrics]:
+    """Get the session metrics for the given session ID and user ID."""
+    if entity._has_async_db():
+        raise ValueError("Async database not supported for sync functions")
+
+    session = entity.get_session(session_id=session_id)  # type: ignore
+    if session is None:
+        raise Exception("Session not found")
+
+    if session.session_data is not None:
+        if isinstance(session.session_data.get("session_metrics"), dict):
+            return Metrics(**session.session_data.get("session_metrics", {}))
+        elif isinstance(session.session_data.get("session_metrics"), Metrics):
+            return session.session_data.get("session_metrics")
+    return None
+
+
+async def aget_session_metrics_util(entity: Union["Agent", "Team"], session_id: str) -> Optional[Metrics]:
+    """Get the session metrics for the given session ID and user ID."""
+    session = await entity.aget_session(session_id=session_id)  # type: ignore
+    if session is None:
+        raise Exception("Session not found")
+
+    if session.session_data is not None:
+        if isinstance(session.session_data.get("session_metrics"), dict):
+            return Metrics(**session.session_data.get("session_metrics", {}))
+        elif isinstance(session.session_data.get("session_metrics"), Metrics):
+            return session.session_data.get("session_metrics")
+    return None
+
+
+def get_chat_history_util(entity: Union["Agent", "Team"], session_id: str) -> List[Message]:
+    """Read the chat history from the session
+
+    Args:
+        session_id: The session ID to get the chat history for. If not provided, the current cached session ID is used.
+    Returns:
+        List[Message]: The chat history from the session.
+    """
+    if entity._has_async_db():
+        raise ValueError("Async database not supported for sync functions")
+
+    session = entity.get_session(session_id=session_id)  # type: ignore
+
+    if session is None:
+        raise Exception("Session not found")
+
+    return session.get_chat_history()
+
+
+async def aget_chat_history_util(entity: Union["Agent", "Team"], session_id: str) -> List[Message]:
+    """Read the chat history from the session
+
+    Args:
+        session_id: The session ID to get the chat history for. If not provided, the current cached session ID is used.
+    Returns:
+        List[Message]: The chat history from the session.
+    """
+    session = await entity.aget_session(session_id=session_id)  # type: ignore
+
+    if session is None:
+        raise Exception("Session not found")
+
+    return session.get_chat_history()

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:
+            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
@@ -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
 
 
@@ -185,3 +186,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)