agno 2.3.25__py3-none-any.whl → 2.4.0__py3-none-any.whl

agno/os/routers/components/components.py

@@ -0,0 +1,466 @@
+import logging
+import time
+from typing import Any, Dict, List, Optional, Union
+
+from fastapi import APIRouter, Body, Depends, HTTPException, Path, Query
+
+from agno.db.base import AsyncBaseDb, BaseDb
+from agno.db.base import ComponentType as DbComponentType
+from agno.os.auth import get_authentication_dependency
+from agno.os.schema import (
+    BadRequestResponse,
+    ComponentConfigResponse,
+    ComponentCreate,
+    ComponentResponse,
+    ComponentType,
+    ComponentUpdate,
+    ConfigCreate,
+    ConfigUpdate,
+    InternalServerErrorResponse,
+    NotFoundResponse,
+    PaginatedResponse,
+    PaginationInfo,
+    UnauthenticatedResponse,
+    ValidationErrorResponse,
+)
+from agno.os.settings import AgnoAPISettings
+from agno.registry import Registry
+from agno.utils.log import log_error
+from agno.utils.string import generate_id_from_name
+
+logger = logging.getLogger(__name__)
+
+
+def _resolve_db_in_config(
+    config: Dict[str, Any],
+    os_db: BaseDb,
+    registry: Optional[Registry] = None,
+) -> Dict[str, Any]:
+    """
+    Resolve db reference in config by looking up in registry or OS db.
+
+    If config contains a db dict with an id, this function will:
+    1. Check if the id matches the OS db
+    2. Check if the id exists in the registry
+    3. Convert the found db to a dict for serialization
+
+    Args:
+        config: The config dict that may contain a db reference
+        os_db: The OS database instance
+        registry: Optional registry containing registered databases
+
+    Returns:
+        Updated config dict with resolved db
+    """
+    component_db = config.get("db")
+    if component_db is not None and isinstance(component_db, dict):
+        component_db_id = component_db.get("id")
+        if component_db_id is not None:
+            resolved_db = None
+            # First check if it matches the OS db
+            if component_db_id == os_db.id:
+                resolved_db = os_db
+            # Then check the registry
+            elif registry is not None:
+                resolved_db = registry.get_db(component_db_id)
+
+            # Store the full db dict for serialization
+            if resolved_db is not None:
+                config["db"] = resolved_db.to_dict()
+            else:
+                log_error(f"Could not resolve db with id: {component_db_id}")
+    elif component_db is None and "db" in config:
+        # Explicitly set to None, remove the key
+        config.pop("db", None)
+
+    return config
+
+
+def get_components_router(
+    os_db: Union[BaseDb, AsyncBaseDb],
+    settings: AgnoAPISettings = AgnoAPISettings(),
+    registry: Optional[Registry] = None,
+) -> APIRouter:
+    """Create components router."""
+    router = APIRouter(
+        dependencies=[Depends(get_authentication_dependency(settings))],
+        tags=["Components"],
+        responses={
+            400: {"description": "Bad Request", "model": BadRequestResponse},
+            401: {"description": "Unauthorized", "model": UnauthenticatedResponse},
+            404: {"description": "Not Found", "model": NotFoundResponse},
+            422: {"description": "Validation Error", "model": ValidationErrorResponse},
+            500: {"description": "Internal Server Error", "model": InternalServerErrorResponse},
+        },
+    )
+    return attach_routes(router=router, os_db=os_db, registry=registry)
+
+
+def attach_routes(
+    router: APIRouter, os_db: Union[BaseDb, AsyncBaseDb], registry: Optional[Registry] = None
+) -> APIRouter:
+    # Component routes require sync database
+    if not isinstance(os_db, BaseDb):
+        raise ValueError("Component routes require a sync database (BaseDb), not an async database.")
+    db: BaseDb = os_db  # Type narrowed after isinstance check
+
+    @router.get(
+        "/components",
+        response_model=PaginatedResponse[ComponentResponse],
+        response_model_exclude_none=True,
+        status_code=200,
+        operation_id="list_components",
+        summary="List Components",
+        description="Retrieve a paginated list of components with optional filtering by type.",
+    )
+    async def list_components(
+        component_type: Optional[ComponentType] = Query(None, description="Filter by type: agent, team, workflow"),
+        page: int = Query(1, ge=1, description="Page number"),
+        limit: int = Query(20, ge=1, le=100, description="Items per page"),
+    ) -> PaginatedResponse[ComponentResponse]:
+        try:
+            start_time_ms = time.time() * 1000
+            offset = (page - 1) * limit
+
+            components, total_count = db.list_components(
+                component_type=DbComponentType(component_type.value) if component_type else None,
+                limit=limit,
+                offset=offset,
+            )
+
+            total_pages = (total_count + limit - 1) // limit if limit > 0 else 0
+
+            return PaginatedResponse(
+                data=[ComponentResponse(**c) for c in components],
+                meta=PaginationInfo(
+                    page=page,
+                    limit=limit,
+                    total_pages=total_pages,
+                    total_count=total_count,
+                    search_time_ms=round(time.time() * 1000 - start_time_ms, 2),
+                ),
+            )
+        except Exception as e:
+            log_error(f"Error listing components: {e}")
+            raise HTTPException(status_code=500, detail="Internal server error")
+
+    @router.post(
+        "/components",
+        response_model=ComponentResponse,
+        response_model_exclude_none=True,
+        status_code=201,
+        operation_id="create_component",
+        summary="Create Component",
+        description="Create a new component (agent, team, or workflow) with initial config.",
+    )
+    async def create_component(
+        body: ComponentCreate,
+    ) -> ComponentResponse:
+        try:
+            component_id = body.component_id
+            if component_id is None:
+                component_id = generate_id_from_name(body.name)
+
+            # TODO: Create links from config
+
+            # Prepare config - ensure it's a dict and resolve db reference
+            config = body.config or {}
+            config = _resolve_db_in_config(config, db, registry)
+
+            component, _config = db.create_component_with_config(
+                component_id=component_id,
+                component_type=DbComponentType(body.component_type.value),
+                name=body.name,
+                description=body.description,
+                metadata=body.metadata,
+                config=config,
+                label=body.label,
+                stage=body.stage or "draft",
+                notes=body.notes,
+            )
+
+            return ComponentResponse(**component)
+        except ValueError as e:
+            raise HTTPException(status_code=400, detail=str(e))
+        except Exception as e:
+            log_error(f"Error creating component: {e}")
+            raise HTTPException(status_code=500, detail="Internal server error")
+
+    @router.get(
+        "/components/{component_id}",
+        response_model=ComponentResponse,
+        response_model_exclude_none=True,
+        status_code=200,
+        operation_id="get_component",
+        summary="Get Component",
+        description="Retrieve a component by ID.",
+    )
+    async def get_component(
+        component_id: str = Path(description="Component ID"),
+    ) -> ComponentResponse:
+        try:
+            component = db.get_component(component_id)
+            if component is None:
+                raise HTTPException(status_code=404, detail=f"Component {component_id} not found")
+            return ComponentResponse(**component)
+        except HTTPException:
+            raise
+        except Exception as e:
+            log_error(f"Error getting component: {e}")
+            raise HTTPException(status_code=500, detail="Internal server error")
+
+    @router.patch(
+        "/components/{component_id}",
+        response_model=ComponentResponse,
+        response_model_exclude_none=True,
+        status_code=200,
+        operation_id="update_component",
+        summary="Update Component",
+        description="Partially update a component by ID.",
+    )
+    async def update_component(
+        component_id: str = Path(description="Component ID"),
+        body: ComponentUpdate = Body(description="Component fields to update"),
+    ) -> ComponentResponse:
+        try:
+            existing = db.get_component(component_id)
+            if existing is None:
+                raise HTTPException(status_code=404, detail=f"Component {component_id} not found")
+
+            update_kwargs: Dict[str, Any] = {"component_id": component_id}
+            if body.name is not None:
+                update_kwargs["name"] = body.name
+            if body.description is not None:
+                update_kwargs["description"] = body.description
+            if body.metadata is not None:
+                update_kwargs["metadata"] = body.metadata
+            if body.component_type is not None:
+                update_kwargs["component_type"] = DbComponentType(body.component_type)
+
+            component = db.upsert_component(**update_kwargs)
+            return ComponentResponse(**component)
+        except HTTPException:
+            raise
+        except ValueError as e:
+            raise HTTPException(status_code=400, detail=str(e))
+        except Exception as e:
+            log_error(f"Error updating component: {e}")
+            raise HTTPException(status_code=500, detail="Internal server error")
+
+    @router.delete(
+        "/components/{component_id}",
+        status_code=204,
+        operation_id="delete_component",
+        summary="Delete Component",
+        description="Delete a component by ID.",
+    )
+    async def delete_component(
+        component_id: str = Path(description="Component ID"),
+    ) -> None:
+        try:
+            deleted = db.delete_component(component_id)
+            if not deleted:
+                raise HTTPException(status_code=404, detail=f"Component {component_id} not found")
+        except HTTPException:
+            raise
+        except Exception as e:
+            log_error(f"Error deleting component: {e}")
+            raise HTTPException(status_code=500, detail="Internal server error")
+
+    @router.get(
+        "/components/{component_id}/configs",
+        response_model=List[ComponentConfigResponse],
+        response_model_exclude_none=True,
+        status_code=200,
+        operation_id="list_configs",
+        summary="List Configs",
+        description="List all configs for a component.",
+    )
+    async def list_configs(
+        component_id: str = Path(description="Component ID"),
+        include_config: bool = Query(True, description="Include full config blob"),
+    ) -> List[ComponentConfigResponse]:
+        try:
+            configs = db.list_configs(component_id, include_config=include_config)
+            return [ComponentConfigResponse(**c) for c in configs]
+        except Exception as e:
+            log_error(f"Error listing configs: {e}")
+            raise HTTPException(status_code=500, detail="Internal server error")
+
+    @router.post(
+        "/components/{component_id}/configs",
+        response_model=ComponentConfigResponse,
+        response_model_exclude_none=True,
+        status_code=201,
+        operation_id="create_config",
+        summary="Create Config Version",
+        description="Create a new config version for a component.",
+    )
+    async def create_config(
+        component_id: str = Path(description="Component ID"),
+        body: ConfigCreate = Body(description="Config data"),
+    ) -> ComponentConfigResponse:
+        try:
+            # Resolve db from config if present
+            config_data = body.config or {}
+            config_data = _resolve_db_in_config(config_data, db, registry)
+
+            config = db.upsert_config(
+                component_id=component_id,
+                version=None,  # Always create new
+                config=config_data,
+                label=body.label,
+                stage=body.stage,
+                notes=body.notes,
+                links=body.links,
+            )
+            return ComponentConfigResponse(**config)
+        except ValueError as e:
+            raise HTTPException(status_code=400, detail=str(e))
+        except Exception as e:
+            log_error(f"Error creating config: {e}")
+            raise HTTPException(status_code=500, detail="Internal server error")
+
+    @router.patch(
+        "/components/{component_id}/configs/{version}",
+        response_model=ComponentConfigResponse,
+        response_model_exclude_none=True,
+        status_code=200,
+        operation_id="update_config",
+        summary="Update Draft Config",
+        description="Update an existing draft config. Cannot update published configs.",
+    )
+    async def update_config(
+        component_id: str = Path(description="Component ID"),
+        version: int = Path(description="Version number"),
+        body: ConfigUpdate = Body(description="Config fields to update"),
+    ) -> ComponentConfigResponse:
+        try:
+            # Resolve db from config if present
+            config_data = body.config
+            if config_data is not None:
+                config_data = _resolve_db_in_config(config_data, db, registry)
+
+            config = db.upsert_config(
+                component_id=component_id,
+                version=version,  # Always update existing
+                config=config_data,
+                label=body.label,
+                stage=body.stage,
+                notes=body.notes,
+                links=body.links,
+            )
+            return ComponentConfigResponse(**config)
+        except ValueError as e:
+            raise HTTPException(status_code=400, detail=str(e))
+        except Exception as e:
+            log_error(f"Error updating config: {e}")
+            raise HTTPException(status_code=500, detail="Internal server error")
+
+    @router.get(
+        "/components/{component_id}/configs/current",
+        response_model=ComponentConfigResponse,
+        response_model_exclude_none=True,
+        status_code=200,
+        operation_id="get_current_config",
+        summary="Get Current Config",
+        description="Get the current config version for a component.",
+    )
+    async def get_current_config(
+        component_id: str = Path(description="Component ID"),
+    ) -> ComponentConfigResponse:
+        try:
+            config = db.get_config(component_id)
+            if config is None:
+                raise HTTPException(status_code=404, detail=f"No current config for {component_id}")
+            return ComponentConfigResponse(**config)
+        except HTTPException:
+            raise
+        except Exception as e:
+            log_error(f"Error getting config: {e}")
+            raise HTTPException(status_code=500, detail="Internal server error")
+
+    @router.get(
+        "/components/{component_id}/configs/{version}",
+        response_model=ComponentConfigResponse,
+        response_model_exclude_none=True,
+        status_code=200,
+        operation_id="get_config",
+        summary="Get Config Version",
+        description="Get a specific config version by number.",
+    )
+    async def get_config_version(
+        component_id: str = Path(description="Component ID"),
+        version: int = Path(description="Version number"),
+    ) -> ComponentConfigResponse:
+        try:
+            config = db.get_config(component_id, version=version)
+
+            if config is None:
+                raise HTTPException(status_code=404, detail=f"Config {component_id} v{version} not found")
+            return ComponentConfigResponse(**config)
+        except HTTPException:
+            raise
+        except Exception as e:
+            log_error(f"Error getting config: {e}")
+            raise HTTPException(status_code=500, detail="Internal server error")
+
+    @router.delete(
+        "/components/{component_id}/configs/{version}",
+        status_code=204,
+        operation_id="delete_config",
+        summary="Delete Config Version",
+        description="Delete a specific draft config version. Cannot delete published or current configs.",
+    )
+    async def delete_config_version(
+        component_id: str = Path(description="Component ID"),
+        version: int = Path(description="Version number"),
+    ) -> None:
+        try:
+            # Resolve version number
+            deleted = db.delete_config(component_id, version=version)
+            if not deleted:
+                raise HTTPException(status_code=404, detail=f"Config {component_id} v{version} not found")
+        except HTTPException:
+            raise
+        except ValueError as e:
+            raise HTTPException(status_code=400, detail=str(e))
+        except Exception as e:
+            log_error(f"Error deleting config: {e}")
+            raise HTTPException(status_code=500, detail="Internal server error")
+
+    @router.post(
+        "/components/{component_id}/configs/{version}/set-current",
+        response_model=ComponentResponse,
+        response_model_exclude_none=True,
+        status_code=200,
+        operation_id="set_current_config",
+        summary="Set Current Config Version",
+        description="Set a published config version as current (for rollback).",
+    )
+    async def set_current_config(
+        component_id: str = Path(description="Component ID"),
+        version: int = Path(description="Version number"),
+    ) -> ComponentResponse:
+        try:
+            success = db.set_current_version(component_id, version=version)
+            if not success:
+                raise HTTPException(
+                    status_code=404, detail=f"Component {component_id} or config version {version} not found"
+                )
+
+            # Fetch and return updated component
+            component = db.get_component(component_id)
+            if component is None:
+                raise HTTPException(status_code=404, detail=f"Component {component_id} not found")
+
+            return ComponentResponse(**component)
+        except HTTPException:
+            raise
+        except ValueError as e:
+            raise HTTPException(status_code=400, detail=str(e))
+        except Exception as e:
+            log_error(f"Error setting current config: {e}")
+            raise HTTPException(status_code=500, detail="Internal server error")
+
+    return router

agno/os/routers/evals/schemas.py

@@ -1,5 +1,5 @@
 from dataclasses import asdict
-from datetime import datetime, timezone
+from datetime import datetime
 from typing import Any, Dict, List, Literal, Optional
 
 from pydantic import BaseModel, Field
@@ -10,6 +10,7 @@ from agno.eval.accuracy import AccuracyEval
 from agno.eval.agent_as_judge import AgentAsJudgeEval
 from agno.eval.performance import PerformanceEval
 from agno.eval.reliability import ReliabilityEval
+from agno.os.utils import to_utc_datetime
 
 
 class EvalRunInput(BaseModel):
@@ -74,8 +75,8 @@ class EvalSchema(BaseModel):
             eval_type=eval_run["eval_type"],
             eval_data=eval_run["eval_data"],
             eval_input=eval_run.get("eval_input"),
-            created_at=datetime.fromtimestamp(eval_run["created_at"], tz=timezone.utc),
-            updated_at=datetime.fromtimestamp(eval_run["updated_at"], tz=timezone.utc),
+            created_at=to_utc_datetime(eval_run.get("created_at")),
+            updated_at=to_utc_datetime(eval_run.get("updated_at")),
         )
 
     @classmethod

agno/os/routers/health.py

@@ -8,7 +8,7 @@ from agno.os.schema import HealthResponse
 def get_health_router(health_endpoint: str = "/health") -> APIRouter:
     router = APIRouter(tags=["Health"])
 
-    started_time_stamp = datetime.now(timezone.utc).timestamp()
+    started_at = datetime.now(timezone.utc)
 
     @router.get(
         health_endpoint,
@@ -20,12 +20,12 @@ def get_health_router(health_endpoint: str = "/health") -> APIRouter:
             200: {
                 "description": "API is healthy and operational",
                 "content": {
-                    "application/json": {"example": {"status": "ok", "instantiated_at": str(started_time_stamp)}}
+                    "application/json": {"example": {"status": "ok", "instantiated_at": "2025-06-10T12:00:00Z"}}
                 },
             }
         },
     )
     async def health_check() -> HealthResponse:
-        return HealthResponse(status="ok", instantiated_at=str(started_time_stamp))
+        return HealthResponse(status="ok", instantiated_at=started_at)
 
     return router

agno/os/routers/knowledge/knowledge.py

@@ -671,7 +671,7 @@ def attach_routes(router: APIRouter, knowledge_instances: List[Union[Knowledge,
         # Use max_results if specified, otherwise use a higher limit for search then paginate
         search_limit = request.max_results
 
-        results = await knowledge.async_search(
+        results = await knowledge.asearch(
             query=request.query, max_results=search_limit, filters=request.filters, search_type=request.search_type
         )
 
@@ -1047,7 +1047,7 @@ def attach_routes(router: APIRouter, knowledge_instances: List[Union[Knowledge,
                     search_types=search_types,
                 )
             )
-        filters = await knowledge.async_get_valid_filters()
+        filters = await knowledge.aget_valid_filters()
         return ConfigResponseSchema(
             readers=reader_schemas,
             vector_dbs=vector_dbs,
@@ -1098,7 +1098,7 @@ async def process_content(
             log_debug(f"Set chunking strategy: {chunker}")
 
         log_debug(f"Using reader: {content.reader.__class__.__name__}")
-        await knowledge._load_content_async(content, upsert=False, skip_if_exists=True)
+        await knowledge._aload_content(content, upsert=False, skip_if_exists=True)
         log_info(f"Content {content.id} processed successfully")
     except Exception as e:
         log_info(f"Error processing content: {e}")

agno/os/routers/memory/schemas.py

@@ -1,9 +1,11 @@
 import json
-from datetime import datetime, timezone
+from datetime import datetime
 from typing import Any, Dict, List, Optional
 
 from pydantic import BaseModel, Field
 
+from agno.os.utils import to_utc_datetime
+
 
 class DeleteMemoriesRequest(BaseModel):
     memory_ids: List[str] = Field(..., description="List of memory IDs to delete", min_length=1)
@@ -71,7 +73,7 @@ class UserStatsSchema(BaseModel):
         return cls(
             user_id=str(user_stats_dict["user_id"]),
             total_memories=user_stats_dict["total_memories"],
-            last_memory_updated_at=datetime.fromtimestamp(updated_at, tz=timezone.utc) if updated_at else None,
+            last_memory_updated_at=to_utc_datetime(updated_at),
         )
 
 

agno/os/routers/metrics/metrics.py

@@ -1,5 +1,5 @@
 import logging
-from datetime import date, datetime, timezone
+from datetime import date
 from typing import List, Optional, Union, cast
 
 from fastapi import Depends, HTTPException, Query, Request
@@ -16,7 +16,7 @@ from agno.os.schema import (
     ValidationErrorResponse,
 )
 from agno.os.settings import AgnoAPISettings
-from agno.os.utils import get_db
+from agno.os.utils import get_db, to_utc_datetime
 from agno.remote.base import RemoteDb
 
 logger = logging.getLogger(__name__)
@@ -79,9 +79,9 @@ def attach_routes(router: APIRouter, dbs: dict[str, list[Union[BaseDb, AsyncBase
                                         "reasoning_tokens": 0,
                                     },
                                     "model_metrics": [{"model_id": "gpt-4o", "model_provider": "OpenAI", "count": 5}],
-                                    "date": "2025-07-31T00:00:00",
-                                    "created_at": 1753993132,
-                                    "updated_at": 1753993741,
+                                    "date": "2025-07-31T00:00:00Z",
+                                    "created_at": "2025-07-31T12:38:52Z",
+                                    "updated_at": "2025-07-31T12:49:01Z",
                                 }
                             ]
                         }
@@ -121,9 +121,7 @@ def attach_routes(router: APIRouter, dbs: dict[str, list[Union[BaseDb, AsyncBase
 
             return MetricsResponse(
                 metrics=[DayAggregatedMetrics.from_dict(metric) for metric in metrics],
-                updated_at=datetime.fromtimestamp(latest_updated_at, tz=timezone.utc)
-                if latest_updated_at is not None
-                else None,
+                updated_at=to_utc_datetime(latest_updated_at),
             )
 
         except Exception as e:
@@ -167,9 +165,9 @@ def attach_routes(router: APIRouter, dbs: dict[str, list[Union[BaseDb, AsyncBase
                                     "reasoning_tokens": 0,
                                 },
                                 "model_metrics": [{"model_id": "gpt-4o", "model_provider": "OpenAI", "count": 2}],
-                                "date": "2025-08-12T00:00:00",
-                                "created_at": 1755016907,
-                                "updated_at": 1755016907,
+                                "date": "2025-08-12T00:00:00Z",
+                                "created_at": "2025-08-12T08:01:47Z",
+                                "updated_at": "2025-08-12T08:01:47Z",
                             }
                         ]
                     }

agno/os/routers/metrics/schemas.py

@@ -1,8 +1,10 @@
-from datetime import datetime
+from datetime import datetime, timezone
 from typing import Any, Dict, List, Optional
 
 from pydantic import BaseModel, Field
 
+from agno.os.utils import to_utc_datetime
+
 
 class DayAggregatedMetrics(BaseModel):
     """Aggregated metrics for a given day"""
@@ -20,22 +22,24 @@ class DayAggregatedMetrics(BaseModel):
     model_metrics: List[Dict[str, Any]] = Field(..., description="Metrics grouped by model (model_id, provider, count)")
 
     date: datetime = Field(..., description="Date for which these metrics are aggregated")
-    created_at: int = Field(..., description="Unix timestamp when metrics were created", ge=0)
-    updated_at: int = Field(..., description="Unix timestamp when metrics were last updated", ge=0)
+    created_at: datetime = Field(..., description="Timestamp when metrics were created")
+    updated_at: datetime = Field(..., description="Timestamp when metrics were last updated")
 
     @classmethod
     def from_dict(cls, metrics_dict: Dict[str, Any]) -> "DayAggregatedMetrics":
+        created_at = to_utc_datetime(metrics_dict.get("created_at")) or datetime.now(timezone.utc)
+        updated_at = to_utc_datetime(metrics_dict.get("updated_at", created_at)) or created_at
         return cls(
             agent_runs_count=metrics_dict.get("agent_runs_count", 0),
             agent_sessions_count=metrics_dict.get("agent_sessions_count", 0),
-            created_at=metrics_dict.get("created_at", 0),
-            date=metrics_dict.get("date", datetime.now()),
+            date=metrics_dict.get("date", datetime.now(timezone.utc)),
             id=metrics_dict.get("id", ""),
             model_metrics=metrics_dict.get("model_metrics", {}),
             team_runs_count=metrics_dict.get("team_runs_count", 0),
             team_sessions_count=metrics_dict.get("team_sessions_count", 0),
             token_metrics=metrics_dict.get("token_metrics", {}),
-            updated_at=metrics_dict.get("updated_at", metrics_dict.get("created_at", 0)),
+            created_at=created_at,
+            updated_at=updated_at,
             users_count=metrics_dict.get("users_count", 0),
             workflow_runs_count=metrics_dict.get("workflow_runs_count", 0),
             workflow_sessions_count=metrics_dict.get("workflow_sessions_count", 0),

agno/os/routers/registry/__init__.py

@@ -0,0 +1,3 @@
+from agno.os.routers.registry.registry import get_registry_router
+
+__all__ = ["get_registry_router"]