mcp-mesh 0.5.7__py3-none-any.whl → 0.6.1__py3-none-any.whl

_mcp_mesh/pipeline/mcp_startup/fastmcpserver_discovery.py

@@ -46,7 +46,7 @@ class FastMCPServerDiscoveryStep(PipelineStep):
                 server_info.append(info)
                 total_registered_functions += info.get("function_count", 0)
 
-                self.logger.info(
+                self.logger.debug(
                     f"📡 Discovered FastMCP server '{server_name}': "
                     f"{info.get('function_count', 0)} functions"
                 )
@@ -57,6 +57,13 @@ class FastMCPServerDiscoveryStep(PipelineStep):
             result.add_context("fastmcp_server_count", len(discovered_servers))
             result.add_context("fastmcp_total_functions", total_registered_functions)
 
+            # Store server info in DecoratorRegistry for heartbeat schema extraction (Phase 2)
+            from ...engine.decorator_registry import DecoratorRegistry
+
+            # Convert server_info list to dict for easier lookup
+            server_info_dict = {info["server_name"]: info for info in server_info}
+            DecoratorRegistry.store_fastmcp_server_info(server_info_dict)
+
             result.message = (
                 f"Discovered {len(discovered_servers)} FastMCP servers "
                 f"with {total_registered_functions} total functions"

_mcp_mesh/pipeline/mcp_startup/heartbeat_preparation.py

@@ -9,6 +9,7 @@ from ...engine.decorator_registry import DecoratorRegistry
 from ...engine.signature_analyzer import validate_mesh_dependencies
 from ...shared.config_resolver import ValidationRule, get_config_value
 from ...shared.support_types import HealthStatus, HealthStatusType
+from ...utils.fastmcp_schema_extractor import FastMCPSchemaExtractor
 from ..shared import PipelineResult, PipelineStatus, PipelineStep
 
 
@@ -39,8 +40,17 @@ class HeartbeatPreparationStep(PipelineStep):
             agent_config = DecoratorRegistry.get_resolved_agent_config()
             agent_id = agent_config["agent_id"]
 
-            # Build tools list for registration
-            tools_list = self._build_tools_list(mesh_tools)
+            # Get FastMCP server info from context (set by fastmcp-server-discovery step)
+            fastmcp_server_info = context.get("fastmcp_server_info", [])
+
+            # Convert server_info list to dict for schema extractor
+            fastmcp_servers = {}
+            for server_info in fastmcp_server_info:
+                server_name = server_info.get("server_name", "unknown")
+                fastmcp_servers[server_name] = server_info
+
+            # Build tools list for registration (with FastMCP schemas)
+            tools_list = self._build_tools_list(mesh_tools, fastmcp_servers)
 
             # Build agent registration payload
             registration_data = self._build_registration_payload(
@@ -71,8 +81,10 @@ class HeartbeatPreparationStep(PipelineStep):
 
         return result
 
-    def _build_tools_list(self, mesh_tools: dict[str, Any]) -> list[dict[str, Any]]:
-        """Build tools list from mesh_tools, validating function signatures."""
+    def _build_tools_list(
+        self, mesh_tools: dict[str, Any], fastmcp_servers: dict[str, Any] = None
+    ) -> list[dict[str, Any]]:
+        """Build tools list from mesh_tools, validating function signatures and extracting schemas."""
         tools_list = []
         skipped_tools = []
 
@@ -93,14 +105,108 @@ class HeartbeatPreparationStep(PipelineStep):
                     skipped_tools.append(func_name)
                     continue
 
+            # Extract inputSchema from FastMCP tool (if available)
+            # First try matching with FastMCP servers, then fallback to direct attribute
+            input_schema = FastMCPSchemaExtractor.extract_from_fastmcp_servers(
+                current_function, fastmcp_servers
+            )
+            if input_schema is None:
+                input_schema = FastMCPSchemaExtractor.extract_input_schema(
+                    current_function
+                )
+
+            # Check if this function has @mesh.llm decorator (Phase 3)
+            llm_filter_data = None
+            llm_provider_data = None
+            llm_agents = DecoratorRegistry.get_mesh_llm_agents()
+            self.logger.debug(
+                f"🤖 Checking for LLM filter: function={func_name}, total_llm_agents_registered={len(llm_agents)}"
+            )
+
+            for llm_agent_id, llm_metadata in llm_agents.items():
+                if llm_metadata.function.__name__ == func_name:
+                    # Found matching LLM agent - extract filter config
+                    raw_filter = llm_metadata.config.get("filter")
+                    filter_mode = llm_metadata.config.get("filter_mode", "all")
+
+                    # Normalize filter to array format (OpenAPI schema requirement)
+                    if raw_filter is None:
+                        normalized_filter = []
+                    elif isinstance(raw_filter, str):
+                        normalized_filter = [raw_filter]
+                    elif isinstance(raw_filter, dict):
+                        normalized_filter = [raw_filter]
+                    elif isinstance(raw_filter, list):
+                        normalized_filter = raw_filter
+                    else:
+                        self.logger.warning(
+                            f"⚠️ Invalid filter type for {func_name}: {type(raw_filter)}"
+                        )
+                        normalized_filter = []
+
+                    llm_filter_data = {
+                        "filter": normalized_filter,
+                        "filter_mode": filter_mode,
+                    }
+                    self.logger.debug(
+                        f"🤖 LLM filter found for {func_name}: {len(normalized_filter)} filters, mode={filter_mode}, raw_filter={raw_filter}"
+                    )
+
+                    # Check if provider is a dict (mesh delegation mode - v0.6.1)
+                    # If so, add it as llm_provider field (NOT in dependencies array)
+                    provider = llm_metadata.config.get("provider")
+                    if isinstance(provider, dict):
+                        self.logger.debug(
+                            f"🔌 LLM provider is dict (mesh delegation) for {func_name}: {provider}"
+                        )
+                        # Set llm_provider field (separate from dependencies)
+                        # Registry will resolve this to an actual provider agent
+                        llm_provider_data = {
+                            "capability": provider.get("capability", "llm"),
+                            "tags": provider.get("tags", []),
+                            "version": provider.get("version", ""),
+                            "namespace": provider.get("namespace", "default"),
+                        }
+                        self.logger.debug(
+                            f"✅ LLM provider spec prepared for {func_name}: {llm_provider_data}"
+                        )
+
+                    break
+
             # Build tool registration data
+            self.logger.debug(
+                f"Building tool_data for {func_name}, dependencies={dependencies}"
+            )
+            processed_deps = self._process_dependencies(dependencies)
+            self.logger.debug(
+                f"Processed dependencies for {func_name}: {processed_deps}"
+            )
+
+            # Extract kwargs (any extra fields not in standard set)
+            standard_fields = {
+                "capability",
+                "tags",
+                "version",
+                "description",
+                "dependencies",
+            }
+            kwargs_data = {
+                k: v for k, v in metadata.items() if k not in standard_fields
+            }
+
             tool_data = {
                 "function_name": func_name,
                 "capability": metadata.get("capability"),
                 "tags": metadata.get("tags", []),
                 "version": metadata.get("version", "1.0.0"),
                 "description": metadata.get("description"),
-                "dependencies": self._process_dependencies(dependencies),
+                "dependencies": processed_deps,
+                "input_schema": input_schema,  # Add inputSchema for LLM integration (Phase 2)
+                "llm_filter": llm_filter_data,  # Add LLM filter for LLM integration (Phase 3)
+                "llm_provider": llm_provider_data,  # Add LLM provider for mesh delegation (v0.6.1)
+                "kwargs": (
+                    kwargs_data if kwargs_data else None
+                ),  # Add kwargs for vendor and other metadata
             }
 
             # Add debug pointer information only if debug flag is enabled

_mcp_mesh/pipeline/mcp_startup/server_discovery.py

@@ -8,14 +8,14 @@ in @mesh.agent decorators to prevent Python interpreter shutdown.
 import logging
 from typing import Any, Dict, Optional
 
-from ..shared import PipelineResult, PipelineStatus, PipelineStep
 from ...shared.server_discovery import ServerDiscoveryUtil
+from ..shared import PipelineResult, PipelineStatus, PipelineStep
 
 
 class ServerDiscoveryStep(PipelineStep):
     """
     Discovers existing uvicorn servers that may be running.
-    
+
     This step checks if there's already a uvicorn server running on the target port,
     which could happen when @mesh.agent(auto_run=True) starts an immediate uvicorn
     server to prevent Python interpreter shutdown.
@@ -39,77 +39,100 @@ class ServerDiscoveryStep(PipelineStep):
             agent_config = context.get("agent_config", {})
             target_port = agent_config.get("http_port", 8080)
             target_host = agent_config.get("http_host", "0.0.0.0")
-            
-            self.logger.info(f"🔍 DISCOVERY: Looking for immediate uvicorn server from DecoratorRegistry")
+
+            self.logger.debug(
+                "🔍 DISCOVERY: Looking for immediate uvicorn server from DecoratorRegistry"
+            )
 
             # Check DecoratorRegistry for immediate uvicorn server (much more reliable)
             from ...engine.decorator_registry import DecoratorRegistry
+
             existing_server = DecoratorRegistry.get_immediate_uvicorn_server()
 
             # Debug: Show what we found
             if existing_server:
                 server_status = existing_server.get("status", "unknown")
                 server_type = existing_server.get("type", "unknown")
-                self.logger.info(f"🔍 DISCOVERY: Found server - status='{server_status}', type='{server_type}'")
+                self.logger.debug(
+                    f"🔍 DISCOVERY: Found server - status='{server_status}', type='{server_type}'"
+                )
             else:
-                self.logger.info(f"🔍 DISCOVERY: No immediate uvicorn server found in registry")
-            
+                self.logger.debug(
+                    "🔍 DISCOVERY: No immediate uvicorn server found in registry"
+                )
+
             if existing_server:
                 # Found existing immediate uvicorn server
-                server_host = existing_server.get('host', 'unknown')
-                server_port = existing_server.get('port', 0)
-                
+                server_host = existing_server.get("host", "unknown")
+                server_port = existing_server.get("port", 0)
+
                 result.add_context("existing_server", existing_server)
                 result.add_context("server_reuse", True)
-                
+
                 # Get the FastAPI app directly from server info
-                existing_app = existing_server.get('app')
+                existing_app = existing_server.get("app")
                 if existing_app:
                     app_info = {
-                        'instance': existing_app,
-                        'title': getattr(existing_app, 'title', 'MCP Mesh Agent (Starting)'),
-                        'version': getattr(existing_app, 'version', 'unknown'),
-                        'object_id': id(existing_app),
-                        'type': 'immediate_uvicorn'
+                        "instance": existing_app,
+                        "title": getattr(
+                            existing_app, "title", "MCP Mesh Agent (Starting)"
+                        ),
+                        "version": getattr(existing_app, "version", "unknown"),
+                        "object_id": id(existing_app),
+                        "type": "immediate_uvicorn",
                     }
                     result.add_context("existing_fastapi_app", app_info)
                     result.message = (
                         f"Found immediate uvicorn server on {server_host}:{server_port} "
                         f"with FastAPI app '{app_info.get('title', 'Unknown')}'"
                     )
-                    self.logger.info(
+                    self.logger.debug(
                         f"✅ DISCOVERY: Found immediate uvicorn server on {server_host}:{server_port} "
                         f"with FastAPI app '{app_info.get('title', 'Unknown')}'"
                     )
                 else:
                     result.message = f"Found immediate uvicorn server on {server_host}:{server_port} (no FastAPI app reference)"
-                    self.logger.warning(f"⚠️ DISCOVERY: Found immediate uvicorn server but no FastAPI app reference")
-                
+                    self.logger.warning(
+                        "⚠️ DISCOVERY: Found immediate uvicorn server but no FastAPI app reference"
+                    )
+
             else:
                 # No existing server found
                 result.add_context("existing_server", None)
                 result.add_context("server_reuse", False)
-                result.message = f"No immediate uvicorn server found in DecoratorRegistry"
-                self.logger.info(f"🔍 DISCOVERY: No immediate uvicorn server found - pipeline will start new server")
+                result.message = (
+                    "No immediate uvicorn server found in DecoratorRegistry"
+                )
+                self.logger.info(
+                    "🔍 DISCOVERY: No immediate uvicorn server found - pipeline will start new server"
+                )
 
             # Only discover FastAPI apps if no immediate uvicorn server was found
             if not existing_server:
-                self.logger.debug("🔍 DISCOVERY: No immediate uvicorn server found, discovering FastAPI apps via garbage collection")
+                self.logger.debug(
+                    "🔍 DISCOVERY: No immediate uvicorn server found, discovering FastAPI apps via garbage collection"
+                )
                 fastapi_apps = ServerDiscoveryUtil.discover_fastapi_instances()
                 result.add_context("discovered_fastapi_apps", fastapi_apps)
-                
+
                 if fastapi_apps:
                     app_count = len(fastapi_apps)
                     result.message += f" | Discovered {app_count} FastAPI app(s)"
-                    self.logger.info(f"📦 DISCOVERY: Discovered {app_count} FastAPI application(s) for potential mounting")
-                    
+                    self.logger.info(
+                        f"📦 DISCOVERY: Discovered {app_count} FastAPI application(s) for potential mounting"
+                    )
+
                     # Log details about discovered apps
                     for app_id, app_info in fastapi_apps.items():
                         app_title = app_info.get("title", "Unknown")
                         route_count = len(app_info.get("routes", []))
-                        self.logger.debug(f"  📦 App '{app_title}' ({app_id}): {route_count} routes")
+                        self.logger.debug(
+                            f"  📦 App '{app_title}' ({app_id}): {route_count} routes"
+                        )
             else:
-                self.logger.debug("🔍 DISCOVERY: Using FastAPI app from immediate uvicorn server, skipping garbage collection discovery")
+                self.logger.debug(
+                    "🔍 DISCOVERY: Using FastAPI app from immediate uvicorn server, skipping garbage collection discovery"
+                )
 
         except Exception as e:
             result.status = PipelineStatus.FAILED
@@ -119,46 +142,52 @@ class ServerDiscoveryStep(PipelineStep):
 
         return result
 
-    def _find_associated_fastapi_app(self, server_info: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+    def _find_associated_fastapi_app(
+        self, server_info: dict[str, Any]
+    ) -> Optional[dict[str, Any]]:
         """
         Try to find the FastAPI app associated with the existing server.
-        
+
         Args:
             server_info: Server information from discovery
-            
+
         Returns:
             FastAPI app info if found, None otherwise
         """
         try:
             # Check if server info already has an app
-            if 'app' in server_info:
-                app = server_info['app']
+            if "app" in server_info:
+                app = server_info["app"]
                 return {
-                    'instance': app,
-                    'title': getattr(app, 'title', 'Unknown'),
-                    'version': getattr(app, 'version', 'unknown'),
-                    'routes': ServerDiscoveryUtil._extract_route_info(app),
-                    'object_id': id(app),
+                    "instance": app,
+                    "title": getattr(app, "title", "Unknown"),
+                    "version": getattr(app, "version", "unknown"),
+                    "routes": ServerDiscoveryUtil._extract_route_info(app),
+                    "object_id": id(app),
                 }
-            
+
             # If not, discover all FastAPI apps and try to match
             fastapi_apps = ServerDiscoveryUtil.discover_fastapi_instances()
-            
+
             # For immediate uvicorn servers, look for apps with specific titles
             for app_id, app_info in fastapi_apps.items():
-                app_title = app_info.get('title', '')
-                if 'MCP Mesh Agent' in app_title and 'Starting' in app_title:
+                app_title = app_info.get("title", "")
+                if "MCP Mesh Agent" in app_title and "Starting" in app_title:
                     # This looks like our immediate uvicorn app
-                    self.logger.debug(f"🔍 DISCOVERY: Found immediate uvicorn FastAPI app: {app_title}")
+                    self.logger.debug(
+                        f"🔍 DISCOVERY: Found immediate uvicorn FastAPI app: {app_title}"
+                    )
                     return app_info
-            
+
             # If no immediate uvicorn app found, return the first available app
             if fastapi_apps:
                 first_app = next(iter(fastapi_apps.values()))
-                self.logger.debug(f"🔍 DISCOVERY: Using first available FastAPI app: {first_app.get('title', 'Unknown')}")
+                self.logger.debug(
+                    f"🔍 DISCOVERY: Using first available FastAPI app: {first_app.get('title', 'Unknown')}"
+                )
                 return first_app
-                
+
         except Exception as e:
             self.logger.warning(f"Error finding associated FastAPI app: {e}")
-        
-        return None
+
+        return None

_mcp_mesh/pipeline/mcp_startup/startup_orchestrator.py

@@ -228,7 +228,7 @@ class DebounceCoordinator:
                                     fastapi_app, binding_config
                                 )
                         elif server_status == "running":
-                            self.logger.info(
+                            self.logger.debug(
                                 "🔄 RUNNING SERVER: Server already running with proper lifecycle, pipeline skipping uvicorn.run()"
                             )
                             self.logger.info(
@@ -493,7 +493,7 @@ class MeshOrchestrator:
 
         This replaces the background polling with explicit execution.
         """
-        self.logger.info(f"🚀 Starting single pipeline execution: {self.name}")
+        self.logger.debug(f"🚀 Starting single pipeline execution: {self.name}")
 
         result = await self.pipeline.execute()
 

_mcp_mesh/pipeline/mcp_startup/startup_pipeline.py

@@ -49,9 +49,9 @@ class StartupPipeline(MeshPipeline):
         steps = [
             DecoratorCollectionStep(),
             ConfigurationStep(),
-            HeartbeatPreparationStep(),  # Prepare heartbeat payload structure
+            FastMCPServerDiscoveryStep(),  # Discover user's FastMCP instances (MOVED UP for Phase 2)
+            HeartbeatPreparationStep(),  # Prepare heartbeat payload structure (can now access FastMCP schemas)
             ServerDiscoveryStep(),  # Discover existing uvicorn servers from immediate startup
-            FastMCPServerDiscoveryStep(),  # Discover user's FastMCP instances
             HeartbeatLoopStep(),  # Setup background heartbeat config (handles no registry gracefully)
             FastAPIServerSetupStep(),  # Setup FastAPI app with background heartbeat
             # Note: Registry connection is handled in heartbeat pipeline for retry behavior

_mcp_mesh/shared/health_check_cache.py

@@ -0,0 +1,246 @@
+"""
+Health check caching with TTL support.
+
+Provides a TTL-based cache for health check results to avoid expensive
+health check operations on every heartbeat and /health endpoint call.
+"""
+
+import logging
+import time
+from collections.abc import Awaitable, Callable
+from datetime import UTC, datetime
+from typing import Any, Optional
+
+from .support_types import HealthStatus, HealthStatusType
+
+logger = logging.getLogger(__name__)
+
+# Global cache instance for health status
+# Stores tuples of (health_status, expiry_timestamp) for per-key TTL support
+# Format: {"health:agent_id": (HealthStatus, expiry_timestamp)}
+_health_cache: dict[str, tuple[HealthStatus, float]] = {}
+_max_cache_size = 100
+
+
+async def get_health_status_with_cache(
+    agent_id: str,
+    health_check_fn: Optional[Callable[[], Awaitable[Any]]],
+    agent_config: dict[str, Any],
+    startup_context: dict[str, Any],
+    ttl: int = 15,
+) -> HealthStatus:
+    """
+    Get health status with TTL caching.
+
+    This function synchronously returns from cache if available, otherwise
+    calls the user's health check function and caches the result.
+
+    User health check can return:
+    - bool: True = HEALTHY, False = UNHEALTHY
+    - dict: {"status": "healthy/degraded/unhealthy", "checks": {...}, "errors": [...]}
+    - HealthStatus: Full object (fields will be overridden with correct values)
+
+    Args:
+        agent_id: Unique identifier for the agent
+        health_check_fn: Optional async function that returns bool, dict, or HealthStatus
+        agent_config: Agent configuration dict for building default health status
+        startup_context: Full startup context with capabilities
+        ttl: Cache TTL in seconds (default: 15)
+
+    Returns:
+        HealthStatus: Current health status (from cache or fresh check)
+
+    Note:
+        - Cache key is based on agent_id
+        - If health_check_fn is None, returns default HEALTHY status
+        - If health_check_fn raises an exception, returns DEGRADED status
+        - TTL is enforced per-key with manual expiry tracking
+    """
+    cache_key = f"health:{agent_id}"
+    current_time = time.time()
+
+    # Try to get from cache and check if expired
+    if cache_key in _health_cache:
+        cached_status, expiry_time = _health_cache[cache_key]
+        if current_time < expiry_time:
+            logger.debug(f"✅ Health check cache HIT for agent '{agent_id}'")
+            return cached_status
+        else:
+            # Cache entry expired, remove it
+            logger.debug(
+                f"⏰ Health check cache EXPIRED for agent '{agent_id}' (TTL exceeded)"
+            )
+            del _health_cache[cache_key]
+
+    logger.debug(f"❌ Health check cache MISS for agent '{agent_id}'")
+
+    # Cache miss - call user's health check if provided
+    if health_check_fn:
+        try:
+            logger.debug(
+                f"🔍 Executing health check function for agent '{agent_id}'..."
+            )
+            user_result = await health_check_fn()
+
+            # Parse user result into status, checks, and errors
+            status_type = HealthStatusType.HEALTHY
+            checks = {}
+            errors = []
+
+            if isinstance(user_result, bool):
+                # Simple boolean: True = HEALTHY, False = UNHEALTHY
+                status_type = (
+                    HealthStatusType.HEALTHY
+                    if user_result
+                    else HealthStatusType.UNHEALTHY
+                )
+                checks["health_check"] = user_result
+                if not user_result:
+                    errors.append("Health check returned False")
+
+            elif isinstance(user_result, dict):
+                # Dictionary with status, checks, errors
+                status_str = user_result.get("status", "healthy").lower()
+                if status_str == "healthy":
+                    status_type = HealthStatusType.HEALTHY
+                elif status_str == "degraded":
+                    status_type = HealthStatusType.DEGRADED
+                elif status_str == "unhealthy":
+                    status_type = HealthStatusType.UNHEALTHY
+                else:
+                    status_type = HealthStatusType.UNKNOWN
+
+                checks = user_result.get("checks", {})
+                errors = user_result.get("errors", [])
+
+            elif isinstance(user_result, HealthStatus):
+                # Full HealthStatus object - extract status, checks, errors
+                status_type = user_result.status
+                checks = user_result.checks
+                errors = user_result.errors
+
+            else:
+                logger.warning(
+                    f"⚠️ Health check for '{agent_id}' returned unexpected type {type(user_result)}, treating as unhealthy"
+                )
+                status_type = HealthStatusType.UNHEALTHY
+                checks = {"health_check_return_type": False}
+                errors = [f"Invalid return type: {type(user_result)}"]
+
+            # Build complete HealthStatus with resolved values
+            # Get capabilities from startup_context (from registered tools)
+            capabilities = startup_context.get("capabilities", [])
+            if not capabilities:
+                # Fallback: try to get from agent_config
+                capabilities = agent_config.get("capabilities", [])
+            if not capabilities:
+                # Last resort: use a default to satisfy validation
+                capabilities = ["default"]
+
+            health_status = HealthStatus(
+                agent_name=agent_id,
+                status=status_type,
+                capabilities=capabilities,
+                checks=checks,
+                errors=errors,
+                timestamp=datetime.now(UTC),
+                version=agent_config.get("version", "1.0.0"),
+                metadata=agent_config,
+                uptime_seconds=0,
+            )
+
+            logger.info(
+                f"💚 Health check function executed successfully for '{agent_id}': {health_status.status.value}"
+            )
+
+        except Exception as e:
+            # Health check function failed - return DEGRADED
+            logger.warning(
+                f"⚠️ Health check function failed for agent '{agent_id}': {e}"
+            )
+
+            # Get capabilities from startup_context
+            capabilities = startup_context.get("capabilities", [])
+            if not capabilities:
+                capabilities = agent_config.get("capabilities", ["default"])
+
+            health_status = HealthStatus(
+                agent_name=agent_id,
+                status=HealthStatusType.DEGRADED,
+                capabilities=capabilities,
+                checks={"health_check_execution": False},
+                errors=[f"Health check failed: {str(e)}"],
+                timestamp=datetime.now(UTC),
+                version=agent_config.get("version", "1.0.0"),
+                metadata=agent_config,
+                uptime_seconds=0,
+            )
+    else:
+        # No health check provided - default to HEALTHY
+        logger.debug(
+            f"ℹ️ No health check function provided for '{agent_id}', using default HEALTHY status"
+        )
+
+        # Get capabilities from startup_context
+        capabilities = startup_context.get("capabilities", [])
+        if not capabilities:
+            capabilities = agent_config.get("capabilities", ["default"])
+
+        health_status = HealthStatus(
+            agent_name=agent_id,
+            status=HealthStatusType.HEALTHY,
+            capabilities=capabilities,
+            timestamp=datetime.now(UTC),
+            version=agent_config.get("version", "1.0.0"),
+            metadata=agent_config,
+            uptime_seconds=0,
+        )
+
+    # Store in cache with TTL (manual expiry tracking)
+    expiry_time = current_time + ttl
+    _health_cache[cache_key] = (health_status, expiry_time)
+    logger.debug(f"💾 Cached health status for '{agent_id}' with TTL={ttl}s")
+
+    # Enforce max cache size by removing oldest entry if needed
+    if len(_health_cache) > _max_cache_size:
+        # Remove the entry with earliest expiry time
+        oldest_key = min(_health_cache.keys(), key=lambda k: _health_cache[k][1])
+        del _health_cache[oldest_key]
+        logger.debug("🗑️ Evicted oldest cache entry to maintain max size")
+
+    return health_status
+
+
+def clear_health_cache(agent_id: Optional[str] = None) -> None:
+    """
+    Clear health cache for a specific agent or all agents.
+
+    Args:
+        agent_id: Optional agent ID to clear. If None, clears entire cache.
+
+    Note:
+        This is useful for testing or forcing a fresh health check.
+    """
+    if agent_id:
+        cache_key = f"health:{agent_id}"
+        if cache_key in _health_cache:
+            del _health_cache[cache_key]
+            logger.debug(f"🗑️ Cleared health cache for agent '{agent_id}'")
+    else:
+        _health_cache.clear()
+        logger.debug("🗑️ Cleared entire health cache")
+
+
+def get_cache_stats() -> dict[str, Any]:
+    """
+    Get cache statistics for monitoring and debugging.
+
+    Returns:
+        dict: Cache statistics including size, maxsize, and current keys
+    """
+    return {
+        "size": len(_health_cache),
+        "maxsize": _max_cache_size,
+        "ttl": 15,  # Default TTL (for backward compatibility)
+        "cached_agents": [key.replace("health:", "") for key in _health_cache.keys()],
+    }