crca 1.4.0__py3-none-any.whl

utils/aop.py

@@ -0,0 +1,2948 @@
+import asyncio
+from contextlib import AbstractAsyncContextManager
+import socket
+import sys
+import threading
+import time
+import traceback
+from collections import deque
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Callable, Dict, List, Literal, Optional
+from uuid import uuid4
+
+from loguru import logger
+from mcp.server.auth.settings import AuthSettings
+from mcp.server.fastmcp import FastMCP
+from mcp.server.lowlevel.server import LifespanResultT
+from mcp.server.transport_security import TransportSecuritySettings
+
+from swarms.structs.agent import Agent
+from swarms.structs.omni_agent_types import AgentType
+from swarms.tools.mcp_client_tools import (
+    get_tools_for_multiple_mcp_servers,
+)
+
+
+class TaskStatus(Enum):
+    """Status of a task in the queue."""
+
+    PENDING = "pending"
+    PROCESSING = "processing"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+
+
+class QueueStatus(Enum):
+    """Status of a task queue."""
+
+    RUNNING = "running"
+    PAUSED = "paused"
+    STOPPED = "stopped"
+
+
+@dataclass
+class Task:
+    """
+    Represents a task to be executed by an agent.
+
+    Attributes:
+        task_id: Unique identifier for the task
+        task: The task or prompt to execute
+        img: Optional image to be processed
+        imgs: Optional list of images to be processed
+        correct_answer: Optional correct answer for validation
+        priority: Task priority (higher number = higher priority)
+        created_at: Timestamp when task was created
+        status: Current status of the task
+        result: Result of task execution
+        error: Error message if task failed
+        retry_count: Number of times task has been retried
+        max_retries: Maximum number of retries allowed
+    """
+
+    task_id: str = field(default_factory=lambda: str(uuid4()))
+    task: str = ""
+    img: Optional[str] = None
+    imgs: Optional[List[str]] = None
+    correct_answer: Optional[str] = None
+    priority: int = 0
+    created_at: float = field(default_factory=time.time)
+    status: TaskStatus = TaskStatus.PENDING
+    result: Optional[str] = None
+    error: Optional[str] = None
+    retry_count: int = 0
+    max_retries: int = 3
+
+
+@dataclass
+class QueueStats:
+    """
+    Statistics for a task queue.
+
+    Attributes:
+        total_tasks: Total number of tasks processed
+        completed_tasks: Number of successfully completed tasks
+        failed_tasks: Number of failed tasks
+        pending_tasks: Number of tasks currently pending
+        processing_tasks: Number of tasks currently being processed
+        average_processing_time: Average time to process a task
+        queue_size: Current size of the queue
+    """
+
+    total_tasks: int = 0
+    completed_tasks: int = 0
+    failed_tasks: int = 0
+    pending_tasks: int = 0
+    processing_tasks: int = 0
+    average_processing_time: float = 0.0
+    queue_size: int = 0
+
+
+class TaskQueue:
+    """
+    A thread-safe task queue for managing agent tasks.
+
+    This class provides functionality to:
+    1. Add tasks to the queue with priority support
+    2. Process tasks in background workers
+    3. Handle task retries and error management
+    4. Provide queue statistics and monitoring
+    """
+
+    def __init__(
+        self,
+        agent_name: str,
+        agent: AgentType,
+        max_workers: int = 1,
+        max_queue_size: int = 1000,
+        processing_timeout: int = 30,
+        retry_delay: float = 1.0,
+        verbose: bool = False,
+    ):
+        """
+        Initialize the task queue.
+
+        Args:
+            agent_name: Name of the agent this queue belongs to
+            agent: The agent instance to execute tasks
+            max_workers: Maximum number of worker threads
+            max_queue_size: Maximum number of tasks in queue
+            processing_timeout: Timeout for task processing in seconds
+            retry_delay: Delay between retries in seconds
+            verbose: Enable verbose logging
+        """
+        self.agent_name = agent_name
+        self.agent = agent
+        self.max_workers = max_workers
+        self.max_queue_size = max_queue_size
+        self.processing_timeout = processing_timeout
+        self.retry_delay = retry_delay
+        self.verbose = verbose
+
+        # Queue management
+        self._queue = deque()
+        self._lock = threading.RLock()
+        self._status = QueueStatus.STOPPED
+        self._workers = []
+        self._stop_event = threading.Event()
+
+        # Statistics
+        self._stats = QueueStats()
+        self._processing_times = deque(
+            maxlen=100
+        )  # Keep last 100 processing times
+
+        # Task tracking
+        self._tasks = {}  # task_id -> Task
+        self._processing_tasks = (
+            set()
+        )  # Currently processing task IDs
+
+        logger.info(
+            f"Initialized TaskQueue for agent '{agent_name}' with {max_workers} workers"
+        )
+
+    def add_task(
+        self,
+        task: str,
+        img: Optional[str] = None,
+        imgs: Optional[List[str]] = None,
+        correct_answer: Optional[str] = None,
+        priority: int = 0,
+        max_retries: int = 3,
+    ) -> str:
+        """
+        Add a task to the queue.
+
+        Args:
+            task: The task or prompt to execute
+            img: Optional image to be processed
+            imgs: Optional list of images to be processed
+            correct_answer: Optional correct answer for validation
+            priority: Task priority (higher number = higher priority)
+            max_retries: Maximum number of retries allowed
+
+        Returns:
+            str: Task ID
+
+        Raises:
+            ValueError: If queue is full or task is invalid
+        """
+        if not task:
+            raise ValueError("Task cannot be empty")
+
+        with self._lock:
+            if len(self._queue) >= self.max_queue_size:
+                raise ValueError(
+                    f"Queue is full (max size: {self.max_queue_size})"
+                )
+
+            task_obj = Task(
+                task=task,
+                img=img,
+                imgs=imgs,
+                correct_answer=correct_answer,
+                priority=priority,
+                max_retries=max_retries,
+            )
+
+            # Insert task based on priority (higher priority first)
+            inserted = False
+            for i, existing_task in enumerate(self._queue):
+                if task_obj.priority > existing_task.priority:
+                    self._queue.insert(i, task_obj)
+                    inserted = True
+                    break
+
+            if not inserted:
+                self._queue.append(task_obj)
+
+            self._tasks[task_obj.task_id] = task_obj
+            self._stats.total_tasks += 1
+            self._stats.pending_tasks += 1
+            self._stats.queue_size = len(self._queue)
+
+            if self.verbose:
+                logger.debug(
+                    f"Added task '{task_obj.task_id}' to queue for agent '{self.agent_name}'"
+                )
+
+            return task_obj.task_id
+
+    def get_task(self, task_id: str) -> Optional[Task]:
+        """
+        Get a task by ID.
+
+        Args:
+            task_id: The task ID
+
+        Returns:
+            Task object or None if not found
+        """
+        with self._lock:
+            return self._tasks.get(task_id)
+
+    def cancel_task(self, task_id: str) -> bool:
+        """
+        Cancel a task.
+
+        Args:
+            task_id: The task ID to cancel
+
+        Returns:
+            bool: True if task was cancelled, False if not found or already processed
+        """
+        with self._lock:
+            if task_id not in self._tasks:
+                return False
+
+            task = self._tasks[task_id]
+            if task.status in [
+                TaskStatus.COMPLETED,
+                TaskStatus.FAILED,
+                TaskStatus.CANCELLED,
+            ]:
+                return False
+
+            # Remove from queue if still pending
+            if task.status == TaskStatus.PENDING:
+                try:
+                    self._queue.remove(task)
+                    self._stats.pending_tasks -= 1
+                    self._stats.queue_size = len(self._queue)
+                except ValueError:
+                    pass  # Task not in queue
+
+            # Mark as cancelled
+            task.status = TaskStatus.CANCELLED
+            self._processing_tasks.discard(task_id)
+
+            if self.verbose:
+                logger.debug(
+                    f"Cancelled task '{task_id}' for agent '{self.agent_name}'"
+                )
+
+            return True
+
+    def start_workers(self) -> None:
+        """Start the background worker threads."""
+        with self._lock:
+            if self._status != QueueStatus.STOPPED:
+                logger.warning(
+                    f"Workers for agent '{self.agent_name}' are already running"
+                )
+                return
+
+            self._status = QueueStatus.RUNNING
+            self._stop_event.clear()
+
+            for i in range(self.max_workers):
+                worker = threading.Thread(
+                    target=self._worker_loop,
+                    name=f"Worker-{self.agent_name}-{i}",
+                    daemon=True,
+                )
+                worker.start()
+                self._workers.append(worker)
+
+            logger.info(
+                f"Started {self.max_workers} workers for agent '{self.agent_name}'"
+            )
+
+    def stop_workers(self) -> None:
+        """Stop the background worker threads."""
+        with self._lock:
+            if self._status == QueueStatus.STOPPED:
+                return
+
+            self._status = QueueStatus.STOPPED
+            self._stop_event.set()
+
+            # Wait for workers to finish
+            for worker in self._workers:
+                worker.join(timeout=5.0)
+
+            self._workers.clear()
+            logger.info(
+                f"Stopped workers for agent '{self.agent_name}'"
+            )
+
+    def pause_workers(self) -> None:
+        """Pause the workers (they will finish current tasks but not start new ones)."""
+        with self._lock:
+            if self._status == QueueStatus.RUNNING:
+                self._status = QueueStatus.PAUSED
+                logger.info(
+                    f"Paused workers for agent '{self.agent_name}'"
+                )
+
+    def resume_workers(self) -> None:
+        """Resume the workers."""
+        with self._lock:
+            if self._status == QueueStatus.PAUSED:
+                self._status = QueueStatus.RUNNING
+                logger.info(
+                    f"Resumed workers for agent '{self.agent_name}'"
+                )
+
+    def clear_queue(self) -> int:
+        """
+        Clear all pending tasks from the queue.
+
+        Returns:
+            int: Number of tasks cleared
+        """
+        with self._lock:
+            cleared_count = len(self._queue)
+            self._queue.clear()
+            self._stats.pending_tasks = 0
+            self._stats.queue_size = 0
+
+            # Mark all pending tasks as cancelled
+            for task in self._tasks.values():
+                if task.status == TaskStatus.PENDING:
+                    task.status = TaskStatus.CANCELLED
+
+            if self.verbose:
+                logger.debug(
+                    f"Cleared {cleared_count} tasks from queue for agent '{self.agent_name}'"
+                )
+
+            return cleared_count
+
+    def get_stats(self) -> QueueStats:
+        """Get current queue statistics."""
+        with self._lock:
+            # Update current stats
+            self._stats.pending_tasks = len(
+                [
+                    t
+                    for t in self._tasks.values()
+                    if t.status == TaskStatus.PENDING
+                ]
+            )
+            self._stats.processing_tasks = len(self._processing_tasks)
+            self._stats.queue_size = len(self._queue)
+
+            # Calculate average processing time
+            if self._processing_times:
+                self._stats.average_processing_time = sum(
+                    self._processing_times
+                ) / len(self._processing_times)
+
+            return QueueStats(
+                total_tasks=self._stats.total_tasks,
+                completed_tasks=self._stats.completed_tasks,
+                failed_tasks=self._stats.failed_tasks,
+                pending_tasks=self._stats.pending_tasks,
+                processing_tasks=self._stats.processing_tasks,
+                average_processing_time=self._stats.average_processing_time,
+                queue_size=self._stats.queue_size,
+            )
+
+    def get_status(self) -> QueueStatus:
+        """Get current queue status."""
+        return self._status
+
+    def _worker_loop(self) -> None:
+        """Main worker loop for processing tasks."""
+        while not self._stop_event.is_set():
+            try:
+                # Check if we should process tasks
+                with self._lock:
+                    if (
+                        self._status != QueueStatus.RUNNING
+                        or not self._queue
+                    ):
+                        self._stop_event.wait(0.1)
+                        continue
+
+                    # Get next task
+                    task = self._queue.popleft()
+                    self._processing_tasks.add(task.task_id)
+                    task.status = TaskStatus.PROCESSING
+                    self._stats.pending_tasks -= 1
+                    self._stats.processing_tasks += 1
+
+                # Process the task
+                self._process_task(task)
+
+            except Exception as e:
+                logger.error(
+                    f"Error in worker loop for agent '{self.agent_name}': {e}"
+                )
+                if self.verbose:
+                    logger.error(traceback.format_exc())
+                time.sleep(0.1)
+
+    def _process_task(self, task: Task) -> None:
+        """
+        Process a single task.
+
+        Args:
+            task: The task to process
+        """
+        start_time = time.time()
+
+        try:
+            if self.verbose:
+                logger.debug(
+                    f"Processing task '{task.task_id}' for agent '{self.agent_name}'"
+                )
+
+            # Execute the agent
+            result = self.agent.run(
+                task=task.task,
+                img=task.img,
+                imgs=task.imgs,
+                correct_answer=task.correct_answer,
+            )
+
+            # Update task with result
+            task.result = result
+            task.status = TaskStatus.COMPLETED
+
+            # Update statistics
+            processing_time = time.time() - start_time
+            self._processing_times.append(processing_time)
+
+            with self._lock:
+                self._stats.completed_tasks += 1
+                self._stats.processing_tasks -= 1
+                self._processing_tasks.discard(task.task_id)
+
+            if self.verbose:
+                logger.debug(
+                    f"Completed task '{task.task_id}' in {processing_time:.2f}s"
+                )
+
+        except Exception as e:
+            error_msg = str(e)
+            task.error = error_msg
+            task.retry_count += 1
+
+            if self.verbose:
+                logger.error(
+                    f"Error processing task '{task.task_id}': {error_msg}"
+                )
+                logger.error(traceback.format_exc())
+
+            # Handle retries
+            if task.retry_count <= task.max_retries:
+                if self.verbose:
+                    logger.debug(
+                        f"Retrying task '{task.task_id}' (attempt {task.retry_count + 1})"
+                    )
+
+                # Re-queue the task with a delay
+                time.sleep(self.retry_delay)
+
+                with self._lock:
+                    if self._status == QueueStatus.RUNNING:
+                        task.status = TaskStatus.PENDING
+                        self._queue.append(
+                            task
+                        )  # Add to end of queue
+                        self._stats.pending_tasks += 1
+                        self._stats.queue_size = len(self._queue)
+                    else:
+                        task.status = TaskStatus.FAILED
+                        self._stats.failed_tasks += 1
+            else:
+                # Max retries exceeded
+                task.status = TaskStatus.FAILED
+
+                with self._lock:
+                    self._stats.failed_tasks += 1
+                    self._stats.processing_tasks -= 1
+                    self._processing_tasks.discard(task.task_id)
+
+                if self.verbose:
+                    logger.error(
+                        f"Task '{task.task_id}' failed after {task.max_retries} retries"
+                    )
+
+
+@dataclass
+class AgentToolConfig:
+    """
+    Configuration for converting an agent to an MCP tool.
+
+    Attributes:
+        tool_name: The name of the tool in the MCP server
+        tool_description: Description of what the tool does
+        input_schema: JSON schema for the tool's input parameters
+        output_schema: JSON schema for the tool's output
+        timeout: Maximum time to wait for agent execution (seconds)
+        max_retries: Number of retries if agent execution fails
+        verbose: Enable verbose logging for this tool
+        traceback_enabled: Enable traceback logging for errors
+    """
+
+    tool_name: str
+    tool_description: str
+    input_schema: Dict[str, Any]
+    output_schema: Dict[str, Any]
+    timeout: int = 30
+    max_retries: int = 3
+    verbose: bool = False
+    traceback_enabled: bool = True
+
+
+class AOP:
+    """
+    A class that takes a list of agents and deploys them as unique tools in an MCP server.
+
+    This class provides functionality to:
+    1. Convert swarms agents into MCP tools
+    2. Deploy multiple agents as individual tools
+    3. Handle tool execution with proper error handling
+    4. Manage the MCP server lifecycle
+    5. Queue-based task execution for improved performance and reliability
+    6. Persistence mode with automatic restart and failsafe protection
+
+    Attributes:
+        mcp_server: The FastMCP server instance
+        agents: Dictionary mapping tool names to agent instances
+        tool_configs: Dictionary mapping tool names to their configurations
+        task_queues: Dictionary mapping tool names to their task queues
+        server_name: Name of the MCP server
+        queue_enabled: Whether queue-based execution is enabled
+        persistence: Whether persistence mode is enabled
+        max_restart_attempts: Maximum number of restart attempts before giving up
+        restart_delay: Delay between restart attempts in seconds
+        network_monitoring: Whether network connection monitoring is enabled
+        max_network_retries: Maximum number of network reconnection attempts
+        network_retry_delay: Delay between network retry attempts in seconds
+        network_timeout: Network connection timeout in seconds
+    """
+
+    def __init__(
+        self,
+        server_name: str = "AOP Cluster",
+        description: str = "A cluster that enables you to deploy multiple agents as tools in an MCP server.",
+        agents: any = None,
+        port: int = 8000,
+        transport: str = "streamable-http",
+        verbose: bool = False,
+        traceback_enabled: bool = True,
+        host: str = "localhost",
+        queue_enabled: bool = True,
+        max_workers_per_agent: int = 1,
+        max_queue_size_per_agent: int = 1000,
+        processing_timeout: int = 30,
+        retry_delay: float = 1.0,
+        persistence: bool = False,
+        max_restart_attempts: int = 10,
+        restart_delay: float = 5.0,
+        network_monitoring: bool = True,
+        max_network_retries: int = 5,
+        network_retry_delay: float = 10.0,
+        network_timeout: float = 30.0,
+        log_level: Literal[
+            "DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"
+        ] = "INFO",
+        lifespan: (
+            Callable[
+                [FastMCP[LifespanResultT]],
+                AbstractAsyncContextManager[LifespanResultT],
+            ]
+            | None
+        ) = None,
+        auth: AuthSettings | None = None,
+        transport_security: TransportSecuritySettings | None = None,
+        *args,
+        **kwargs,
+    ):
+        """
+        Initialize the AOP.
+
+        Args:
+            server_name: Name for the MCP server
+            description: Description of the AOP cluster
+            agents: Optional list of agents to add initially
+            port: Port for the MCP server
+            transport: Transport type for the MCP server
+            verbose: Enable verbose logging
+            traceback_enabled: Enable traceback logging for errors
+            host: Host to bind the server to
+            log_level: Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
+            queue_enabled: Enable queue-based task execution
+            max_workers_per_agent: Maximum number of workers per agent
+            max_queue_size_per_agent: Maximum queue size per agent
+            processing_timeout: Timeout for task processing in seconds
+            retry_delay: Delay between retries in seconds
+            persistence: Enable automatic restart on shutdown (with failsafe)
+            max_restart_attempts: Maximum number of restart attempts before giving up
+            restart_delay: Delay between restart attempts in seconds
+            network_monitoring: Enable network connection monitoring and retry
+            max_network_retries: Maximum number of network reconnection attempts
+            network_retry_delay: Delay between network retry attempts in seconds
+            network_timeout: Network connection timeout in seconds
+        """
+        self.server_name = server_name
+        self.description = description
+        self.verbose = verbose
+        self.traceback_enabled = traceback_enabled
+        self.log_level = log_level
+        self.host = host
+        self.port = port
+        self.queue_enabled = queue_enabled
+        self.max_workers_per_agent = max_workers_per_agent
+        self.max_queue_size_per_agent = max_queue_size_per_agent
+        self.processing_timeout = processing_timeout
+        self.retry_delay = retry_delay
+        self.persistence = persistence
+        self.max_restart_attempts = max_restart_attempts
+        self.restart_delay = restart_delay
+        self.network_monitoring = network_monitoring
+        self.max_network_retries = max_network_retries
+        self.network_retry_delay = network_retry_delay
+        self.network_timeout = network_timeout
+
+        # Persistence state tracking
+        self._restart_count = 0
+        self._persistence_enabled = persistence
+        self._shutdown_requested = False
+
+        # Network state tracking
+        self._network_retry_count = 0
+        self._last_network_error = None
+        self._network_connected = True
+
+        # Server creation timestamp
+        self._created_at = time.time()
+
+        self.agents: Dict[str, Agent] = {}
+        self.tool_configs: Dict[str, AgentToolConfig] = {}
+        self.task_queues: Dict[str, TaskQueue] = {}
+        self.transport = transport
+
+        self.mcp_server = FastMCP(
+            name=server_name,
+            port=port,
+            log_level=log_level,
+            lifespan=lifespan,
+            auth=auth,
+            transport_security=transport_security,
+            *args,
+            **kwargs,
+        )
+
+        # Configure logger
+        logger.remove()  # Remove default handler
+        logger.add(
+            sys.stderr,
+            level=log_level,
+            format="<green>{time:YYYY-MM-DD HH:mm:ss}</green> | <level>{level: <8}</level> | <cyan>{name}</cyan>:<cyan>{function}</cyan>:<cyan>{line}</cyan> - <level>{message}</level>",
+            colorize=True,
+        )
+
+        logger.info(
+            f"Initialized AOP with server name: {server_name}, verbose: {verbose}, traceback: {traceback_enabled}, persistence: {persistence}, network_monitoring: {network_monitoring}"
+        )
+
+        # Add initial agents if provided
+        if agents:
+            logger.info(f"Adding {len(agents)} initial agents")
+            self.add_agents_batch(agents)
+
+        # Register the agent discovery tool
+        self._register_agent_discovery_tool()
+
+        # Register queue management tools if queue is enabled
+        if self.queue_enabled:
+            self._register_queue_management_tools()
+
+    def add_agent(
+        self,
+        agent: AgentType,
+        tool_name: Optional[str] = None,
+        tool_description: Optional[str] = None,
+        input_schema: Optional[Dict[str, Any]] = None,
+        output_schema: Optional[Dict[str, Any]] = None,
+        timeout: int = 30,
+        max_retries: int = 3,
+        verbose: Optional[bool] = None,
+        traceback_enabled: Optional[bool] = None,
+    ) -> str:
+        """
+        Add an agent to the MCP server as a tool.
+
+        Args:
+            agent: The swarms Agent instance to deploy
+            tool_name: Name for the tool (defaults to agent.agent_name)
+            tool_description: Description of the tool (defaults to agent.agent_description)
+            input_schema: JSON schema for input parameters
+            output_schema: JSON schema for output
+            timeout: Maximum execution time in seconds
+            max_retries: Number of retries on failure
+            verbose: Enable verbose logging for this tool (defaults to deployer's verbose setting)
+            traceback_enabled: Enable traceback logging for this tool (defaults to deployer's setting)
+
+        Returns:
+            str: The tool name that was registered
+
+        Raises:
+            ValueError: If agent is None or tool_name already exists
+        """
+        if agent is None:
+            logger.error("Cannot add None agent")
+            raise ValueError("Agent cannot be None")
+
+        # Use agent name as tool name if not provided
+        if tool_name is None:
+            tool_name = (
+                agent.agent_name or f"agent_{len(self.agents)}"
+            )
+
+        if tool_name in self.agents:
+            logger.error(f"Tool name '{tool_name}' already exists")
+            raise ValueError(
+                f"Tool name '{tool_name}' already exists"
+            )
+
+        # Use deployer defaults if not specified
+        if verbose is None:
+            verbose = self.verbose
+        if traceback_enabled is None:
+            traceback_enabled = self.traceback_enabled
+
+        logger.debug(
+            f"Adding agent '{agent.agent_name}' as tool '{tool_name}' with verbose={verbose}, traceback={traceback_enabled}"
+        )
+
+        # Use agent description if not provided
+        if tool_description is None:
+            tool_description = (
+                agent.agent_description
+                or f"Agent tool: {agent.agent_name}"
+            )
+
+        # Default input schema for task-based agents
+        if input_schema is None:
+            input_schema = {
+                "type": "object",
+                "properties": {
+                    "task": {
+                        "type": "string",
+                        "description": "The task or prompt to execute with this agent",
+                    },
+                    "img": {
+                        "type": "string",
+                        "description": "Optional image to be processed by the agent",
+                    },
+                    "imgs": {
+                        "type": "array",
+                        "items": {"type": "string"},
+                        "description": "Optional list of images to be processed by the agent",
+                    },
+                    "correct_answer": {
+                        "type": "string",
+                        "description": "Optional correct answer for validation or comparison",
+                    },
+                },
+                "required": ["task"],
+            }
+
+        # Default output schema
+        if output_schema is None:
+            output_schema = {
+                "type": "object",
+                "properties": {
+                    "result": {
+                        "type": "string",
+                        "description": "The agent's response to the task",
+                    },
+                    "success": {
+                        "type": "boolean",
+                        "description": "Whether the task was executed successfully",
+                    },
+                    "error": {
+                        "type": "string",
+                        "description": "Error message if execution failed",
+                    },
+                },
+                "required": ["result", "success"],
+            }
+
+        # Store agent and configuration
+        self.agents[tool_name] = agent
+        self.tool_configs[tool_name] = AgentToolConfig(
+            tool_name=tool_name,
+            tool_description=tool_description,
+            input_schema=input_schema,
+            output_schema=output_schema,
+            timeout=timeout,
+            max_retries=max_retries,
+            verbose=verbose,
+            traceback_enabled=traceback_enabled,
+        )
+
+        # Create task queue if queue is enabled
+        if self.queue_enabled:
+            self.task_queues[tool_name] = TaskQueue(
+                agent_name=tool_name,
+                agent=agent,
+                max_workers=self.max_workers_per_agent,
+                max_queue_size=self.max_queue_size_per_agent,
+                processing_timeout=self.processing_timeout,
+                retry_delay=self.retry_delay,
+                verbose=verbose,
+            )
+            # Start the queue workers
+            self.task_queues[tool_name].start_workers()
+
+        # Register the tool with the MCP server
+        self._register_tool(tool_name, agent)
+
+        # Re-register the discovery tool to include the new agent
+        self._register_agent_discovery_tool()
+
+        logger.info(
+            f"Added agent '{agent.agent_name}' as tool '{tool_name}' (verbose={verbose}, traceback={traceback_enabled}, queue_enabled={self.queue_enabled})"
+        )
+        return tool_name
+
+    def add_agents_batch(
+        self,
+        agents: List[Agent],
+        tool_names: Optional[List[str]] = None,
+        tool_descriptions: Optional[List[str]] = None,
+        input_schemas: Optional[List[Dict[str, Any]]] = None,
+        output_schemas: Optional[List[Dict[str, Any]]] = None,
+        timeouts: Optional[List[int]] = None,
+        max_retries_list: Optional[List[int]] = None,
+        verbose_list: Optional[List[bool]] = None,
+        traceback_enabled_list: Optional[List[bool]] = None,
+    ) -> List[str]:
+        """
+        Add multiple agents to the MCP server as tools in batch.
+
+        Args:
+            agents: List of swarms Agent instances
+            tool_names: Optional list of tool names (defaults to agent names)
+            tool_descriptions: Optional list of tool descriptions
+            input_schemas: Optional list of input schemas
+            output_schemas: Optional list of output schemas
+            timeouts: Optional list of timeout values
+            max_retries_list: Optional list of max retry values
+            verbose_list: Optional list of verbose settings for each agent
+            traceback_enabled_list: Optional list of traceback settings for each agent
+
+        Returns:
+            List[str]: List of tool names that were registered
+
+        Raises:
+            ValueError: If agents list is empty or contains None values
+        """
+        if not agents:
+            logger.error("Cannot add empty agents list")
+            raise ValueError("Agents list cannot be empty")
+
+        if None in agents:
+            logger.error("Agents list contains None values")
+            raise ValueError("Agents list cannot contain None values")
+
+        logger.info(f"Adding {len(agents)} agents in batch")
+        registered_tools = []
+
+        for i, agent in enumerate(agents):
+            tool_name = (
+                tool_names[i]
+                if tool_names and i < len(tool_names)
+                else None
+            )
+            tool_description = (
+                tool_descriptions[i]
+                if tool_descriptions and i < len(tool_descriptions)
+                else None
+            )
+            input_schema = (
+                input_schemas[i]
+                if input_schemas and i < len(input_schemas)
+                else None
+            )
+            output_schema = (
+                output_schemas[i]
+                if output_schemas and i < len(output_schemas)
+                else None
+            )
+            timeout = (
+                timeouts[i] if timeouts and i < len(timeouts) else 30
+            )
+            max_retries = (
+                max_retries_list[i]
+                if max_retries_list and i < len(max_retries_list)
+                else 3
+            )
+            verbose = (
+                verbose_list[i]
+                if verbose_list and i < len(verbose_list)
+                else None
+            )
+            traceback_enabled = (
+                traceback_enabled_list[i]
+                if traceback_enabled_list
+                and i < len(traceback_enabled_list)
+                else None
+            )
+
+            tool_name = self.add_agent(
+                agent=agent,
+                tool_name=tool_name,
+                tool_description=tool_description,
+                input_schema=input_schema,
+                output_schema=output_schema,
+                timeout=timeout,
+                max_retries=max_retries,
+                verbose=verbose,
+                traceback_enabled=traceback_enabled,
+            )
+            registered_tools.append(tool_name)
+
+        # Re-register the discovery tool to include all new agents
+        self._register_agent_discovery_tool()
+
+        logger.info(
+            f"Added {len(agents)} agents as tools: {registered_tools}"
+        )
+        return registered_tools
+
+    def _register_tool(
+        self, tool_name: str, agent: AgentType
+    ) -> None:
+        """
+        Register a single agent as an MCP tool.
+
+        Args:
+            tool_name: Name of the tool to register
+            agent: The agent instance to register
+        """
+        config = self.tool_configs[tool_name]
+
+        @self.mcp_server.tool(
+            name=tool_name, description=config.tool_description
+        )
+        def agent_tool(
+            task: str = None,
+            img: str = None,
+            imgs: List[str] = None,
+            correct_answer: str = None,
+            max_retries: int = None,
+        ) -> Dict[str, Any]:
+            """
+            Execute the agent with the provided parameters.
+
+            Args:
+                task: The task or prompt to execute with this agent
+                img: Optional image to be processed by the agent
+                imgs: Optional list of images to be processed by the agent
+                correct_answer: Optional correct answer for validation or comparison
+                max_retries: Maximum number of retries (uses config default if None)
+
+            Returns:
+                Dict containing the agent's response and execution status
+            """
+            start_time = None
+            if config.verbose:
+                start_time = (
+                    asyncio.get_event_loop().time()
+                    if asyncio.get_event_loop().is_running()
+                    else 0
+                )
+                logger.debug(
+                    f"Starting execution of tool '{tool_name}' with task: {task[:100] if task else 'None'}..."
+                )
+                if img:
+                    logger.debug(f"Processing single image: {img}")
+                if imgs:
+                    logger.debug(
+                        f"Processing {len(imgs)} images: {imgs}"
+                    )
+                if correct_answer:
+                    logger.debug(
+                        f"Using correct answer for validation: {correct_answer[:50]}..."
+                    )
+
+            try:
+                # Validate required parameters
+                if not task:
+                    error_msg = "No task provided"
+                    logger.warning(
+                        f"Tool '{tool_name}' called without task parameter"
+                    )
+                    return {
+                        "result": "",
+                        "success": False,
+                        "error": error_msg,
+                    }
+
+                # Use queue-based execution if enabled
+                if (
+                    self.queue_enabled
+                    and tool_name in self.task_queues
+                ):
+                    return self._execute_with_queue(
+                        tool_name,
+                        task,
+                        img,
+                        imgs,
+                        correct_answer,
+                        0,
+                        max_retries,
+                        True,
+                        config,
+                    )
+                else:
+                    # Fallback to direct execution
+                    result = self._execute_agent_with_timeout(
+                        agent,
+                        task,
+                        config.timeout,
+                        img,
+                        imgs,
+                        correct_answer,
+                    )
+
+                    if config.verbose and start_time:
+                        execution_time = (
+                            asyncio.get_event_loop().time()
+                            - start_time
+                            if asyncio.get_event_loop().is_running()
+                            else 0
+                        )
+                        logger.debug(
+                            f"Tool '{tool_name}' completed successfully in {execution_time:.2f}s"
+                        )
+
+                    return {
+                        "result": str(result),
+                        "success": True,
+                        "error": None,
+                    }
+
+            except Exception as e:
+                error_msg = str(e)
+                logger.error(
+                    f"Error executing agent '{tool_name}': {error_msg}"
+                )
+
+                if config.traceback_enabled:
+                    logger.error(f"Traceback for tool '{tool_name}':")
+                    logger.error(traceback.format_exc())
+
+                if config.verbose and start_time:
+                    execution_time = (
+                        asyncio.get_event_loop().time() - start_time
+                        if asyncio.get_event_loop().is_running()
+                        else 0
+                    )
+                    logger.debug(
+                        f"Tool '{tool_name}' failed after {execution_time:.2f}s"
+                    )
+
+                return {
+                    "result": "",
+                    "success": False,
+                    "error": error_msg,
+                }
+
+    def _execute_with_queue(
+        self,
+        tool_name: str,
+        task: str,
+        img: Optional[str],
+        imgs: Optional[List[str]],
+        correct_answer: Optional[str],
+        priority: int,
+        max_retries: Optional[int],
+        wait_for_completion: bool,
+        config: AgentToolConfig,
+    ) -> Dict[str, Any]:
+        """
+        Execute a task using the queue system.
+
+        Args:
+            tool_name: Name of the tool/agent
+            task: The task to execute
+            img: Optional image to process
+            imgs: Optional list of images to process
+            correct_answer: Optional correct answer for validation
+            priority: Task priority
+            max_retries: Maximum number of retries
+            wait_for_completion: Whether to wait for completion
+            config: Tool configuration
+
+        Returns:
+            Dict containing the result or task information
+        """
+        # Safety check: ensure queue is enabled
+        if not self.queue_enabled:
+            logger.error(
+                f"Queue execution attempted but queue is disabled for tool '{tool_name}'"
+            )
+            return {
+                "result": "",
+                "success": False,
+                "error": "Queue system is disabled",
+            }
+
+        # Safety check: ensure task queue exists
+        if tool_name not in self.task_queues:
+            logger.error(
+                f"Task queue not found for tool '{tool_name}'"
+            )
+            return {
+                "result": "",
+                "success": False,
+                "error": f"Task queue not found for agent '{tool_name}'",
+            }
+
+        try:
+            # Use config max_retries if not specified
+            if max_retries is None:
+                max_retries = config.max_retries
+
+            # Add task to queue
+            task_id = self.task_queues[tool_name].add_task(
+                task=task,
+                img=img,
+                imgs=imgs,
+                correct_answer=correct_answer,
+                priority=priority,
+                max_retries=max_retries,
+            )
+
+            if not wait_for_completion:
+                # Return task ID immediately
+                return {
+                    "task_id": task_id,
+                    "status": "queued",
+                    "success": True,
+                    "message": f"Task '{task_id}' queued for agent '{tool_name}'",
+                }
+
+            # Wait for task completion
+            return self._wait_for_task_completion(
+                tool_name, task_id, config.timeout
+            )
+
+        except Exception as e:
+            error_msg = str(e)
+            logger.error(
+                f"Error adding task to queue for '{tool_name}': {error_msg}"
+            )
+            return {
+                "result": "",
+                "success": False,
+                "error": error_msg,
+            }
+
+    def _wait_for_task_completion(
+        self, tool_name: str, task_id: str, timeout: int
+    ) -> Dict[str, Any]:
+        """
+        Wait for a task to complete.
+
+        Args:
+            tool_name: Name of the tool/agent
+            task_id: ID of the task to wait for
+            timeout: Maximum time to wait in seconds
+
+        Returns:
+            Dict containing the task result
+        """
+        # Safety check: ensure queue is enabled
+        if not self.queue_enabled:
+            logger.error(
+                f"Task completion wait attempted but queue is disabled for tool '{tool_name}'"
+            )
+            return {
+                "result": "",
+                "success": False,
+                "error": "Queue system is disabled",
+                "task_id": task_id,
+            }
+
+        # Safety check: ensure task queue exists
+        if tool_name not in self.task_queues:
+            logger.error(
+                f"Task queue not found for tool '{tool_name}'"
+            )
+            return {
+                "result": "",
+                "success": False,
+                "error": f"Task queue not found for agent '{tool_name}'",
+                "task_id": task_id,
+            }
+
+        start_time = time.time()
+
+        while time.time() - start_time < timeout:
+            task = self.task_queues[tool_name].get_task(task_id)
+            if not task:
+                return {
+                    "result": "",
+                    "success": False,
+                    "error": f"Task '{task_id}' not found",
+                }
+
+            if task.status == TaskStatus.COMPLETED:
+                return {
+                    "result": task.result or "",
+                    "success": True,
+                    "error": None,
+                    "task_id": task_id,
+                }
+            elif task.status == TaskStatus.FAILED:
+                return {
+                    "result": "",
+                    "success": False,
+                    "error": task.error or "Task failed",
+                    "task_id": task_id,
+                }
+            elif task.status == TaskStatus.CANCELLED:
+                return {
+                    "result": "",
+                    "success": False,
+                    "error": "Task was cancelled",
+                    "task_id": task_id,
+                }
+
+            # Wait a bit before checking again
+            time.sleep(0.1)
+
+        # Timeout reached
+        return {
+            "result": "",
+            "success": False,
+            "error": f"Task '{task_id}' timed out after {timeout} seconds",
+            "task_id": task_id,
+        }
+
+    def _execute_agent_with_timeout(
+        self,
+        agent: AgentType,
+        task: str,
+        timeout: int,
+        img: str = None,
+        imgs: List[str] = None,
+        correct_answer: str = None,
+    ) -> str:
+        """
+        Execute an agent with a timeout and all run method parameters.
+
+        Args:
+            agent: The agent to execute
+            task: The task to execute
+            timeout: Maximum execution time in seconds
+            img: Optional image to be processed by the agent
+            imgs: Optional list of images to be processed by the agent
+            correct_answer: Optional correct answer for validation or comparison
+
+        Returns:
+            str: The agent's response
+
+        Raises:
+            TimeoutError: If execution exceeds timeout
+            Exception: If agent execution fails
+        """
+        try:
+            logger.debug(
+                f"Executing agent '{agent.agent_name}' with timeout {timeout}s"
+            )
+
+            out = agent.run(
+                task=task,
+                img=img,
+                imgs=imgs,
+                correct_answer=correct_answer,
+            )
+
+            logger.debug(
+                f"Agent '{agent.agent_name}' execution completed successfully"
+            )
+            return out
+
+        except Exception as e:
+            error_msg = f"Agent execution failed: {str(e)}"
+            logger.error(
+                f"Execution error for agent '{agent.agent_name}': {error_msg}"
+            )
+            if self.traceback_enabled:
+                logger.error(
+                    f"Traceback for agent '{agent.agent_name}':"
+                )
+                logger.error(traceback.format_exc())
+            raise Exception(error_msg)
+
+    def remove_agent(self, tool_name: str) -> bool:
+        """
+        Remove an agent from the MCP server.
+
+        Args:
+            tool_name: Name of the tool to remove
+
+        Returns:
+            bool: True if agent was removed, False if not found
+        """
+        if tool_name in self.agents:
+            # Stop and remove task queue if it exists and queue is enabled
+            if self.queue_enabled and tool_name in self.task_queues:
+                self.task_queues[tool_name].stop_workers()
+                del self.task_queues[tool_name]
+
+            del self.agents[tool_name]
+            del self.tool_configs[tool_name]
+            logger.info(f"Removed agent tool '{tool_name}'")
+            return True
+        return False
+
+    def list_agents(self) -> List[str]:
+        """
+        Get a list of all registered agent tool names.
+
+        Returns:
+            List[str]: List of tool names
+        """
+        agent_list = list(self.agents.keys())
+        if self.verbose:
+            logger.debug(
+                f"Listing {len(agent_list)} registered agents: {agent_list}"
+            )
+        return agent_list
+
+    def get_agent_info(
+        self, tool_name: str
+    ) -> Optional[Dict[str, Any]]:
+        """
+        Get information about a specific agent tool.
+
+        Args:
+            tool_name: Name of the tool
+
+        Returns:
+            Dict containing agent information, or None if not found
+        """
+        if tool_name not in self.agents:
+            if self.verbose:
+                logger.debug(
+                    f"Requested info for non-existent agent tool '{tool_name}'"
+                )
+            return None
+
+        agent = self.agents[tool_name]
+        config = self.tool_configs[tool_name]
+
+        info = {
+            "tool_name": tool_name,
+            "agent_name": agent.agent_name,
+            "agent_description": agent.agent_description,
+            "model_name": getattr(agent, "model_name", "Unknown"),
+            "max_loops": getattr(agent, "max_loops", 1),
+            "tool_description": config.tool_description,
+            "timeout": config.timeout,
+            "max_retries": config.max_retries,
+            "verbose": config.verbose,
+            "traceback_enabled": config.traceback_enabled,
+        }
+
+        if self.verbose:
+            logger.debug(
+                f"Retrieved info for agent tool '{tool_name}': {info}"
+            )
+
+        return info
+
+    def get_queue_stats(
+        self, tool_name: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """
+        Get queue statistics for agents.
+
+        Args:
+            tool_name: Optional specific agent name. If None, returns stats for all agents.
+
+        Returns:
+            Dict containing queue statistics
+        """
+        if not self.queue_enabled:
+            return {
+                "success": False,
+                "error": "Queue system is not enabled",
+                "stats": {},
+            }
+
+        try:
+            if tool_name:
+                if tool_name not in self.task_queues:
+                    return {
+                        "success": False,
+                        "error": f"Agent '{tool_name}' not found or has no queue",
+                        "stats": {},
+                    }
+
+                stats = self.task_queues[tool_name].get_stats()
+                return {
+                    "success": True,
+                    "agent_name": tool_name,
+                    "stats": {
+                        "total_tasks": stats.total_tasks,
+                        "completed_tasks": stats.completed_tasks,
+                        "failed_tasks": stats.failed_tasks,
+                        "pending_tasks": stats.pending_tasks,
+                        "processing_tasks": stats.processing_tasks,
+                        "average_processing_time": stats.average_processing_time,
+                        "queue_size": stats.queue_size,
+                        "queue_status": self.task_queues[tool_name]
+                        .get_status()
+                        .value,
+                    },
+                }
+            else:
+                # Get stats for all agents
+                all_stats = {}
+                for name, queue in self.task_queues.items():
+                    stats = queue.get_stats()
+                    all_stats[name] = {
+                        "total_tasks": stats.total_tasks,
+                        "completed_tasks": stats.completed_tasks,
+                        "failed_tasks": stats.failed_tasks,
+                        "pending_tasks": stats.pending_tasks,
+                        "processing_tasks": stats.processing_tasks,
+                        "average_processing_time": stats.average_processing_time,
+                        "queue_size": stats.queue_size,
+                        "queue_status": queue.get_status().value,
+                    }
+
+                return {
+                    "success": True,
+                    "stats": all_stats,
+                    "total_agents": len(all_stats),
+                }
+
+        except Exception as e:
+            error_msg = str(e)
+            logger.error(f"Error getting queue stats: {error_msg}")
+            return {
+                "success": False,
+                "error": error_msg,
+                "stats": {},
+            }
+
+    def pause_agent_queue(self, tool_name: str) -> bool:
+        """
+        Pause the task queue for a specific agent.
+
+        Args:
+            tool_name: Name of the agent tool
+
+        Returns:
+            bool: True if paused successfully, False if not found
+        """
+        if not self.queue_enabled:
+            logger.warning("Queue system is not enabled")
+            return False
+
+        if tool_name not in self.task_queues:
+            logger.warning(
+                f"Agent '{tool_name}' not found or has no queue"
+            )
+            return False
+
+        try:
+            self.task_queues[tool_name].pause_workers()
+            logger.info(f"Paused queue for agent '{tool_name}'")
+            return True
+        except Exception as e:
+            logger.error(
+                f"Error pausing queue for agent '{tool_name}': {e}"
+            )
+            return False
+
+    def resume_agent_queue(self, tool_name: str) -> bool:
+        """
+        Resume the task queue for a specific agent.
+
+        Args:
+            tool_name: Name of the agent tool
+
+        Returns:
+            bool: True if resumed successfully, False if not found
+        """
+        if not self.queue_enabled:
+            logger.warning("Queue system is not enabled")
+            return False
+
+        if tool_name not in self.task_queues:
+            logger.warning(
+                f"Agent '{tool_name}' not found or has no queue"
+            )
+            return False
+
+        try:
+            self.task_queues[tool_name].resume_workers()
+            logger.info(f"Resumed queue for agent '{tool_name}'")
+            return True
+        except Exception as e:
+            logger.error(
+                f"Error resuming queue for agent '{tool_name}': {e}"
+            )
+            return False
+
+    def clear_agent_queue(self, tool_name: str) -> int:
+        """
+        Clear all pending tasks from an agent's queue.
+
+        Args:
+            tool_name: Name of the agent tool
+
+        Returns:
+            int: Number of tasks cleared, -1 if error
+        """
+        if not self.queue_enabled:
+            logger.warning("Queue system is not enabled")
+            return -1
+
+        if tool_name not in self.task_queues:
+            logger.warning(
+                f"Agent '{tool_name}' not found or has no queue"
+            )
+            return -1
+
+        try:
+            cleared_count = self.task_queues[tool_name].clear_queue()
+            logger.info(
+                f"Cleared {cleared_count} tasks from queue for agent '{tool_name}'"
+            )
+            return cleared_count
+        except Exception as e:
+            logger.error(
+                f"Error clearing queue for agent '{tool_name}': {e}"
+            )
+            return -1
+
+    def get_task_status(
+        self, tool_name: str, task_id: str
+    ) -> Dict[str, Any]:
+        """
+        Get the status of a specific task.
+
+        Args:
+            tool_name: Name of the agent tool
+            task_id: ID of the task
+
+        Returns:
+            Dict containing task status information
+        """
+        if not self.queue_enabled:
+            return {
+                "success": False,
+                "error": "Queue system is not enabled",
+                "task": None,
+            }
+
+        if tool_name not in self.task_queues:
+            return {
+                "success": False,
+                "error": f"Agent '{tool_name}' not found or has no queue",
+                "task": None,
+            }
+
+        try:
+            task = self.task_queues[tool_name].get_task(task_id)
+            if not task:
+                return {
+                    "success": False,
+                    "error": f"Task '{task_id}' not found",
+                    "task": None,
+                }
+
+            return {
+                "success": True,
+                "task": {
+                    "task_id": task.task_id,
+                    "status": task.status.value,
+                    "created_at": task.created_at,
+                    "result": task.result,
+                    "error": task.error,
+                    "retry_count": task.retry_count,
+                    "max_retries": task.max_retries,
+                    "priority": task.priority,
+                },
+            }
+        except Exception as e:
+            logger.error(f"Error getting task status: {e}")
+            return {
+                "success": False,
+                "error": str(e),
+                "task": None,
+            }
+
+    def cancel_task(self, tool_name: str, task_id: str) -> bool:
+        """
+        Cancel a specific task.
+
+        Args:
+            tool_name: Name of the agent tool
+            task_id: ID of the task to cancel
+
+        Returns:
+            bool: True if cancelled successfully, False otherwise
+        """
+        if not self.queue_enabled:
+            logger.warning("Queue system is not enabled")
+            return False
+
+        if tool_name not in self.task_queues:
+            logger.warning(
+                f"Agent '{tool_name}' not found or has no queue"
+            )
+            return False
+
+        try:
+            success = self.task_queues[tool_name].cancel_task(task_id)
+            if success:
+                logger.info(
+                    f"Cancelled task '{task_id}' for agent '{tool_name}'"
+                )
+            else:
+                logger.warning(
+                    f"Could not cancel task '{task_id}' for agent '{tool_name}'"
+                )
+            return success
+        except Exception as e:
+            logger.error(f"Error cancelling task '{task_id}': {e}")
+            return False
+
+    def pause_all_queues(self) -> Dict[str, bool]:
+        """
+        Pause all agent queues.
+
+        Returns:
+            Dict mapping agent names to success status
+        """
+        if not self.queue_enabled:
+            logger.warning("Queue system is not enabled")
+            return {}
+
+        results = {}
+        for tool_name in self.task_queues.keys():
+            results[tool_name] = self.pause_agent_queue(tool_name)
+
+        logger.info(
+            f"Paused {sum(results.values())} out of {len(results)} agent queues"
+        )
+        return results
+
+    def resume_all_queues(self) -> Dict[str, bool]:
+        """
+        Resume all agent queues.
+
+        Returns:
+            Dict mapping agent names to success status
+        """
+        if not self.queue_enabled:
+            logger.warning("Queue system is not enabled")
+            return {}
+
+        results = {}
+        for tool_name in self.task_queues.keys():
+            results[tool_name] = self.resume_agent_queue(tool_name)
+
+        logger.info(
+            f"Resumed {sum(results.values())} out of {len(results)} agent queues"
+        )
+        return results
+
+    def clear_all_queues(self) -> Dict[str, int]:
+        """
+        Clear all agent queues.
+
+        Returns:
+            Dict mapping agent names to number of tasks cleared
+        """
+        if not self.queue_enabled:
+            logger.warning("Queue system is not enabled")
+            return {}
+
+        results = {}
+        total_cleared = 0
+        for tool_name in self.task_queues.keys():
+            cleared = self.clear_agent_queue(tool_name)
+            results[tool_name] = cleared
+            if cleared > 0:
+                total_cleared += cleared
+
+        logger.info(
+            f"Cleared {total_cleared} tasks from all agent queues"
+        )
+        return results
+
+    def _register_agent_discovery_tool(self) -> None:
+        """
+        Register the agent discovery tools that allow agents to learn about each other.
+        """
+
+        @self.mcp_server.tool(
+            name="discover_agents",
+            description="Discover information about other agents in the cluster including their name, description, system prompt (truncated to 200 chars), and tags.",
+        )
+        def discover_agents(agent_name: str = None) -> Dict[str, Any]:
+            """
+            Discover information about agents in the cluster.
+
+            Args:
+                agent_name: Optional specific agent name to get info for. If None, returns info for all agents.
+
+            Returns:
+                Dict containing agent information for discovery
+            """
+            try:
+                if agent_name:
+                    # Get specific agent info
+                    if agent_name not in self.agents:
+                        return {
+                            "success": False,
+                            "error": f"Agent '{agent_name}' not found",
+                            "agents": [],
+                        }
+
+                    agent_info = self._get_agent_discovery_info(
+                        agent_name
+                    )
+                    return {
+                        "success": True,
+                        "agents": [agent_info] if agent_info else [],
+                    }
+                else:
+                    # Get all agents info
+                    all_agents_info = []
+                    for tool_name in self.agents.keys():
+                        agent_info = self._get_agent_discovery_info(
+                            tool_name
+                        )
+                        if agent_info:
+                            all_agents_info.append(agent_info)
+
+                    return {
+                        "success": True,
+                        "agents": all_agents_info,
+                    }
+
+            except Exception as e:
+                error_msg = str(e)
+                logger.error(
+                    f"Error in discover_agents tool: {error_msg}"
+                )
+                return {
+                    "success": False,
+                    "error": error_msg,
+                    "agents": [],
+                }
+
+        @self.mcp_server.tool(
+            name="get_agent_details",
+            description="Get detailed information about a single agent by name including configuration, capabilities, and metadata.",
+        )
+        def get_agent_details(agent_name: str) -> Dict[str, Any]:
+            """
+            Get detailed information about a specific agent.
+
+            Args:
+                agent_name: Name of the agent to get information for.
+
+            Returns:
+                Dict containing detailed agent information
+            """
+            try:
+                if agent_name not in self.agents:
+                    return {
+                        "success": False,
+                        "error": f"Agent '{agent_name}' not found",
+                        "agent_info": None,
+                    }
+
+                agent_info = self.get_agent_info(agent_name)
+                discovery_info = self._get_agent_discovery_info(
+                    agent_name
+                )
+
+                return {
+                    "success": True,
+                    "agent_info": agent_info,
+                    "discovery_info": discovery_info,
+                }
+
+            except Exception as e:
+                error_msg = str(e)
+                logger.error(
+                    f"Error in get_agent_details tool: {error_msg}"
+                )
+                return {
+                    "success": False,
+                    "error": error_msg,
+                    "agent_info": None,
+                }
+
+        @self.mcp_server.tool(
+            name="get_agents_info",
+            description="Get detailed information about multiple agents by providing a list of agent names.",
+        )
+        def get_agents_info(agent_names: List[str]) -> Dict[str, Any]:
+            """
+            Get detailed information about multiple agents.
+
+            Args:
+                agent_names: List of agent names to get information for.
+
+            Returns:
+                Dict containing detailed information for all requested agents
+            """
+            try:
+                if not agent_names:
+                    return {
+                        "success": False,
+                        "error": "No agent names provided",
+                        "agents_info": [],
+                    }
+
+                agents_info = []
+                not_found = []
+
+                for agent_name in agent_names:
+                    if agent_name in self.agents:
+                        agent_info = self.get_agent_info(agent_name)
+                        discovery_info = (
+                            self._get_agent_discovery_info(agent_name)
+                        )
+                        agents_info.append(
+                            {
+                                "agent_name": agent_name,
+                                "agent_info": agent_info,
+                                "discovery_info": discovery_info,
+                            }
+                        )
+                    else:
+                        not_found.append(agent_name)
+
+                return {
+                    "success": True,
+                    "agents_info": agents_info,
+                    "not_found": not_found,
+                    "total_found": len(agents_info),
+                    "total_requested": len(agent_names),
+                }
+
+            except Exception as e:
+                error_msg = str(e)
+                logger.error(
+                    f"Error in get_agents_info tool: {error_msg}"
+                )
+                return {
+                    "success": False,
+                    "error": error_msg,
+                    "agents_info": [],
+                }
+
+        @self.mcp_server.tool(
+            name="list_agents",
+            description="Get a simple list of all available agent names in the cluster.",
+        )
+        def list_agents() -> Dict[str, Any]:
+            """
+            Get a list of all available agent names.
+
+            Returns:
+                Dict containing the list of agent names
+            """
+            try:
+                agent_names = self.list_agents()
+                return {
+                    "success": True,
+                    "agent_names": agent_names,
+                    "total_count": len(agent_names),
+                }
+
+            except Exception as e:
+                error_msg = str(e)
+                logger.error(
+                    f"Error in list_agents tool: {error_msg}"
+                )
+                return {
+                    "success": False,
+                    "error": error_msg,
+                    "agent_names": [],
+                }
+
+        @self.mcp_server.tool(
+            name="search_agents",
+            description="Search for agents by name, description, tags, or capabilities using keyword matching.",
+        )
+        def search_agents(
+            query: str, search_fields: List[str] = None
+        ) -> Dict[str, Any]:
+            """
+            Search for agents using keyword matching.
+
+            Args:
+                query: Search query string
+                search_fields: Optional list of fields to search in (name, description, tags, capabilities).
+                              If None, searches all fields.
+
+            Returns:
+                Dict containing matching agents
+            """
+            try:
+                if not query:
+                    return {
+                        "success": False,
+                        "error": "No search query provided",
+                        "matching_agents": [],
+                    }
+
+                # Default search fields
+                if search_fields is None:
+                    search_fields = [
+                        "name",
+                        "description",
+                        "tags",
+                        "capabilities",
+                    ]
+
+                query_lower = query.lower()
+                matching_agents = []
+
+                for tool_name in self.agents.keys():
+                    discovery_info = self._get_agent_discovery_info(
+                        tool_name
+                    )
+                    if not discovery_info:
+                        continue
+
+                    match_found = False
+
+                    # Search in specified fields
+                    for field in search_fields:
+                        if (
+                            field == "name"
+                            and query_lower
+                            in discovery_info.get(
+                                "agent_name", ""
+                            ).lower()
+                        ):
+                            match_found = True
+                            break
+                        elif (
+                            field == "description"
+                            and query_lower
+                            in discovery_info.get(
+                                "description", ""
+                            ).lower()
+                        ):
+                            match_found = True
+                            break
+                        elif field == "tags":
+                            tags = discovery_info.get("tags", [])
+                            if any(
+                                query_lower in tag.lower()
+                                for tag in tags
+                            ):
+                                match_found = True
+                                break
+                        elif field == "capabilities":
+                            capabilities = discovery_info.get(
+                                "capabilities", []
+                            )
+                            if any(
+                                query_lower in capability.lower()
+                                for capability in capabilities
+                            ):
+                                match_found = True
+                                break
+
+                    if match_found:
+                        matching_agents.append(discovery_info)
+
+                return {
+                    "success": True,
+                    "matching_agents": matching_agents,
+                    "total_matches": len(matching_agents),
+                    "query": query,
+                    "search_fields": search_fields,
+                }
+
+            except Exception as e:
+                error_msg = str(e)
+                logger.error(
+                    f"Error in search_agents tool: {error_msg}"
+                )
+                return {
+                    "success": False,
+                    "error": error_msg,
+                    "matching_agents": [],
+                }
+
+        @self.mcp_server.tool(
+            name="get_server_info",
+            description="Get comprehensive server information including metadata, configuration, tool details, queue stats, and network status.",
+        )
+        def get_server_info_tool() -> Dict[str, Any]:
+            """
+            Get comprehensive information about the MCP server and registered tools.
+
+            Returns:
+                Dict containing server information with the following fields:
+                - server_name: Name of the server
+                - description: Server description
+                - total_tools/total_agents: Total number of agents registered
+                - tools/agent_names: List of all agent names
+                - created_at: Unix timestamp when server was created
+                - created_at_iso: ISO formatted creation time
+                - uptime_seconds: Server uptime in seconds
+                - host: Server host address
+                - port: Server port number
+                - transport: Transport protocol used
+                - log_level: Logging level
+                - queue_enabled: Whether queue system is enabled
+                - persistence_enabled: Whether persistence mode is enabled
+                - network_monitoring_enabled: Whether network monitoring is enabled
+                - persistence: Detailed persistence status
+                - network: Detailed network status
+                - tool_details: Detailed information about each agent tool
+                - queue_config: Queue configuration (if queue enabled)
+                - queue_stats: Queue statistics for each agent (if queue enabled)
+            """
+            try:
+                server_info = self.get_server_info()
+                return {
+                    "success": True,
+                    "server_info": server_info,
+                }
+            except Exception as e:
+                error_msg = str(e)
+                logger.error(
+                    f"Error in get_server_info tool: {error_msg}"
+                )
+                return {
+                    "success": False,
+                    "error": error_msg,
+                    "server_info": None,
+                }
+
+    def _register_queue_management_tools(self) -> None:
+        """
+        Register queue management tools for the MCP server.
+        """
+
+        @self.mcp_server.tool(
+            name="get_queue_stats",
+            description="Get queue statistics for agents including task counts, processing times, and queue status.",
+        )
+        def get_queue_stats(agent_name: str = None) -> Dict[str, Any]:
+            """
+            Get queue statistics for agents.
+
+            Args:
+                agent_name: Optional specific agent name. If None, returns stats for all agents.
+
+            Returns:
+                Dict containing queue statistics
+            """
+            return self.get_queue_stats(agent_name)
+
+        @self.mcp_server.tool(
+            name="pause_agent_queue",
+            description="Pause the task queue for a specific agent.",
+        )
+        def pause_agent_queue(agent_name: str) -> Dict[str, Any]:
+            """
+            Pause the task queue for a specific agent.
+
+            Args:
+                agent_name: Name of the agent tool
+
+            Returns:
+                Dict containing success status
+            """
+            success = self.pause_agent_queue(agent_name)
+            return {
+                "success": success,
+                "message": f"Queue for agent '{agent_name}' {'paused' if success else 'not found or already paused'}",
+            }
+
+        @self.mcp_server.tool(
+            name="resume_agent_queue",
+            description="Resume the task queue for a specific agent.",
+        )
+        def resume_agent_queue(agent_name: str) -> Dict[str, Any]:
+            """
+            Resume the task queue for a specific agent.
+
+            Args:
+                agent_name: Name of the agent tool
+
+            Returns:
+                Dict containing success status
+            """
+            success = self.resume_agent_queue(agent_name)
+            return {
+                "success": success,
+                "message": f"Queue for agent '{agent_name}' {'resumed' if success else 'not found or already running'}",
+            }
+
+        @self.mcp_server.tool(
+            name="clear_agent_queue",
+            description="Clear all pending tasks from an agent's queue.",
+        )
+        def clear_agent_queue(agent_name: str) -> Dict[str, Any]:
+            """
+            Clear all pending tasks from an agent's queue.
+
+            Args:
+                agent_name: Name of the agent tool
+
+            Returns:
+                Dict containing number of tasks cleared
+            """
+            cleared_count = self.clear_agent_queue(agent_name)
+            return {
+                "success": cleared_count >= 0,
+                "cleared_tasks": cleared_count,
+                "message": (
+                    f"Cleared {cleared_count} tasks from queue for agent '{agent_name}'"
+                    if cleared_count >= 0
+                    else f"Failed to clear queue for agent '{agent_name}'"
+                ),
+            }
+
+        @self.mcp_server.tool(
+            name="get_task_status",
+            description="Get the status of a specific task by task ID.",
+        )
+        def get_task_status(
+            agent_name: str, task_id: str
+        ) -> Dict[str, Any]:
+            """
+            Get the status of a specific task.
+
+            Args:
+                agent_name: Name of the agent tool
+                task_id: ID of the task
+
+            Returns:
+                Dict containing task status information
+            """
+            return self.get_task_status(agent_name, task_id)
+
+        @self.mcp_server.tool(
+            name="cancel_task",
+            description="Cancel a specific task by task ID.",
+        )
+        def cancel_task(
+            agent_name: str, task_id: str
+        ) -> Dict[str, Any]:
+            """
+            Cancel a specific task.
+
+            Args:
+                agent_name: Name of the agent tool
+                task_id: ID of the task to cancel
+
+            Returns:
+                Dict containing success status
+            """
+            success = self.cancel_task(agent_name, task_id)
+            return {
+                "success": success,
+                "message": f"Task '{task_id}' {'cancelled' if success else 'not found or already processed'}",
+            }
+
+        @self.mcp_server.tool(
+            name="pause_all_queues",
+            description="Pause all agent queues.",
+        )
+        def pause_all_queues() -> Dict[str, Any]:
+            """
+            Pause all agent queues.
+
+            Returns:
+                Dict containing results for each agent
+            """
+            results = self.pause_all_queues()
+            return {
+                "success": True,
+                "results": results,
+                "total_agents": len(results),
+                "successful_pauses": sum(results.values()),
+            }
+
+        @self.mcp_server.tool(
+            name="resume_all_queues",
+            description="Resume all agent queues.",
+        )
+        def resume_all_queues() -> Dict[str, Any]:
+            """
+            Resume all agent queues.
+
+            Returns:
+                Dict containing results for each agent
+            """
+            results = self.resume_all_queues()
+            return {
+                "success": True,
+                "results": results,
+                "total_agents": len(results),
+                "successful_resumes": sum(results.values()),
+            }
+
+        @self.mcp_server.tool(
+            name="clear_all_queues",
+            description="Clear all agent queues.",
+        )
+        def clear_all_queues() -> Dict[str, Any]:
+            """
+            Clear all agent queues.
+
+            Returns:
+                Dict containing results for each agent
+            """
+            results = self.clear_all_queues()
+            total_cleared = sum(results.values())
+            return {
+                "success": True,
+                "results": results,
+                "total_agents": len(results),
+                "total_cleared": total_cleared,
+            }
+
+    def _get_agent_discovery_info(
+        self, tool_name: str
+    ) -> Optional[Dict[str, Any]]:
+        """
+        Get discovery information for a specific agent.
+
+        Args:
+            tool_name: Name of the agent tool
+
+        Returns:
+            Dict containing agent discovery information, or None if not found
+        """
+        if tool_name not in self.agents:
+            return None
+
+        agent = self.agents[tool_name]
+
+        # Get system prompt and truncate to 200 characters
+        system_prompt = getattr(agent, "system_prompt", "")
+        short_system_prompt = (
+            system_prompt[:200] + "..."
+            if len(system_prompt) > 200
+            else system_prompt
+        )
+
+        # Get tags (if available)
+        tags = getattr(agent, "tags", [])
+        if not tags:
+            tags = []
+
+        # Get capabilities (if available)
+        capabilities = getattr(agent, "capabilities", [])
+        if not capabilities:
+            capabilities = []
+
+        # Get role (if available)
+        role = getattr(agent, "role", "worker")
+
+        # Get model name
+        model_name = getattr(agent, "model_name", "Unknown")
+
+        info = {
+            "tool_name": tool_name,
+            "agent_name": agent.agent_name,
+            "description": agent.agent_description
+            or "No description available",
+            "short_system_prompt": short_system_prompt,
+            "tags": tags,
+            "capabilities": capabilities,
+            "role": role,
+            "model_name": model_name,
+            "max_loops": getattr(agent, "max_loops", 1),
+            "temperature": getattr(agent, "temperature", 0.5),
+            "max_tokens": getattr(agent, "max_tokens", 4096),
+        }
+
+        if self.verbose:
+            logger.debug(
+                f"Retrieved discovery info for agent '{tool_name}': {info}"
+            )
+
+        return info
+
+    def start_server(self) -> None:
+        """
+        Start the MCP server.
+
+        Args:
+            host: Host to bind the server to
+            port: Port to bind the server to
+        """
+        logger.info(
+            f"Starting MCP server '{self.server_name}' on {self.host}:{self.port}\n"
+            f"Transport: {self.transport}\n"
+            f"Log level: {self.log_level}\n"
+            f"Verbose mode: {self.verbose}\n"
+            f"Traceback enabled: {self.traceback_enabled}\n"
+            f"Queue enabled: {self.queue_enabled}\n"
+            f"Available tools: {self.list_agents()}"
+        )
+
+        if self.verbose:
+            logger.debug(
+                "Server configuration:\n"
+                f"  - Server name: {self.server_name}\n"
+                f"  - Host: {self.host}\n"
+                f"  - Port: {self.port}\n"
+                f"  - Transport: {self.transport}\n"
+                f"  - Queue enabled: {self.queue_enabled}\n"
+                f"  - Total agents: {len(self.agents)}"
+            )
+            for tool_name, config in self.tool_configs.items():
+                logger.debug(
+                    f"  - Tool '{tool_name}': timeout={config.timeout}s, verbose={config.verbose}, traceback={config.traceback_enabled}"
+                )
+
+            if self.queue_enabled:
+                logger.debug(
+                    f"  - Max workers per agent: {self.max_workers_per_agent}"
+                )
+                logger.debug(
+                    f"  - Max queue size per agent: {self.max_queue_size_per_agent}"
+                )
+                logger.debug(
+                    f"  - Processing timeout: {self.processing_timeout}s"
+                )
+                logger.debug(f"  - Retry delay: {self.retry_delay}s")
+
+        try:
+            self.mcp_server.run(transport=self.transport)
+        except KeyboardInterrupt:
+            logger.info("Server interrupted by user")
+        finally:
+            # Clean up queues when server stops
+            if self.queue_enabled:
+                logger.info("Stopping all agent queues...")
+                for tool_name in list(self.task_queues.keys()):
+                    try:
+                        self.task_queues[tool_name].stop_workers()
+                        logger.debug(
+                            f"Stopped queue for agent '{tool_name}'"
+                        )
+                    except Exception as e:
+                        logger.error(
+                            f"Error stopping queue for agent '{tool_name}': {e}"
+                        )
+
+        logger.info(
+            f"MCP Server '{self.server_name}' is ready with {len(self.agents)} tools"
+        )
+        logger.info(
+            f"Tools available: {', '.join(self.list_agents())}"
+        )
+
+    def run(self) -> None:
+        """
+        Run the MCP server with optional persistence.
+
+        If persistence is enabled, the server will automatically restart
+        when stopped, up to max_restart_attempts times. This includes
+        a failsafe mechanism to prevent infinite restart loops.
+        """
+        if not self._persistence_enabled:
+            # Standard run without persistence
+            self.start_server()
+            return
+
+        # Persistence-enabled run
+        logger.info(
+            f"Starting AOP server with persistence enabled (max restarts: {self.max_restart_attempts})"
+        )
+
+        while (
+            not self._shutdown_requested
+            and self._restart_count <= self.max_restart_attempts
+        ):
+            try:
+                if self._restart_count > 0:
+                    logger.info(
+                        f"Restarting server (attempt {self._restart_count}/{self.max_restart_attempts})"
+                    )
+                    # Wait before restarting
+                    time.sleep(self.restart_delay)
+
+                # Reset restart count on successful start
+                self._restart_count = 0
+                self.start_server()
+
+            except KeyboardInterrupt:
+                if (
+                    self._persistence_enabled
+                    and not self._shutdown_requested
+                ):
+                    logger.warning(
+                        "Server interrupted by user, but persistence is enabled. Restarting..."
+                    )
+                    self._restart_count += 1
+                    continue
+                else:
+                    logger.info("Server shutdown requested by user")
+                    break
+
+            except Exception as e:
+                if (
+                    self._persistence_enabled
+                    and not self._shutdown_requested
+                ):
+                    # Check if it's a network error
+                    if self._is_network_error(e):
+                        logger.warning(
+                            "🌐 Network error detected, attempting reconnection..."
+                        )
+                        if self._handle_network_error(e):
+                            # Network retry successful, continue with restart
+                            self._restart_count += 1
+                            continue
+                        else:
+                            # Network retry failed, give up
+                            logger.critical(
+                                "💀 Network reconnection failed permanently"
+                            )
+                            break
+                    else:
+                        # Non-network error, use standard restart logic
+                        logger.error(
+                            f"Server crashed with error: {e}"
+                        )
+                        self._restart_count += 1
+
+                        if (
+                            self._restart_count
+                            > self.max_restart_attempts
+                        ):
+                            logger.critical(
+                                f"Maximum restart attempts ({self.max_restart_attempts}) exceeded. Shutting down permanently."
+                            )
+                            break
+                        else:
+                            logger.info(
+                                f"Will restart in {self.restart_delay} seconds..."
+                            )
+                            continue
+                else:
+                    # Check if it's a network error even without persistence
+                    if self._is_network_error(e):
+                        logger.error(
+                            "🌐 Network error detected but persistence is disabled"
+                        )
+                        if self.network_monitoring:
+                            logger.info(
+                                "🔄 Attempting network reconnection..."
+                            )
+                            if self._handle_network_error(e):
+                                # Try to start server again after network recovery
+                                try:
+                                    self.start_server()
+                                    return
+                                except Exception as retry_error:
+                                    logger.error(
+                                        f"Server failed after network recovery: {retry_error}"
+                                    )
+                                    raise
+                            else:
+                                logger.critical(
+                                    "💀 Network reconnection failed"
+                                )
+                                raise
+                        else:
+                            logger.error(
+                                "Network monitoring is disabled, cannot retry"
+                            )
+                            raise
+                    else:
+                        logger.error(
+                            f"Server failed and persistence is disabled: {e}"
+                        )
+                        raise
+
+        if self._restart_count > self.max_restart_attempts:
+            logger.critical(
+                "Server failed permanently due to exceeding maximum restart attempts"
+            )
+        elif self._shutdown_requested:
+            logger.info("Server shutdown completed as requested")
+        else:
+            logger.info("Server stopped normally")
+
+    def _is_network_error(self, error: Exception) -> bool:
+        """
+        Check if an error is network-related.
+
+        Args:
+            error: The exception to check
+
+        Returns:
+            bool: True if the error is network-related
+        """
+        network_errors = (
+            ConnectionError,
+            ConnectionRefusedError,
+            ConnectionResetError,
+            ConnectionAbortedError,
+            TimeoutError,
+            socket.gaierror,
+            socket.timeout,
+            OSError,
+        )
+
+        # Check if it's a direct network error
+        if isinstance(error, network_errors):
+            return True
+
+        # Check error message for network-related keywords
+        error_msg = str(error).lower()
+        network_keywords = [
+            "connection refused",
+            "connection reset",
+            "connection aborted",
+            "network is unreachable",
+            "no route to host",
+            "timeout",
+            "socket",
+            "network",
+            "connection",
+            "refused",
+            "reset",
+            "aborted",
+            "unreachable",
+            "timeout",
+        ]
+
+        return any(
+            keyword in error_msg for keyword in network_keywords
+        )
+
+    def _get_network_error_message(
+        self, error: Exception, attempt: int
+    ) -> str:
+        """
+        Get a custom error message for network-related errors.
+
+        Args:
+            error: The network error that occurred
+            attempt: Current retry attempt number
+
+        Returns:
+            str: Custom error message
+        """
+        error_type = type(error).__name__
+        error_msg = str(error)
+
+        if isinstance(error, ConnectionRefusedError):
+            return f"🌐 NETWORK ERROR: Connection refused to {self.host}:{self.port} (attempt {attempt}/{self.max_network_retries})"
+        elif isinstance(error, ConnectionResetError):
+            return f"🌐 NETWORK ERROR: Connection was reset by remote host (attempt {attempt}/{self.max_network_retries})"
+        elif isinstance(error, ConnectionAbortedError):
+            return f"🌐 NETWORK ERROR: Connection was aborted (attempt {attempt}/{self.max_network_retries})"
+        elif isinstance(error, TimeoutError):
+            return f"🌐 NETWORK ERROR: Connection timeout after {self.network_timeout}s (attempt {attempt}/{self.max_network_retries})"
+        elif isinstance(error, socket.gaierror):
+            return f"🌐 NETWORK ERROR: Host resolution failed for {self.host} (attempt {attempt}/{self.max_network_retries})"
+        elif isinstance(error, OSError):
+            return f"🌐 NETWORK ERROR: OS-level network error - {error_msg} (attempt {attempt}/{self.max_network_retries})"
+        else:
+            return f"🌐 NETWORK ERROR: {error_type} - {error_msg} (attempt {attempt}/{self.max_network_retries})"
+
+    def _test_network_connectivity(self) -> bool:
+        """
+        Test network connectivity to the server host and port.
+
+        Returns:
+            bool: True if network is reachable, False otherwise
+        """
+        try:
+            # Test if we can resolve the host
+            socket.gethostbyname(self.host)
+
+            # Test if we can connect to the port
+            sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+            sock.settimeout(self.network_timeout)
+            result = sock.connect_ex((self.host, self.port))
+            sock.close()
+
+            return result == 0
+        except Exception as e:
+            if self.verbose:
+                logger.debug(f"Network connectivity test failed: {e}")
+            return False
+
+    def _handle_network_error(self, error: Exception) -> bool:
+        """
+        Handle network errors with retry logic.
+
+        Args:
+            error: The network error that occurred
+
+        Returns:
+            bool: True if should retry, False if should give up
+        """
+        if not self.network_monitoring:
+            return False
+
+        self._network_retry_count += 1
+        self._last_network_error = error
+        self._network_connected = False
+
+        # Get custom error message
+        error_msg = self._get_network_error_message(
+            error, self._network_retry_count
+        )
+        logger.error(error_msg)
+
+        # Check if we should retry
+        if self._network_retry_count <= self.max_network_retries:
+            logger.warning(
+                f"🔄 Attempting to reconnect in {self.network_retry_delay} seconds..."
+            )
+            logger.info(
+                f"📊 Network retry {self._network_retry_count}/{self.max_network_retries}"
+            )
+
+            # Wait before retry
+            time.sleep(self.network_retry_delay)
+
+            # Test connectivity before retry
+            if self._test_network_connectivity():
+                logger.info("✅ Network connectivity restored!")
+                self._network_connected = True
+                self._network_retry_count = (
+                    0  # Reset on successful test
+                )
+                return True
+            else:
+                logger.warning(
+                    "❌ Network connectivity test failed, will retry..."
+                )
+                return True
+        else:
+            logger.critical(
+                f"💀 Maximum network retry attempts ({self.max_network_retries}) exceeded!"
+            )
+            logger.critical(
+                "🚫 Giving up on network reconnection. Server will shut down."
+            )
+            return False
+
+    def get_network_status(self) -> Dict[str, Any]:
+        """
+        Get current network status and statistics.
+
+        Returns:
+            Dict containing network status information
+        """
+        return {
+            "network_monitoring_enabled": self.network_monitoring,
+            "network_connected": self._network_connected,
+            "network_retry_count": self._network_retry_count,
+            "max_network_retries": self.max_network_retries,
+            "network_retry_delay": self.network_retry_delay,
+            "network_timeout": self.network_timeout,
+            "last_network_error": (
+                str(self._last_network_error)
+                if self._last_network_error
+                else None
+            ),
+            "remaining_network_retries": max(
+                0,
+                self.max_network_retries - self._network_retry_count,
+            ),
+            "host": self.host,
+            "port": self.port,
+        }
+
+    def reset_network_retry_count(self) -> None:
+        """
+        Reset the network retry counter.
+
+        This can be useful if you want to give the server a fresh
+        set of network retry attempts.
+        """
+        self._network_retry_count = 0
+        self._last_network_error = None
+        self._network_connected = True
+        logger.info("Network retry counter reset")
+
+    def enable_persistence(self) -> None:
+        """
+        Enable persistence mode for the server.
+
+        This allows the server to automatically restart when stopped,
+        up to the maximum number of restart attempts.
+        """
+        self._persistence_enabled = True
+        logger.info("Persistence mode enabled")
+
+    def disable_persistence(self) -> None:
+        """
+        Disable persistence mode for the server.
+
+        This will allow the server to shut down normally without
+        automatic restarts.
+        """
+        self._persistence_enabled = False
+        self._shutdown_requested = True
+        logger.info(
+            "Persistence mode disabled - server will shut down on next stop"
+        )
+
+    def request_shutdown(self) -> None:
+        """
+        Request a graceful shutdown of the server.
+
+        If persistence is enabled, this will prevent automatic restarts
+        and allow the server to shut down normally.
+        """
+        self._shutdown_requested = True
+        logger.info(
+            "Shutdown requested - server will stop after current operations complete"
+        )
+
+    def get_persistence_status(self) -> Dict[str, Any]:
+        """
+        Get the current persistence status and statistics.
+
+        Returns:
+            Dict containing persistence configuration and status
+        """
+        return {
+            "persistence_enabled": self._persistence_enabled,
+            "shutdown_requested": self._shutdown_requested,
+            "restart_count": self._restart_count,
+            "max_restart_attempts": self.max_restart_attempts,
+            "restart_delay": self.restart_delay,
+            "remaining_restarts": max(
+                0, self.max_restart_attempts - self._restart_count
+            ),
+        }
+
+    def reset_restart_count(self) -> None:
+        """
+        Reset the restart counter.
+
+        This can be useful if you want to give the server a fresh
+        set of restart attempts.
+        """
+        self._restart_count = 0
+        logger.info("Restart counter reset")
+
+    def get_server_info(self) -> Dict[str, Any]:
+        """
+        Get information about the MCP server and registered tools.
+
+        Returns:
+            Dict containing server information including metadata, configuration,
+            and tool details
+        """
+        info = {
+            "server_name": self.server_name,
+            "description": self.description,
+            "total_tools": len(self.agents),
+            "total_agents": len(
+                self.agents
+            ),  # Alias for compatibility
+            "tools": self.list_agents(),
+            "agent_names": self.list_agents(),  # Alias for compatibility
+            "created_at": self._created_at,
+            "created_at_iso": time.strftime(
+                "%Y-%m-%d %H:%M:%S", time.localtime(self._created_at)
+            ),
+            "uptime_seconds": time.time() - self._created_at,
+            "verbose": self.verbose,
+            "traceback_enabled": self.traceback_enabled,
+            "log_level": self.log_level,
+            "transport": self.transport,
+            "host": self.host,
+            "port": self.port,
+            "queue_enabled": self.queue_enabled,
+            "persistence_enabled": self._persistence_enabled,  # Top-level for compatibility
+            "network_monitoring_enabled": self.network_monitoring,  # Top-level for compatibility
+            "persistence": self.get_persistence_status(),
+            "network": self.get_network_status(),
+            "tool_details": {
+                tool_name: self.get_agent_info(tool_name)
+                for tool_name in self.agents.keys()
+            },
+        }
+
+        # Add queue information if enabled
+        if self.queue_enabled:
+            info["queue_config"] = {
+                "max_workers_per_agent": self.max_workers_per_agent,
+                "max_queue_size_per_agent": self.max_queue_size_per_agent,
+                "processing_timeout": self.processing_timeout,
+                "retry_delay": self.retry_delay,
+            }
+
+            # Add queue stats for each agent
+            queue_stats = {}
+            for tool_name in self.agents.keys():
+                if tool_name in self.task_queues:
+                    stats = self.task_queues[tool_name].get_stats()
+                    queue_stats[tool_name] = {
+                        "status": self.task_queues[tool_name]
+                        .get_status()
+                        .value,
+                        "total_tasks": stats.total_tasks,
+                        "completed_tasks": stats.completed_tasks,
+                        "failed_tasks": stats.failed_tasks,
+                        "pending_tasks": stats.pending_tasks,
+                        "processing_tasks": stats.processing_tasks,
+                        "average_processing_time": stats.average_processing_time,
+                        "queue_size": stats.queue_size,
+                    }
+
+            info["queue_stats"] = queue_stats
+
+        if self.verbose:
+            logger.debug(f"Retrieved server info: {info}")
+
+        return info
+
+
+class AOPCluster:
+    """
+    AOPCluster manages a cluster of MCP servers, allowing for the retrieval and searching
+    of tools (agents) across multiple endpoints.
+
+    Attributes:
+        urls (List[str]): List of MCP server URLs to connect to.
+        transport (str): The transport protocol to use (default: "streamable-http").
+    """
+
+    def __init__(
+        self,
+        urls: List[str],
+        transport: str = "streamable-http",
+        *args,
+        **kwargs,
+    ):
+        """
+        Initialize the AOPCluster.
+
+        Args:
+            urls (List[str]): List of MCP server URLs.
+            transport (str, optional): Transport protocol to use. Defaults to "streamable-http".
+            *args: Additional positional arguments.
+            **kwargs: Additional keyword arguments.
+        """
+        self.urls = urls
+        self.transport = transport
+
+    def get_tools(
+        self, output_type: Literal["json", "dict", "str"] = "dict"
+    ) -> List[Dict[str, Any]]:
+        """
+        Retrieve the list of tools (agents) from all MCP servers in the cluster.
+
+        Args:
+            output_type (Literal["json", "dict", "str"], optional): The format of the output.
+                Can be "json", "dict", or "str". Defaults to "dict".
+
+        Returns:
+            List[Dict[str, Any]]: A list of tool information dictionaries.
+        """
+        return get_tools_for_multiple_mcp_servers(
+            urls=self.urls,
+            format="openai",
+            output_type=output_type,
+            transport=self.transport,
+        )
+
+    def find_tool_by_server_name(
+        self, server_name: str
+    ) -> Dict[str, Any]:
+        """
+        Find a tool by its server name (function name).
+
+        Args:
+            server_name (str): The name of the tool/function to find.
+
+        Returns:
+            Dict[str, Any]: Dictionary containing the tool information, or None if not found.
+        """
+        for tool in self.get_tools(output_type="dict"):
+            if tool.get("function", {}).get("name") == server_name:
+                return tool
+        return None