agno 2.3.12__py3-none-any.whl → 2.3.14__py3-none-any.whl

agno/os/scopes.py

@@ -0,0 +1,469 @@
+"""AgentOS RBAC Scopes
+
+This module defines all available permission scopes for AgentOS RBAC (Role-Based Access Control).
+
+Scope Format:
+- Global resource scopes: `resource:action`
+- Per-resource scopes: `resource:<resource-id>:action`
+- Wildcards: `resource:*:action` for any resource
+
+The AgentOS ID is verified via the JWT `aud` (audience) claim.
+
+Examples:
+- `system:read` - Read system config
+- `agents:read` - List all agents
+- `agents:web-agent:read` - Read specific agent
+- `agents:web-agent:run` - Run specific agent
+- `agents:*:run` - Run any agent (wildcard)
+- `agent_os:admin` - Full access to everything
+"""
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Dict, List, Optional, Set
+
+
+class AgentOSScope(str, Enum):
+    """
+    Enum of all available AgentOS permission scopes.
+
+    Special Scopes:
+    - ADMIN: Grants full access to all endpoints (agent_os:admin)
+
+    Scope format:
+
+    Global Resource Scopes:
+    - system:read - System configuration and model information
+    - agents:read - List all agents
+    - teams:read - List all teams
+    - workflows:read - List all workflows
+    - sessions:read - View session data
+    - sessions:write - Create and update sessions
+    - sessions:delete - Delete sessions
+    - memories:read - View memories
+    - memories:write - Create and update memories
+    - memories:delete - Delete memories
+    - knowledge:read - View and search knowledge
+    - knowledge:write - Add and update knowledge
+    - knowledge:delete - Delete knowledge
+    - metrics:read - View metrics
+    - metrics:write - Refresh metrics
+    - evals:read - View evaluation runs
+    - evals:write - Create and update evaluation runs
+    - evals:delete - Delete evaluation runs
+    - traces:read - View traces and trace statistics
+
+    Per-Resource Scopes (with resource ID):
+    - agents:<agent-id>:read - Read specific agent
+    - agents:<agent-id>:run - Run specific agent
+    - teams:<team-id>:read - Read specific team
+    - teams:<team-id>:run - Run specific team
+    - workflows:<workflow-id>:read - Read specific workflow
+    - workflows:<workflow-id>:run - Run specific workflow
+
+    Wildcards:
+    - agents:*:run - Run any agent
+    - teams:*:run - Run any team
+    """
+
+    # Special scopes
+    ADMIN = "agent_os:admin"
+
+
+@dataclass
+class ParsedScope:
+    """Represents a parsed scope with its components."""
+
+    raw: str
+    scope_type: str  # "admin", "global", "per_resource", or "unknown"
+    resource: Optional[str] = None
+    resource_id: Optional[str] = None
+    action: Optional[str] = None
+    is_wildcard_resource: bool = False
+
+    @property
+    def is_global_resource_scope(self) -> bool:
+        """Check if this scope targets all resources of a type (no resource_id)."""
+        return self.scope_type == "global"
+
+    @property
+    def is_per_resource_scope(self) -> bool:
+        """Check if this scope targets a specific resource (has resource_id)."""
+        return self.scope_type == "per_resource"
+
+
+def parse_scope(scope: str, admin_scope: Optional[str] = None) -> ParsedScope:
+    """
+    Parse a scope string into its components.
+
+    Args:
+        scope: The scope string to parse
+        admin_scope: The scope string that grants admin access (default: "agent_os:admin")
+
+    Returns:
+        ParsedScope object with parsed components
+
+    Examples:
+        >>> parse_scope("agent_os:admin")
+        ParsedScope(raw="agent_os:admin", scope_type="admin")
+
+        >>> parse_scope("system:read")
+        ParsedScope(raw="system:read", scope_type="global", resource="system", action="read")
+
+        >>> parse_scope("agents:web-agent:read")
+        ParsedScope(raw="...", scope_type="per_resource", resource="agents", resource_id="web-agent", action="read")
+
+        >>> parse_scope("agents:*:run")
+        ParsedScope(raw="...", scope_type="per_resource", resource="agents", resource_id="*", action="run", is_wildcard_resource=True)
+    """
+    effective_admin_scope = admin_scope or AgentOSScope.ADMIN.value
+    if scope == effective_admin_scope:
+        return ParsedScope(raw=scope, scope_type="admin")
+
+    parts = scope.split(":")
+
+    # Global resource scope: resource:action (2 parts)
+    if len(parts) == 2:
+        return ParsedScope(
+            raw=scope,
+            scope_type="global",
+            resource=parts[0],
+            action=parts[1],
+        )
+
+    # Per-resource scope: resource:<resource-id>:action (3 parts)
+    if len(parts) == 3:
+        resource_id = parts[1]
+        is_wildcard_resource = resource_id == "*"
+
+        return ParsedScope(
+            raw=scope,
+            scope_type="per_resource",
+            resource=parts[0],
+            resource_id=resource_id,
+            action=parts[2],
+            is_wildcard_resource=is_wildcard_resource,
+        )
+
+    # Invalid format
+    return ParsedScope(raw=scope, scope_type="unknown")
+
+
+def matches_scope(
+    user_scope: ParsedScope,
+    required_scope: ParsedScope,
+    resource_id: Optional[str] = None,
+) -> bool:
+    """
+    Check if a user's scope matches a required scope.
+
+    Args:
+        user_scope: The user's parsed scope
+        required_scope: The required parsed scope
+        resource_id: The specific resource ID being accessed
+
+    Returns:
+        True if the user's scope satisfies the required scope
+
+    Examples:
+        >>> user = parse_scope("system:read")
+        >>> required = parse_scope("system:read")
+        >>> matches_scope(user, required)
+        True
+
+        >>> user = parse_scope("agents:web-agent:run")
+        >>> required = parse_scope("agents:<id>:run")
+        >>> matches_scope(user, required, resource_id="web-agent")
+        True
+
+        >>> user = parse_scope("agents:*:run")
+        >>> required = parse_scope("agents:<id>:run")
+        >>> matches_scope(user, required, resource_id="web-agent")
+        True
+    """
+    # Admin always matches
+    if user_scope.scope_type == "admin":
+        return True
+
+    # Unknown scopes don't match anything
+    if user_scope.scope_type == "unknown" or required_scope.scope_type == "unknown":
+        return False
+
+    # Resource type must match
+    if user_scope.resource != required_scope.resource:
+        return False
+
+    # Action must match
+    if user_scope.action != required_scope.action:
+        return False
+
+    # If required scope has a resource_id, check it
+    if required_scope.resource_id:
+        # User has wildcard resource access
+        if user_scope.is_wildcard_resource:
+            return True
+        # User has global resource access (no resource_id in user scope)
+        if not user_scope.resource_id:
+            return True
+        # User has specific resource access - must match
+        return user_scope.resource_id == resource_id
+
+    # Required scope is global (no resource_id), user scope matches if:
+    # - User has global scope (no resource_id), OR
+    # - User has wildcard resource scope
+    return not user_scope.resource_id or user_scope.is_wildcard_resource
+
+
+def has_required_scopes(
+    user_scopes: List[str],
+    required_scopes: List[str],
+    resource_type: Optional[str] = None,
+    resource_id: Optional[str] = None,
+    admin_scope: Optional[str] = None,
+) -> bool:
+    """
+    Check if user has all required scopes.
+
+    Args:
+        user_scopes: List of scope strings the user has
+        required_scopes: List of scope strings required
+        resource_type: Type of resource being accessed ("agents", "teams", "workflows")
+        resource_id: Specific resource ID being accessed
+        admin_scope: The scope string that grants admin access (default: "agent_os:admin")
+
+    Returns:
+        True if user has all required scopes
+
+    Examples:
+        >>> has_required_scopes(
+        ...     ["agents:read"],
+        ...     ["agents:read"],
+        ... )
+        True
+
+        >>> has_required_scopes(
+        ...     ["agents:web-agent:run"],
+        ...     ["agents:run"],
+        ...     resource_type="agents",
+        ...     resource_id="web-agent"
+        ... )
+        True
+
+        >>> has_required_scopes(
+        ...     ["agents:*:run"],
+        ...     ["agents:run"],
+        ...     resource_type="agents",
+        ...     resource_id="any-agent"
+        ... )
+        True
+    """
+    if not required_scopes:
+        return True
+
+    # Parse user scopes once
+    parsed_user_scopes = [parse_scope(scope, admin_scope=admin_scope) for scope in user_scopes]
+
+    # Check for admin scope
+    if any(s.scope_type == "admin" for s in parsed_user_scopes):
+        return True
+
+    # Check each required scope
+    for required_scope_str in required_scopes:
+        parts = required_scope_str.split(":")
+        if len(parts) == 2:
+            resource, action = parts
+            # Build the required scope based on context
+            if resource_id and resource_type:
+                # Per-resource scope required
+                full_required_scope = f"{resource_type}:<resource-id>:{action}"
+            else:
+                # Global resource scope required
+                full_required_scope = required_scope_str
+
+            required = parse_scope(full_required_scope, admin_scope=admin_scope)
+        else:
+            required = parse_scope(required_scope_str, admin_scope=admin_scope)
+
+        scope_matched = False
+        for user_scope in parsed_user_scopes:
+            if matches_scope(user_scope, required, resource_id=resource_id):
+                scope_matched = True
+                break
+
+        if not scope_matched:
+            return False
+
+    return True
+
+
+def get_accessible_resource_ids(
+    user_scopes: List[str],
+    resource_type: str,
+    admin_scope: Optional[str] = None,
+) -> Set[str]:
+    """
+    Get the set of resource IDs the user has access to.
+
+    Args:
+        user_scopes: List of scope strings the user has
+        resource_type: Type of resource ("agents", "teams", "workflows")
+        admin_scope: The scope string that grants admin access (default: "agent_os:admin")
+
+    Returns:
+        Set of resource IDs the user can access. Returns {"*"} for wildcard access.
+
+    Examples:
+        >>> get_accessible_resource_ids(
+        ...     ["agents:agent-1:read", "agents:agent-2:read"],
+        ...     "agents"
+        ... )
+        {'agent-1', 'agent-2'}
+
+        >>> get_accessible_resource_ids(["agents:*:read"], "agents")
+        {'*'}
+
+        >>> get_accessible_resource_ids(["agents:read"], "agents")
+        {'*'}
+
+        >>> get_accessible_resource_ids(["admin"], "agents")
+        {'*'}
+    """
+    parsed_scopes = [parse_scope(scope, admin_scope=admin_scope) for scope in user_scopes]
+
+    # Check for admin or global wildcard access
+    for scope in parsed_scopes:
+        if scope.scope_type == "admin":
+            return {"*"}
+
+        # Check if resource type matches
+        if scope.resource == resource_type:
+            # Global resource scope (no resource_id) grants access to all
+            if not scope.resource_id and scope.action in ["read", "run"]:
+                return {"*"}
+            # Wildcard resource scope grants access to all
+            if scope.is_wildcard_resource and scope.action in ["read", "run"]:
+                return {"*"}
+
+    # Collect specific resource IDs
+    accessible_ids: Set[str] = set()
+    for scope in parsed_scopes:
+        # Check if resource type matches
+        if scope.resource == resource_type:
+            # Specific resource ID
+            if scope.resource_id and not scope.is_wildcard_resource and scope.action in ["read", "run"]:
+                accessible_ids.add(scope.resource_id)
+
+    return accessible_ids
+
+
+def get_default_scope_mappings() -> Dict[str, List[str]]:
+    """
+    Get default scope mappings for AgentOS endpoints.
+
+    Returns a dictionary mapping route patterns (with HTTP methods) to required scope templates.
+    Format: "METHOD /path/pattern": ["resource:action"]
+    """
+    return {
+        # System endpoints
+        "GET /config": ["system:read"],
+        "GET /models": ["system:read"],
+        # Agent endpoints
+        "GET /agents": ["agents:read"],
+        "GET /agents/*": ["agents:read"],
+        "POST /agents": ["agents:write"],
+        "PATCH /agents/*": ["agents:write"],
+        "DELETE /agents/*": ["agents:delete"],
+        "POST /agents/*/runs": ["agents:run"],
+        "POST /agents/*/runs/*/continue": ["agents:run"],
+        "POST /agents/*/runs/*/cancel": ["agents:run"],
+        # Team endpoints
+        "GET /teams": ["teams:read"],
+        "GET /teams/*": ["teams:read"],
+        "POST /teams": ["teams:write"],
+        "PATCH /teams/*": ["teams:write"],
+        "DELETE /teams/*": ["teams:delete"],
+        "POST /teams/*/runs": ["teams:run"],
+        "POST /teams/*/runs/*/continue": ["teams:run"],
+        "POST /teams/*/runs/*/cancel": ["teams:run"],
+        # Workflow endpoints
+        "GET /workflows": ["workflows:read"],
+        "GET /workflows/*": ["workflows:read"],
+        "POST /workflows": ["workflows:write"],
+        "PATCH /workflows/*": ["workflows:write"],
+        "DELETE /workflows/*": ["workflows:delete"],
+        "POST /workflows/*/runs": ["workflows:run"],
+        "POST /workflows/*/runs/*/continue": ["workflows:run"],
+        "POST /workflows/*/runs/*/cancel": ["workflows:run"],
+        # Session endpoints
+        "GET /sessions": ["sessions:read"],
+        "GET /sessions/*": ["sessions:read"],
+        "POST /sessions": ["sessions:write"],
+        "POST /sessions/*/rename": ["sessions:write"],
+        "PATCH /sessions/*": ["sessions:write"],
+        "DELETE /sessions": ["sessions:delete"],
+        "DELETE /sessions/*": ["sessions:delete"],
+        # Memory endpoints
+        "GET /memories": ["memories:read"],
+        "GET /memories/*": ["memories:read"],
+        "GET /memory_topics": ["memories:read"],
+        "GET /user_memory_stats": ["memories:read"],
+        "POST /memories": ["memories:write"],
+        "PATCH /memories/*": ["memories:write"],
+        "DELETE /memories": ["memories:delete"],
+        "DELETE /memories/*": ["memories:delete"],
+        "POST /optimize-memories": ["memories:write"],
+        # Knowledge endpoints
+        "GET /knowledge/content": ["knowledge:read"],
+        "GET /knowledge/content/*": ["knowledge:read"],
+        "GET /knowledge/config": ["knowledge:read"],
+        "POST /knowledge/content": ["knowledge:write"],
+        "PATCH /knowledge/content/*": ["knowledge:write"],
+        "POST /knowledge/search": ["knowledge:read"],
+        "DELETE /knowledge/content": ["knowledge:delete"],
+        "DELETE /knowledge/content/*": ["knowledge:delete"],
+        # Metrics endpoints
+        "GET /metrics": ["metrics:read"],
+        "POST /metrics/refresh": ["metrics:write"],
+        # Evaluation endpoints
+        "GET /eval-runs": ["evals:read"],
+        "GET /eval-runs/*": ["evals:read"],
+        "POST /eval-runs": ["evals:write"],
+        "PATCH /eval-runs/*": ["evals:write"],
+        "DELETE /eval-runs": ["evals:delete"],
+        # Trace endpoints
+        "GET /traces": ["traces:read"],
+        "GET /traces/*": ["traces:read"],
+        "GET /trace_session_stats": ["traces:read"],
+    }
+
+
+def get_scope_value(scope: AgentOSScope) -> str:
+    """
+    Get the string value of a scope.
+
+    Args:
+        scope: The AgentOSScope enum value
+
+    Returns:
+        The string value of the scope
+
+    Example:
+        >>> get_scope_value(AgentOSScope.ADMIN)
+        'admin'
+    """
+    return scope.value
+
+
+def get_all_scopes() -> list[str]:
+    """
+    Get a list of all available scope strings.
+
+    Returns:
+        List of all scope string values
+
+    Example:
+        >>> scopes = get_all_scopes()
+        >>> 'admin' in scopes
+        True
+    """
+    return [scope.value for scope in AgentOSScope]

