agno 2.0.1__py3-none-any.whl → 2.3.0__py3-none-any.whl

agno/utils/gemini.py

@@ -1,5 +1,7 @@
 from pathlib import Path
-from typing import Any, Dict, List, Optional
+from typing import Any, Dict, List, Optional, Type, Union
+
+from pydantic import BaseModel
 
 from agno.media import Image
 from agno.utils.log import log_error, log_warning
@@ -9,12 +11,119 @@ try:
         FunctionDeclaration,
         Schema,
         Tool,
-        Type,
+    )
+    from google.genai.types import (
+        Type as GeminiType,
     )
 except ImportError:
     raise ImportError("`google-genai` not installed. Please install it using `pip install google-genai`")
 
 
+def prepare_response_schema(pydantic_model: Type[BaseModel]) -> Union[Type[BaseModel], Schema]:
+    """
+    Prepare a Pydantic model for use as Gemini response schema.
+
+    Returns the model directly if Gemini can handle it natively,
+    otherwise converts to Gemini's Schema format.
+
+    Args:
+        pydantic_model: A Pydantic model class
+
+    Returns:
+        Either the original Pydantic model or a converted Schema object
+    """
+    schema_dict = pydantic_model.model_json_schema()
+
+    # Convert to Gemini Schema if the model has problematic patterns
+    if needs_conversion(schema_dict):
+        try:
+            converted = convert_schema(schema_dict)
+        except Exception as e:
+            log_warning(f"Failed to convert schema for {pydantic_model}: {e}")
+            converted = None
+
+        if converted is None:
+            # If conversion fails, let Gemini handle it directly
+            return pydantic_model
+        return converted
+
+    # Gemini can handle this model directly
+    return pydantic_model
+
+
+def needs_conversion(schema_dict: Dict[str, Any]) -> bool:
+    """
+    Check if a schema needs conversion for Gemini.
+
+    Returns True if the schema has:
+    - Self-references or circular references
+    - Dict fields (additionalProperties) that Gemini doesn't handle well
+    - Empty object definitions that Gemini rejects
+    """
+    # Check for dict fields (additionalProperties) anywhere in the schema
+    if has_additional_properties(schema_dict):
+        return True
+
+    # Check if schema has $defs with circular references
+    if "$defs" in schema_dict:
+        defs = schema_dict["$defs"]
+        for def_name, def_schema in defs.items():
+            ref_path = f"#/$defs/{def_name}"
+            if has_self_reference(def_schema, ref_path):
+                return True
+
+    return False
+
+
+def has_additional_properties(schema: Any) -> bool:
+    """Check if schema has additionalProperties (Dict fields)"""
+    if isinstance(schema, dict):
+        # Direct check
+        if "additionalProperties" in schema:
+            return True
+
+        # Check properties recursively
+        if "properties" in schema:
+            for prop_schema in schema["properties"].values():
+                if has_additional_properties(prop_schema):
+                    return True
+
+        # Check array items
+        if "items" in schema:
+            if has_additional_properties(schema["items"]):
+                return True
+
+    return False
+
+
+def has_self_reference(schema: Dict, target_ref: str) -> bool:
+    """Check if a schema references itself (directly or indirectly)"""
+    if isinstance(schema, dict):
+        # Direct self-reference
+        if schema.get("$ref") == target_ref:
+            return True
+
+        # Check properties
+        if "properties" in schema:
+            for prop_schema in schema["properties"].values():
+                if has_self_reference(prop_schema, target_ref):
+                    return True
+
+        # Check array items
+        if "items" in schema:
+            if has_self_reference(schema["items"], target_ref):
+                return True
+
+        # Check anyOf/oneOf/allOf
+        for key in ["anyOf", "oneOf", "allOf"]:
+            if key in schema:
+                for sub_schema in schema[key]:
+                    if has_self_reference(sub_schema, target_ref):
+                        return True
+
+    return False
+
+
 def format_image_for_message(image: Image) -> Optional[Dict[str, Any]]:
     # Case 1: Image is a URL
     # Download the image from the URL and add it as base64 encoded data
@@ -66,7 +175,9 @@ def format_image_for_message(image: Image) -> Optional[Dict[str, Any]]:
         return None
 
 
-def convert_schema(schema_dict: Dict[str, Any], root_schema: Optional[Dict[str, Any]] = None) -> Optional[Schema]:
+def convert_schema(
+    schema_dict: Dict[str, Any], root_schema: Optional[Dict[str, Any]] = None, visited_refs: Optional[set] = None
+) -> Optional[Schema]:
     """
     Recursively convert a JSON-like schema dictionary to a types.Schema object.
 
@@ -74,23 +185,39 @@ def convert_schema(schema_dict: Dict[str, Any], root_schema: Optional[Dict[str,
         schema_dict (dict): The JSON schema dictionary with keys like "type", "description",
                             "properties", and "required".
         root_schema (dict, optional): The root schema containing $defs for resolving $ref
+        visited_refs (set, optional): Set of visited $ref paths to detect circular references
 
     Returns:
         types.Schema: The converted schema.
     """
 
-    # If this is the initial call, set root_schema to self
+    # If this is the initial call, set root_schema to self and initialize visited_refs
     if root_schema is None:
         root_schema = schema_dict
+    if visited_refs is None:
+        visited_refs = set()
 
-    # Handle $ref references
+    # Handle $ref references with cycle detection
     if "$ref" in schema_dict:
         ref_path = schema_dict["$ref"]
+
+        # Check for circular reference
+        if ref_path in visited_refs:
+            # Return a basic object schema to break the cycle
+            return Schema(
+                type=GeminiType.OBJECT,
+                description=f"Circular reference to {ref_path}",
+            )
+
         if ref_path.startswith("#/$defs/"):
             def_name = ref_path.split("/")[-1]
             if "$defs" in root_schema and def_name in root_schema["$defs"]:
+                # Add to visited set before recursing
+                new_visited = visited_refs.copy()
+                new_visited.add(ref_path)
+
                 referenced_schema = root_schema["$defs"][def_name]
-                return convert_schema(referenced_schema, root_schema)
+                return convert_schema(referenced_schema, root_schema, new_visited)
         # If we can't resolve the reference, return None
         return None
 
@@ -98,12 +225,13 @@ def convert_schema(schema_dict: Dict[str, Any], root_schema: Optional[Dict[str,
     if schema_type is None or schema_type == "null":
         return None
     description = schema_dict.get("description", None)
+    title = schema_dict.get("title", None)
     default = schema_dict.get("default", None)
 
     # Handle enum types
     if "enum" in schema_dict:
         enum_values = schema_dict["enum"]
-        return Schema(type=Type.STRING, enum=enum_values, description=description, default=default)
+        return Schema(type=GeminiType.STRING, enum=enum_values, description=description, default=default, title=title)
 
     if schema_type == "object":
         # Handle regular objects with properties
@@ -117,25 +245,30 @@ def convert_schema(schema_dict: Dict[str, Any], root_schema: Optional[Dict[str,
                     prop_def["type"] = prop_type[0]
                     is_nullable = True
 
-                # Process property schema (pass root_schema for $ref resolution)
-                converted_schema = convert_schema(prop_def, root_schema)
+                # Process property schema (pass root_schema and visited_refs for $ref resolution)
+                converted_schema = convert_schema(prop_def, root_schema, visited_refs)
                 if converted_schema is not None:
                     if is_nullable:
                         converted_schema.nullable = True
                     properties[key] = converted_schema
+                else:
+                    properties[key] = Schema(
+                        title=prop_def.get("title", None), description=prop_def.get("description", None)
+                    )
 
             required = schema_dict.get("required", [])
 
             if properties:
                 return Schema(
-                    type=Type.OBJECT,
+                    type=GeminiType.OBJECT,
                     properties=properties,
                     required=required,
                     description=description,
                     default=default,
+                    title=title,
                 )
             else:
-                return Schema(type=Type.OBJECT, description=description, default=default)
+                return Schema(type=GeminiType.OBJECT, description=description, default=default, title=title)
 
         # Handle Dict types (objects with additionalProperties but no properties)
         elif "additionalProperties" in schema_dict:
@@ -146,50 +279,67 @@ def convert_schema(schema_dict: Dict[str, Any], root_schema: Optional[Dict[str,
                 # For Gemini, we need to represent Dict[str, T] as an object with at least one property
                 # to avoid the "properties should be non-empty" error.
                 # We'll create a generic property that represents the dictionary structure
-                value_type = additional_props.get("type", "string").upper()
+
+                # Handle both single types and union types (arrays) from Zod schemas
+                type_value = additional_props.get("type", "string")
+                if isinstance(type_value, list):
+                    value_type = type_value[0].upper() if type_value else "STRING"
+                    union_types = ", ".join(type_value)
+                    type_description_suffix = f" (supports union types: {union_types})"
+                else:
+                    # Single type
+                    value_type = type_value.upper()
+                    type_description_suffix = ""
+
                 # Create a placeholder property to satisfy Gemini's requirements
                 # This is a workaround since Gemini doesn't support additionalProperties directly
                 placeholder_properties = {
                     "example_key": Schema(
                         type=value_type,
-                        description=f"Example key-value pair. This object can contain any number of keys with {value_type.lower()} values.",
+                        description=f"Example key-value pair. This object can contain any number of keys with {value_type.lower()} values{type_description_suffix}.",
                     )
                 }
                 if value_type == "ARRAY":
                     placeholder_properties["example_key"].items = {}  # type: ignore
 
                 return Schema(
-                    type=Type.OBJECT,
+                    type=GeminiType.OBJECT,
                     properties=placeholder_properties,
                     description=description
-                    or f"Dictionary with {value_type.lower()} values. Can contain any number of key-value pairs.",
+                    or f"Dictionary with {value_type.lower()} values{type_description_suffix}. Can contain any number of key-value pairs.",
                     default=default,
                 )
             else:
                 # additionalProperties is false or true
-                return Schema(type=Type.OBJECT, description=description, default=default)
+                return Schema(type=GeminiType.OBJECT, description=description, default=default, title=title)
 
         # Handle empty objects
         else:
-            return Schema(type=Type.OBJECT, description=description, default=default)
+            return Schema(type=GeminiType.OBJECT, description=description, default=default, title=title)
 
     elif schema_type == "array" and "items" in schema_dict:
-        items = convert_schema(schema_dict["items"], root_schema)
+        if not schema_dict["items"]:  # Handle empty {}
+            items = Schema(type=GeminiType.STRING)
+        else:
+            converted_items = convert_schema(schema_dict["items"], root_schema, visited_refs)
+            items = converted_items if converted_items is not None else Schema(type=GeminiType.STRING)
         min_items = schema_dict.get("minItems")
         max_items = schema_dict.get("maxItems")
         return Schema(
-            type=Type.ARRAY,
+            type=GeminiType.ARRAY,
             description=description,
             items=items,
             min_items=min_items,
             max_items=max_items,
+            title=title,
         )
 
     elif schema_type == "string":
         schema_kwargs = {
-            "type": Type.STRING,
+            "type": GeminiType.STRING,
             "description": description,
             "default": default,
+            "title": title,
         }
         if "format" in schema_dict:
             schema_kwargs["format"] = schema_dict["format"]
@@ -200,6 +350,7 @@ def convert_schema(schema_dict: Dict[str, Any], root_schema: Optional[Dict[str,
             "type": schema_type.upper(),
             "description": description,
             "default": default,
+            "title": title,
         }
         if "maximum" in schema_dict:
             schema_kwargs["maximum"] = schema_dict["maximum"]
@@ -210,7 +361,7 @@ def convert_schema(schema_dict: Dict[str, Any], root_schema: Optional[Dict[str,
     elif schema_type == "" and "anyOf" in schema_dict:
         any_of = []
         for sub_schema in schema_dict["anyOf"]:
-            sub_schema_converted = convert_schema(sub_schema, root_schema)
+            sub_schema_converted = convert_schema(sub_schema, root_schema, visited_refs)
             any_of.append(sub_schema_converted)
 
         is_nullable = False
@@ -231,12 +382,19 @@ def convert_schema(schema_dict: Dict[str, Any], root_schema: Optional[Dict[str,
                 any_of=any_of,
                 description=description,
                 default=default,
+                title=title,
             )
     else:
+        if isinstance(schema_type, list):
+            non_null_types = [t for t in schema_type if t != "null"]
+            if non_null_types:
+                schema_type = non_null_types[0]
+            else:
+                schema_type = ""
         # Only convert to uppercase if schema_type is not empty
         if schema_type:
             schema_type = schema_type.upper()
-            return Schema(type=schema_type, description=description, default=default)
+            return Schema(type=schema_type, description=description, default=default, title=title)
         else:
             # If we get here with an empty type and no other handlers matched,
             # something is wrong with the schema

agno/utils/hooks.py

@@ -0,0 +1,57 @@
+from typing import Any, Callable, Dict, List, Optional, Union
+
+from agno.guardrails.base import BaseGuardrail
+from agno.utils.log import log_warning
+
+
+def normalize_hooks(
+    hooks: Optional[List[Union[Callable[..., Any], BaseGuardrail]]],
+    async_mode: bool = False,
+) -> Optional[List[Callable[..., Any]]]:
+    """Normalize hooks to a list format"""
+    result_hooks: List[Callable[..., Any]] = []
+
+    if hooks is not None:
+        for hook in hooks:
+            if isinstance(hook, BaseGuardrail):
+                if async_mode:
+                    result_hooks.append(hook.async_check)
+                else:
+                    result_hooks.append(hook.check)
+            else:
+                # Check if the hook is async and used within sync methods
+                if not async_mode:
+                    import asyncio
+
+                    if asyncio.iscoroutinefunction(hook):
+                        raise ValueError(
+                            f"Cannot use {hook.__name__} (an async hook) with `run()`. Use `arun()` instead."
+                        )
+
+                result_hooks.append(hook)
+    return result_hooks if result_hooks else None
+
+
+def filter_hook_args(hook: Callable[..., Any], all_args: Dict[str, Any]) -> Dict[str, Any]:
+    """Filter arguments to only include those that the hook function accepts."""
+    import inspect
+
+    try:
+        sig = inspect.signature(hook)
+        accepted_params = set(sig.parameters.keys())
+
+        has_var_keyword = any(param.kind == inspect.Parameter.VAR_KEYWORD for param in sig.parameters.values())
+
+        # If the function has **kwargs, pass all arguments
+        if has_var_keyword:
+            return all_args
+
+        # Otherwise, filter to only include accepted parameters
+        filtered_args = {key: value for key, value in all_args.items() if key in accepted_params}
+
+        return filtered_args
+
+    except Exception as e:
+        log_warning(f"Could not inspect hook signature, passing all arguments: {e}")
+        # If signature inspection fails, pass all arguments as fallback
+        return all_args

agno/utils/http.py

@@ -10,6 +10,117 @@ logger = logging.getLogger(__name__)
 DEFAULT_MAX_RETRIES = 3
 DEFAULT_BACKOFF_FACTOR = 2  # Exponential backoff: 1, 2, 4, 8...
 
+# Global httpx clients for resource efficiency
+# These are shared across all models to reuse connection pools and avoid resource leaks.
+# Consumers can override these at application startup using set_default_sync_client()
+# and set_default_async_client() to customize limits, timeouts, proxies, etc.
+_global_sync_client: Optional[httpx.Client] = None
+_global_async_client: Optional[httpx.AsyncClient] = None
+
+
+def get_default_sync_client() -> httpx.Client:
+    """Get or create the global synchronous httpx client.
+
+    Returns:
+        A singleton httpx.Client instance with default limits.
+    """
+    global _global_sync_client
+    if _global_sync_client is None or _global_sync_client.is_closed:
+        _global_sync_client = httpx.Client(
+            limits=httpx.Limits(max_connections=1000, max_keepalive_connections=200), http2=True, follow_redirects=True
+        )
+    return _global_sync_client
+
+
+def get_default_async_client() -> httpx.AsyncClient:
+    """Get or create the global asynchronous httpx client.
+
+    Returns:
+        A singleton httpx.AsyncClient instance with default limits.
+    """
+    global _global_async_client
+    if _global_async_client is None or _global_async_client.is_closed:
+        _global_async_client = httpx.AsyncClient(
+            limits=httpx.Limits(max_connections=1000, max_keepalive_connections=200), http2=True, follow_redirects=True
+        )
+    return _global_async_client
+
+
+def close_sync_client() -> None:
+    """Closes the global sync httpx client.
+
+    Should be called during application shutdown.
+    """
+    global _global_sync_client
+    if _global_sync_client is not None and not _global_sync_client.is_closed:
+        _global_sync_client.close()
+
+
+async def aclose_default_clients() -> None:
+    """Asynchronously close the global httpx clients.
+
+    Should be called during application shutdown in async contexts.
+    """
+    global _global_sync_client, _global_async_client
+    if _global_sync_client is not None and not _global_sync_client.is_closed:
+        _global_sync_client.close()
+    if _global_async_client is not None and not _global_async_client.is_closed:
+        await _global_async_client.aclose()
+
+
+def set_default_sync_client(client: httpx.Client) -> None:
+    """Set the global synchronous httpx client.
+
+    IMPORTANT: Call before creating any model instances. Models cache clients on first use.
+
+    Allows consumers to override the default httpx client with custom configuration
+    (e.g., custom limits, timeouts, proxies, SSL verification, etc.).
+    This is useful at application startup to customize how all models connect.
+
+    Example:
+        >>> import httpx
+        >>> from agno.utils.http import set_default_sync_client
+        >>> custom_client = httpx.Client(
+        ...     limits=httpx.Limits(max_connections=500),
+        ...     timeout=httpx.Timeout(30.0),
+        ...     verify=False  # for dev environments
+        ... )
+        >>> set_default_sync_client(custom_client)
+        >>> # All models will now use this custom client
+
+    Args:
+        client: An httpx.Client instance to use as the global sync client.
+    """
+    global _global_sync_client
+    _global_sync_client = client
+
+
+def set_default_async_client(client: httpx.AsyncClient) -> None:
+    """Set the global asynchronous httpx client.
+
+    IMPORTANT: Call before creating any model instances. Models cache clients on first use.
+
+    Allows consumers to override the default async httpx client with custom configuration
+    (e.g., custom limits, timeouts, proxies, SSL verification, etc.).
+    This is useful at application startup to customize how all models connect.
+
+    Example:
+        >>> import httpx
+        >>> from agno.utils.http import set_default_async_client
+        >>> custom_client = httpx.AsyncClient(
+        ...     limits=httpx.Limits(max_connections=500),
+        ...     timeout=httpx.Timeout(30.0),
+        ...     verify=False  # for dev environments
+        ... )
+        >>> set_default_async_client(custom_client)
+        >>> # All models will now use this custom client
+
+    Args:
+        client: An httpx.AsyncClient instance to use as the global async client.
+    """
+    global _global_async_client
+    _global_async_client = client
+
 
 def fetch_with_retry(
     url: str,

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:
+            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}")