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

agno/os/auth.py

@@ -0,0 +1,244 @@
+from typing import List, Set
+
+from fastapi import Depends, HTTPException, Request
+from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
+
+from agno.os.scopes import get_accessible_resource_ids
+from agno.os.settings import AgnoAPISettings
+
+# Create a global HTTPBearer instance
+security = HTTPBearer(auto_error=False)
+
+
+def get_authentication_dependency(settings: AgnoAPISettings):
+    """
+    Create an authentication dependency function for FastAPI routes.
+
+    Args:
+        settings: The API settings containing the security key
+
+    Returns:
+        A dependency function that can be used with FastAPI's Depends()
+    """
+
+    async def auth_dependency(credentials: HTTPAuthorizationCredentials = Depends(security)) -> bool:
+        # If no security key is set, skip authentication entirely
+        if not settings or not settings.os_security_key:
+            return True
+
+        # If security is enabled but no authorization header provided, fail
+        if not credentials:
+            raise HTTPException(status_code=401, detail="Authorization header required")
+
+        token = credentials.credentials
+
+        # Verify the token
+        if token != settings.os_security_key:
+            raise HTTPException(status_code=401, detail="Invalid authentication token")
+
+        return True
+
+    return auth_dependency
+
+
+def validate_websocket_token(token: str, settings: AgnoAPISettings) -> bool:
+    """
+    Validate a bearer token for WebSocket authentication (legacy os_security_key method).
+
+    Args:
+        token: The bearer token to validate
+        settings: The API settings containing the security key
+
+    Returns:
+        True if the token is valid or authentication is disabled, False otherwise
+    """
+    # If no security key is set, skip authentication entirely
+    if not settings or not settings.os_security_key:
+        return True
+
+    # Verify the token matches the configured security key
+    return token == settings.os_security_key
+
+
+def get_accessible_resources(request: Request, resource_type: str) -> Set[str]:
+    """
+    Get the set of resource IDs the user has access to based on their scopes.
+
+    This function is used to filter lists of resources (agents, teams, workflows)
+    based on the user's scopes from their JWT token.
+
+    Args:
+        request: The FastAPI request object (contains request.state.scopes)
+        resource_type: Type of resource ("agents", "teams", "workflows")
+
+    Returns:
+        Set of resource IDs the user can access. Returns {"*"} for wildcard access.
+
+    Usage:
+        accessible_ids = get_accessible_resources(request, "agents")
+        if "*" not in accessible_ids:
+            agents = [a for a in agents if a.id in accessible_ids]
+
+    Examples:
+        >>> # User with specific agent access
+        >>> # Token scopes: ["agent-os:my-os:agents:my-agent:read"]
+        >>> get_accessible_resources(request, "agents")
+        {'my-agent'}
+
+        >>> # User with wildcard access
+        >>> # Token scopes: ["agent-os:my-os:agents:*:read"] or ["admin"]
+        >>> get_accessible_resources(request, "agents")
+        {'*'}
+
+        >>> # User with agent-os level access (global resource scope)
+        >>> # Token scopes: ["agent-os:my-os:agents:read"]
+        >>> get_accessible_resources(request, "agents")
+        {'*'}
+    """
+    # Check if accessible_resource_ids is already cached in request state (set by JWT middleware)
+    # This happens when user doesn't have global scope but has specific resource scopes
+    cached_ids = getattr(request.state, "accessible_resource_ids", None)
+    if cached_ids is not None:
+        return cached_ids
+
+    # Get user's scopes from request state (set by JWT middleware)
+    user_scopes = getattr(request.state, "scopes", [])
+
+    # Get accessible resource IDs
+    accessible_ids = get_accessible_resource_ids(user_scopes=user_scopes, resource_type=resource_type)
+
+    return accessible_ids
+
+
+def filter_resources_by_access(request: Request, resources: List, resource_type: str) -> List:
+    """
+    Filter a list of resources based on user's access permissions.
+
+    Args:
+        request: The FastAPI request object
+        resources: List of resource objects (agents, teams, or workflows) with 'id' attribute
+        resource_type: Type of resource ("agents", "teams", "workflows")
+
+    Returns:
+        Filtered list of resources the user has access to
+
+    Usage:
+        agents = filter_resources_by_access(request, all_agents, "agents")
+        teams = filter_resources_by_access(request, all_teams, "teams")
+        workflows = filter_resources_by_access(request, all_workflows, "workflows")
+
+    Examples:
+        >>> # User with specific access
+        >>> agents = [Agent(id="agent-1"), Agent(id="agent-2"), Agent(id="agent-3")]
+        >>> # Token scopes: ["agent-os:my-os:agents:agent-1:read", "agent-os:my-os:agents:agent-2:read"]
+        >>> filter_resources_by_access(request, agents, "agents")
+        [Agent(id="agent-1"), Agent(id="agent-2")]
+
+        >>> # User with wildcard access
+        >>> # Token scopes: ["admin"]
+        >>> filter_resources_by_access(request, agents, "agents")
+        [Agent(id="agent-1"), Agent(id="agent-2"), Agent(id="agent-3")]
+    """
+    accessible_ids = get_accessible_resources(request, resource_type)
+
+    # Wildcard access - return all resources
+    if "*" in accessible_ids:
+        return resources
+
+    # Filter to only accessible resources
+    return [r for r in resources if r.id in accessible_ids]
+
+
+def check_resource_access(request: Request, resource_id: str, resource_type: str, action: str = "read") -> bool:
+    """
+    Check if user has access to a specific resource.
+
+    Args:
+        request: The FastAPI request object
+        resource_id: ID of the resource to check
+        resource_type: Type of resource ("agents", "teams", "workflows")
+        action: Action to check ("read", "run", etc.)
+
+    Returns:
+        True if user has access, False otherwise
+
+    Usage:
+        if not check_resource_access(request, agent_id, "agents", "run"):
+            raise HTTPException(status_code=403, detail="Access denied")
+
+    Examples:
+        >>> # Token scopes: ["agent-os:my-os:agents:my-agent:read", "agent-os:my-os:agents:my-agent:run"]
+        >>> check_resource_access(request, "my-agent", "agents", "run")
+        True
+
+        >>> check_resource_access(request, "other-agent", "agents", "run")
+        False
+    """
+    accessible_ids = get_accessible_resources(request, resource_type)
+
+    # Wildcard access grants all permissions
+    if "*" in accessible_ids:
+        return True
+
+    # Check if user has access to this specific resource
+    return resource_id in accessible_ids
+
+
+def require_resource_access(resource_type: str, action: str, resource_id_param: str):
+    """
+    Create a dependency that checks if the user has access to a specific resource.
+
+    This dependency factory creates a FastAPI dependency that automatically checks
+    authorization when authorization is enabled. It extracts the resource ID from
+    the path parameters and verifies the user has the required access.
+
+    Args:
+        resource_type: Type of resource ("agents", "teams", "workflows")
+        action: Action to check ("read", "run")
+        resource_id_param: Name of the path parameter containing the resource ID
+
+    Returns:
+        A dependency function for use with FastAPI's Depends()
+
+    Usage:
+        @router.post("/agents/{agent_id}/runs")
+        async def create_agent_run(
+            agent_id: str,
+            request: Request,
+            _: None = Depends(require_resource_access("agents", "run", "agent_id")),
+        ):
+            ...
+
+        @router.get("/agents/{agent_id}")
+        async def get_agent(
+            agent_id: str,
+            request: Request,
+            _: None = Depends(require_resource_access("agents", "read", "agent_id")),
+        ):
+            ...
+
+    Examples:
+        >>> # Creates dependency for checking agent run access
+        >>> dep = require_resource_access("agents", "run", "agent_id")
+
+        >>> # Creates dependency for checking team read access
+        >>> dep = require_resource_access("teams", "read", "team_id")
+    """
+    # Map resource_type to singular form for error messages
+    resource_singular = {
+        "agents": "agent",
+        "teams": "team",
+        "workflows": "workflow",
+    }.get(resource_type, resource_type.rstrip("s"))
+
+    async def dependency(request: Request):
+        # Only check authorization if it's enabled
+        if not getattr(request.state, "authorization_enabled", False):
+            return
+
+        # Get the resource_id from path parameters
+        resource_id = request.path_params.get(resource_id_param)
+        if resource_id and not check_resource_access(request, resource_id, resource_type, action):
+            raise HTTPException(status_code=403, detail=f"Access denied to {action} this {resource_singular}")
+
+    return dependency

agno/os/config.py

@@ -0,0 +1,126 @@
+"""Schemas related to the AgentOS configuration"""
+
+from typing import Generic, List, Optional, TypeVar
+
+from pydantic import BaseModel, field_validator
+
+
+class AuthorizationConfig(BaseModel):
+    """Configuration for the JWT middleware"""
+
+    verification_keys: Optional[List[str]] = None
+    jwks_file: Optional[str] = None
+    algorithm: Optional[str] = None
+    verify_audience: Optional[bool] = None
+
+
+class EvalsDomainConfig(BaseModel):
+    """Configuration for the Evals domain of the AgentOS"""
+
+    display_name: Optional[str] = None
+    available_models: Optional[List[str]] = None
+
+
+class SessionDomainConfig(BaseModel):
+    """Configuration for the Session domain of the AgentOS"""
+
+    display_name: Optional[str] = None
+
+
+class KnowledgeDomainConfig(BaseModel):
+    """Configuration for the Knowledge domain of the AgentOS"""
+
+    display_name: Optional[str] = None
+
+
+class MetricsDomainConfig(BaseModel):
+    """Configuration for the Metrics domain of the AgentOS"""
+
+    display_name: Optional[str] = None
+
+
+class MemoryDomainConfig(BaseModel):
+    """Configuration for the Memory domain of the AgentOS"""
+
+    display_name: Optional[str] = None
+
+
+class TracesDomainConfig(BaseModel):
+    """Configuration for the Traces domain of the AgentOS"""
+
+    display_name: Optional[str] = None
+
+
+DomainConfigType = TypeVar("DomainConfigType")
+
+
+class DatabaseConfig(BaseModel, Generic[DomainConfigType]):
+    """Configuration for a domain when used with the contextual database"""
+
+    db_id: str
+    domain_config: Optional[DomainConfigType] = None
+    tables: Optional[List[str]] = None
+
+
+class EvalsConfig(EvalsDomainConfig):
+    """Configuration for the Evals domain of the AgentOS"""
+
+    dbs: Optional[List[DatabaseConfig[EvalsDomainConfig]]] = None
+
+
+class SessionConfig(SessionDomainConfig):
+    """Configuration for the Session domain of the AgentOS"""
+
+    dbs: Optional[List[DatabaseConfig[SessionDomainConfig]]] = None
+
+
+class MemoryConfig(MemoryDomainConfig):
+    """Configuration for the Memory domain of the AgentOS"""
+
+    dbs: Optional[List[DatabaseConfig[MemoryDomainConfig]]] = None
+
+
+class KnowledgeConfig(KnowledgeDomainConfig):
+    """Configuration for the Knowledge domain of the AgentOS"""
+
+    dbs: Optional[List[DatabaseConfig[KnowledgeDomainConfig]]] = None
+
+
+class MetricsConfig(MetricsDomainConfig):
+    """Configuration for the Metrics domain of the AgentOS"""
+
+    dbs: Optional[List[DatabaseConfig[MetricsDomainConfig]]] = None
+
+
+class TracesConfig(TracesDomainConfig):
+    """Configuration for the Traces domain of the AgentOS"""
+
+    dbs: Optional[List[DatabaseConfig[TracesDomainConfig]]] = None
+
+
+class ChatConfig(BaseModel):
+    """Configuration for the Chat page of the AgentOS"""
+
+    quick_prompts: dict[str, list[str]]
+
+    # Limit the number of quick prompts to 3 (per agent/team/workflow)
+    @field_validator("quick_prompts")
+    @classmethod
+    def limit_lists(cls, v):
+        for key, lst in v.items():
+            if len(lst) > 3:
+                raise ValueError(f"Too many quick prompts for '{key}', maximum allowed is 3")
+        return v
+
+
+class AgentOSConfig(BaseModel):
+    """General configuration for an AgentOS instance"""
+
+    available_models: Optional[List[str]] = None
+    chat: Optional[ChatConfig] = None
+    evals: Optional[EvalsConfig] = None
+    knowledge: Optional[KnowledgeConfig] = None
+    memory: Optional[MemoryConfig] = None
+    session: Optional[SessionConfig] = None
+    metrics: Optional[MetricsConfig] = None
+    traces: Optional[TracesConfig] = None

agno/os/interfaces/__init__.py

@@ -0,0 +1 @@
+

agno/os/interfaces/a2a/__init__.py

@@ -0,0 +1,3 @@
+from agno.os.interfaces.a2a.a2a import A2A
+
+__all__ = ["A2A"]

agno/os/interfaces/a2a/a2a.py

@@ -0,0 +1,42 @@
+"""Main class for the A2A app, used to expose an Agno Agent, Team, or Workflow in an A2A compatible format."""
+
+from typing import Optional
+
+from fastapi.routing import APIRouter
+from typing_extensions import List
+
+from agno.agent import Agent
+from agno.os.interfaces.a2a.router import attach_routes
+from agno.os.interfaces.base import BaseInterface
+from agno.team import Team
+from agno.workflow import Workflow
+
+
+class A2A(BaseInterface):
+    type = "a2a"
+
+    router: APIRouter
+
+    def __init__(
+        self,
+        agents: Optional[List[Agent]] = None,
+        teams: Optional[List[Team]] = None,
+        workflows: Optional[List[Workflow]] = None,
+        prefix: str = "/a2a",
+        tags: Optional[List[str]] = None,
+    ):
+        self.agents = agents
+        self.teams = teams
+        self.workflows = workflows
+        self.prefix = prefix
+        self.tags = tags or ["A2A"]
+
+        if not (self.agents or self.teams or self.workflows):
+            raise ValueError("Agents, Teams, or Workflows are required to setup the A2A interface.")
+
+    def get_router(self, **kwargs) -> APIRouter:
+        self.router = APIRouter(prefix=self.prefix, tags=self.tags)  # type: ignore
+
+        self.router = attach_routes(router=self.router, agents=self.agents, teams=self.teams, workflows=self.workflows)
+
+        return self.router

agno/os/interfaces/a2a/router.py

@@ -0,0 +1,249 @@
+"""Async router handling exposing an Agno Agent or Team in an A2A compatible format."""
+
+from typing import Optional, Union
+from uuid import uuid4
+
+from fastapi import HTTPException, Request
+from fastapi.responses import StreamingResponse
+from fastapi.routing import APIRouter
+from typing_extensions import List
+
+try:
+    from a2a.types import SendMessageSuccessResponse, Task, TaskState, TaskStatus
+except ImportError as e:
+    raise ImportError("`a2a` not installed. Please install it with `pip install -U a2a-sdk`") from e
+
+from agno.agent import Agent
+from agno.os.interfaces.a2a.utils import (
+    map_a2a_request_to_run_input,
+    map_run_output_to_a2a_task,
+    stream_a2a_response_with_error_handling,
+)
+from agno.os.utils import get_agent_by_id, get_request_kwargs, get_team_by_id, get_workflow_by_id
+from agno.team import Team
+from agno.workflow import Workflow
+
+
+def attach_routes(
+    router: APIRouter,
+    agents: Optional[List[Agent]] = None,
+    teams: Optional[List[Team]] = None,
+    workflows: Optional[List[Workflow]] = None,
+) -> APIRouter:
+    if agents is None and teams is None and workflows is None:
+        raise ValueError("Agents, Teams, or Workflows are required to setup the A2A interface.")
+
+    @router.post(
+        "/message/send",
+        operation_id="send_message",
+        name="send_message",
+        description="Send a message to an Agno Agent, Team, or Workflow. "
+        "The Agent, Team or Workflow is identified via the 'agentId' field in params.message or X-Agent-ID header. "
+        "Optional: Pass user ID via X-User-ID header (recommended) or 'userId' in params.message.metadata.",
+        response_model_exclude_none=True,
+        responses={
+            200: {
+                "description": "Message sent successfully",
+                "content": {
+                    "application/json": {
+                        "example": {
+                            "jsonrpc": "2.0",
+                            "id": "request-123",
+                            "result": {
+                                "task": {
+                                    "id": "task-456",
+                                    "context_id": "context-789",
+                                    "status": "completed",
+                                    "history": [
+                                        {
+                                            "message_id": "msg-1",
+                                            "role": "agent",
+                                            "parts": [{"kind": "text", "text": "Response from agent"}],
+                                        }
+                                    ],
+                                }
+                            },
+                        }
+                    }
+                },
+            },
+            400: {"description": "Invalid request or unsupported method"},
+            404: {"description": "Agent, Team, or Workflow not found"},
+        },
+        response_model=SendMessageSuccessResponse,
+    )
+    async def a2a_send_message(request: Request):
+        request_body = await request.json()
+        kwargs = await get_request_kwargs(request, a2a_send_message)
+
+        # 1. Get the Agent, Team, or Workflow to run
+        agent_id = request_body.get("params", {}).get("message", {}).get("agentId") or request.headers.get("X-Agent-ID")
+        if not agent_id:
+            raise HTTPException(
+                status_code=400,
+                detail="Entity ID required. Provide it via 'agentId' in params.message or 'X-Agent-ID' header.",
+            )
+        entity: Optional[Union[Agent, Team, Workflow]] = None
+        if agents:
+            entity = get_agent_by_id(agent_id, agents)
+        if not entity and teams:
+            entity = get_team_by_id(agent_id, teams)
+        if not entity and workflows:
+            entity = get_workflow_by_id(agent_id, workflows)
+        if entity is None:
+            raise HTTPException(status_code=404, detail=f"Agent, Team, or Workflow with ID '{agent_id}' not found")
+
+        # 2. Map the request to our run_input and run variables
+        run_input = await map_a2a_request_to_run_input(request_body, stream=False)
+        context_id = request_body.get("params", {}).get("message", {}).get("contextId")
+        user_id = request.headers.get("X-User-ID")
+        if not user_id:
+            user_id = request_body.get("params", {}).get("message", {}).get("metadata", {}).get("userId")
+
+        # 3. Run the agent, team, or workflow
+        try:
+            if isinstance(entity, Workflow):
+                response = await entity.arun(
+                    input=run_input.input_content,
+                    images=list(run_input.images) if run_input.images else None,
+                    videos=list(run_input.videos) if run_input.videos else None,
+                    audio=list(run_input.audios) if run_input.audios else None,
+                    files=list(run_input.files) if run_input.files else None,
+                    session_id=context_id,
+                    user_id=user_id,
+                    **kwargs,
+                )
+            else:
+                response = await entity.arun(
+                    input=run_input.input_content,
+                    images=run_input.images,
+                    videos=run_input.videos,
+                    audio=run_input.audios,
+                    files=run_input.files,
+                    session_id=context_id,
+                    user_id=user_id,
+                    **kwargs,
+                )
+
+            # 4. Send the response
+            a2a_task = map_run_output_to_a2a_task(response)
+            return SendMessageSuccessResponse(
+                id=request_body.get("id", "unknown"),
+                result=a2a_task,
+            )
+
+        # Handle all critical errors
+        except Exception as e:
+            from a2a.types import Message as A2AMessage
+            from a2a.types import Part, Role, TextPart
+
+            error_message = A2AMessage(
+                message_id=str(uuid4()),
+                role=Role.agent,
+                parts=[Part(root=TextPart(text=f"Error: {str(e)}"))],
+                context_id=context_id or str(uuid4()),
+            )
+            failed_task = Task(
+                id=str(uuid4()),
+                context_id=context_id or str(uuid4()),
+                status=TaskStatus(state=TaskState.failed),
+                history=[error_message],
+            )
+
+            return SendMessageSuccessResponse(
+                id=request_body.get("id", "unknown"),
+                result=failed_task,
+            )
+
+    @router.post(
+        "/message/stream",
+        operation_id="stream_message",
+        name="stream_message",
+        description="Stream a message to an Agno Agent, Team, or Workflow."
+        "The Agent, Team or Workflow is identified via the 'agentId' field in params.message or X-Agent-ID header. "
+        "Optional: Pass user ID via X-User-ID header (recommended) or 'userId' in params.message.metadata. "
+        "Returns real-time updates as newline-delimited JSON (NDJSON).",
+        response_model_exclude_none=True,
+        responses={
+            200: {
+                "description": "Streaming response with task updates",
+                "content": {
+                    "application/x-ndjson": {
+                        "example": '{"jsonrpc":"2.0","id":"request-123","result":{"taskId":"task-456","status":"working"}}\n'
+                        '{"jsonrpc":"2.0","id":"request-123","result":{"messageId":"msg-1","role":"agent","parts":[{"kind":"text","text":"Response"}]}}\n'
+                    }
+                },
+            },
+            400: {"description": "Invalid request or unsupported method"},
+            404: {"description": "Agent, Team, or Workflow not found"},
+        },
+    )
+    async def a2a_stream_message(request: Request):
+        request_body = await request.json()
+        kwargs = await get_request_kwargs(request, a2a_stream_message)
+
+        # 1. Get the Agent, Team, or Workflow to run
+        agent_id = request_body.get("params", {}).get("message", {}).get("agentId")
+        if not agent_id:
+            agent_id = request.headers.get("X-Agent-ID")
+        if not agent_id:
+            raise HTTPException(
+                status_code=400,
+                detail="Entity ID required. Provide 'agentId' in params.message or 'X-Agent-ID' header.",
+            )
+        entity: Optional[Union[Agent, Team, Workflow]] = None
+        if agents:
+            entity = get_agent_by_id(agent_id, agents)
+        if not entity and teams:
+            entity = get_team_by_id(agent_id, teams)
+        if not entity and workflows:
+            entity = get_workflow_by_id(agent_id, workflows)
+        if entity is None:
+            raise HTTPException(status_code=404, detail=f"Agent, Team, or Workflow with ID '{agent_id}' not found")
+
+        # 2. Map the request to our run_input and run variables
+        run_input = await map_a2a_request_to_run_input(request_body, stream=True)
+        context_id = request_body.get("params", {}).get("message", {}).get("contextId")
+        user_id = request.headers.get("X-User-ID")
+        if not user_id:
+            user_id = request_body.get("params", {}).get("message", {}).get("metadata", {}).get("userId")
+
+        # 3. Run the Agent, Team, or Workflow and stream the response
+        try:
+            if isinstance(entity, Workflow):
+                event_stream = entity.arun(
+                    input=run_input.input_content,
+                    images=list(run_input.images) if run_input.images else None,
+                    videos=list(run_input.videos) if run_input.videos else None,
+                    audio=list(run_input.audios) if run_input.audios else None,
+                    files=list(run_input.files) if run_input.files else None,
+                    session_id=context_id,
+                    user_id=user_id,
+                    stream=True,
+                    stream_events=True,
+                    **kwargs,
+                )
+            else:
+                event_stream = entity.arun(  # type: ignore[assignment]
+                    input=run_input.input_content,
+                    images=run_input.images,
+                    videos=run_input.videos,
+                    audio=run_input.audios,
+                    files=run_input.files,
+                    session_id=context_id,
+                    user_id=user_id,
+                    stream=True,
+                    stream_events=True,
+                    **kwargs,
+                )
+
+            # 4. Stream the response
+            return StreamingResponse(
+                stream_a2a_response_with_error_handling(event_stream=event_stream, request_id=request_body["id"]),  # type: ignore[arg-type]
+                media_type="application/x-ndjson",
+            )
+
+        except Exception as e:
+            raise HTTPException(status_code=500, detail=f"Failed to start run: {str(e)}")
+
+    return router