agno/os/utils.py

@@ -26,12 +26,21 @@ from agno.workflow.workflow import Workflow
 
 async def get_request_kwargs(request: Request, endpoint_func: Callable) -> Dict[str, Any]:
     """Given a Request and an endpoint function, return a dictionary with all extra form data fields.
+
     Args:
         request: The FastAPI Request object
         endpoint_func: The function exposing the endpoint that received the request
 
+    Supported form parameters:
+        - session_state: JSON string of session state dict
+        - dependencies: JSON string of dependencies dict
+        - metadata: JSON string of metadata dict
+        - knowledge_filters: JSON string of knowledge filters
+        - output_schema: JSON schema string (converted to Pydantic model by default)
+        - use_json_schema: If "true", keeps output_schema as dict instead of converting to Pydantic model
+
     Returns:
-        A dictionary of kwargs
+        A dictionary of kwargs to pass to Agent/Team run methods
     """
     import inspect
 
@@ -101,15 +110,25 @@ async def get_request_kwargs(request: Request, endpoint_func: Callable) -> Dict[
             kwargs.pop("knowledge_filters")
             log_warning(f"Invalid FilterExpr in knowledge_filters: {e}")
 
-    # Handle output_schema - convert JSON schema to dynamic Pydantic model
+    # Handle output_schema - convert JSON schema to Pydantic model or keep as dict
+    # use_json_schema is a control flag consumed here (not passed to Agent/Team)
+    # When true, output_schema stays as dict for direct JSON output
+    use_json_schema = kwargs.pop("use_json_schema", False)
+    if isinstance(use_json_schema, str):
+        use_json_schema = use_json_schema.lower() == "true"
+
     if output_schema := kwargs.get("output_schema"):
         try:
             if isinstance(output_schema, str):
-                from agno.os.utils import json_schema_to_pydantic_model
-
                 schema_dict = json.loads(output_schema)
-                dynamic_model = json_schema_to_pydantic_model(schema_dict)
-                kwargs["output_schema"] = dynamic_model
+
+                if use_json_schema:
+                    # Keep as dict schema for direct JSON output
+                    kwargs["output_schema"] = schema_dict
+                else:
+                    # Convert to Pydantic model (default behavior)
+                    dynamic_model = json_schema_to_pydantic_model(schema_dict)
+                    kwargs["output_schema"] = dynamic_model
         except json.JSONDecodeError:
             kwargs.pop("output_schema")
             log_warning(f"Invalid output_schema JSON: {output_schema}")
@@ -281,56 +300,45 @@ def get_session_name(session: Dict[str, Any]) -> str:
     if session_data is not None and session_data.get("session_name") is not None:
         return session_data["session_name"]
 
-    # Otherwise use the original user message
-    else:
-        runs = session.get("runs", []) or []
-
-        # For teams, identify the first Team run and avoid using the first member's run
-        if session.get("session_type") == "team":
-            run = None
-            for r in runs:
-                # If agent_id is not present, it's a team run
-                if not r.get("agent_id"):
-                    run = r
-                    break
-
-            # Fallback to first run if no team run found
-            if run is None and runs:
-                run = runs[0]
-
-        elif session.get("session_type") == "workflow":
-            try:
-                workflow_run = runs[0]
-                workflow_input = workflow_run.get("input")
-                if isinstance(workflow_input, str):
-                    return workflow_input
-                elif isinstance(workflow_input, dict):
-                    try:
-                        import json
-
-                        return json.dumps(workflow_input)
-                    except (TypeError, ValueError):
-                        pass
-
-                workflow_name = session.get("workflow_data", {}).get("name")
-                return f"New {workflow_name} Session" if workflow_name else ""
-            except (KeyError, IndexError, TypeError):
-                return ""
-
-        # For agents, use the first run
-        else:
-            run = runs[0] if runs else None
+    runs = session.get("runs", []) or []
+    session_type = session.get("session_type")
 
-        if run is None:
+    # Handle workflows separately
+    if session_type == "workflow":
+        if not runs:
             return ""
+        workflow_run = runs[0]
+        workflow_input = workflow_run.get("input")
+        if isinstance(workflow_input, str):
+            return workflow_input
+        elif isinstance(workflow_input, dict):
+            try:
+                return json.dumps(workflow_input)
+            except (TypeError, ValueError):
+                pass
+        workflow_name = session.get("workflow_data", {}).get("name")
+        return f"New {workflow_name} Session" if workflow_name else ""
+
+    # For team, filter to team runs (runs without agent_id); for agents, use all runs
+    if session_type == "team":
+        runs_to_check = [r for r in runs if not r.get("agent_id")]
+    else:
+        runs_to_check = runs
+
+    # Find the first user message across runs
+    for r in runs_to_check:
+        if r is None:
+            continue
+        run_dict = r if isinstance(r, dict) else r.to_dict()
+
+        for message in run_dict.get("messages") or []:
+            if message.get("role") == "user" and message.get("content"):
+                return message["content"]
 
-        if not isinstance(run, dict):
-            run = run.to_dict()
+        run_input = r.get("input")
+        if run_input is not None:
+            return run_input.get("input_content")
 
-        if run and run.get("messages"):
-            for message in run["messages"]:
-                if message["role"] == "user":
-                    return message["content"]
     return ""
 
 
@@ -550,6 +558,31 @@ def _generate_schema_from_params(params: Dict[str, Any]) -> Dict[str, Any]:
     return schema
 
 
+def resolve_origins(user_origins: Optional[List[str]] = None, default_origins: Optional[List[str]] = None) -> List[str]:
+    """
+    Get CORS origins - user-provided origins override defaults.
+
+    Args:
+        user_origins: Optional list of user-provided CORS origins
+
+    Returns:
+        List of allowed CORS origins (user-provided if set, otherwise defaults)
+    """
+    # User-provided origins override defaults
+    if user_origins:
+        return user_origins
+
+    # Default Agno domains
+    return default_origins or [
+        "http://localhost:3000",
+        "https://agno.com",
+        "https://www.agno.com",
+        "https://app.agno.com",
+        "https://os-stg.agno.com",
+        "https://os.agno.com",
+    ]
+
+
 def update_cors_middleware(app: FastAPI, new_origins: list):
     existing_origins: List[str] = []
 
@@ -837,7 +870,7 @@ def _get_python_type_from_json_schema(field_schema: Dict[str, Any], field_name:
         # Unknown or unspecified type - fallback to Any
         if json_type:
             logger.warning(f"Unknown JSON schema type '{json_type}' for field '{field_name}', using Any")
-        return Any
+        return Any  # type: ignore
 
 
 def json_schema_to_pydantic_model(schema: Dict[str, Any]) -> Type[BaseModel]: