fast-agent-mcp 0.0.12__py3-none-any.whl → 0.0.14__py3-none-any.whl

mcp_agent/core/fastagent.py

@@ -3,7 +3,17 @@ Decorator-based interface for MCP Agent applications.
 Provides a simplified way to create and manage agents using decorators.
 """
 
-from typing import List, Optional, Dict, Callable, TypeVar, Any, Union, TypeAlias
+from typing import (
+    List,
+    Optional,
+    Dict,
+    Callable,
+    TypeVar,
+    Any,
+    Union,
+    TypeAlias,
+    Literal,
+)
 from enum import Enum
 import yaml
 import argparse
@@ -11,6 +21,9 @@ from contextlib import asynccontextmanager
 
 from mcp_agent.core.exceptions import (
     AgentConfigError,
+    CircularDependencyError,
+    ModelConfigError,
+    PromptExitError,
     ServerConfigError,
     ProviderKeyError,
     ServerInitializationError,
@@ -52,6 +65,7 @@ class AgentType(Enum):
     PARALLEL = "parallel"
     EVALUATOR_OPTIMIZER = "evaluator_optimizer"
     ROUTER = "router"
+    CHAIN = "chain"
 
 
 T = TypeVar("T")  # For the wrapper classes
@@ -138,6 +152,27 @@ class RouterProxy(BaseAgentProxy):
         return f"Routed to: {top_result.result} ({top_result.confidence}): {top_result.reasoning}"
 
 
+class ChainProxy(BaseAgentProxy):
+    """Proxy for chained agent operations"""
+
+    def __init__(
+        self, app: MCPApp, name: str, sequence: List[str], agent_proxies: ProxyDict
+    ):
+        super().__init__(app, name)
+        self._sequence = sequence
+        self._agent_proxies = agent_proxies
+
+    async def generate_str(self, message: str) -> str:
+        """Chain message through a sequence of agents"""
+        current_message = message
+
+        for agent_name in self._sequence:
+            proxy = self._agent_proxies[agent_name]
+            current_message = await proxy.generate_str(current_message)
+
+        return current_message
+
+
 class AgentApp:
     """Main application wrapper"""
 
@@ -175,7 +210,7 @@ class AgentApp:
 
         # Pass all available agent names for auto-completion
         available_agents = list(self._agents.keys())
-        
+
         # Create agent_types dictionary mapping agent names to their types
         agent_types = {}
         for name, proxy in self._agents.items():
@@ -185,6 +220,8 @@ class AgentApp:
                 agent_types[name] = "Agent"
             elif isinstance(proxy, RouterProxy):
                 agent_types[name] = "Router"
+            elif isinstance(proxy, ChainProxy):
+                agent_types[name] = "Chain"
             elif isinstance(proxy, WorkflowProxy):
                 # For workflow proxies, check the workflow type
                 workflow = proxy._workflow
@@ -228,7 +265,7 @@ class AgentApp:
                     continue
 
                 if user_input.upper() == "STOP":
-                    return
+                    return result
                 if user_input == "":
                     continue
 
@@ -311,6 +348,7 @@ class FastAgent(ContextDependent):
         if agent_type not in [
             AgentType.PARALLEL.value,
             AgentType.EVALUATOR_OPTIMIZER.value,
+            AgentType.CHAIN.value,
         ]:
             self._log_agent_load(name)
         if agent_type == AgentType.BASIC.value:
@@ -343,6 +381,10 @@ class FastAgent(ContextDependent):
                     f"Expected LLMRouter instance for {name}, got {type(instance)}"
                 )
             return RouterProxy(self.app, name, instance)
+        elif agent_type == AgentType.CHAIN.value:
+            # Chain proxy is directly returned from _create_agents_by_type
+            # No need for type checking as it's already a ChainProxy
+            return instance
         else:
             raise ValueError(f"Unknown agent type: {agent_type}")
 
@@ -449,6 +491,15 @@ class FastAgent(ContextDependent):
                         f"Evaluator-Optimizer '{name}' references non-existent components: {', '.join(missing)}"
                     )
 
+            elif agent_type == AgentType.CHAIN.value:
+                # Check that all agents in the sequence exist
+                sequence = agent_data.get("sequence", agent_data.get("agents", []))
+                missing = [a for a in sequence if a not in available_components]
+                if missing:
+                    raise AgentConfigError(
+                        f"Chain '{name}' references non-existent agents: {', '.join(missing)}"
+                    )
+
     def _get_model_factory(
         self,
         model: Optional[str] = None,
@@ -633,6 +684,7 @@ class FastAgent(ContextDependent):
         use_history: bool = False,
         request_params: Optional[Dict] = None,
         human_input: bool = False,
+        plan_type: Literal["full", "iterative"] = "full",
     ) -> Callable:
         """
         Decorator to create and register an orchestrator.
@@ -645,6 +697,7 @@ class FastAgent(ContextDependent):
             use_history: Whether to maintain conversation history (forced false)
             request_params: Additional request parameters for the LLM
             human_input: Whether to enable human input capabilities
+            plan_type: Planning approach - "full" generates entire plan first, "iterative" plans one step at a time
         """
         default_instruction = """
             You are an expert planner. Given an objective task and a list of MCP servers (which are collections of tools)
@@ -666,6 +719,7 @@ class FastAgent(ContextDependent):
             use_history=use_history,
             request_params=request_params,
             human_input=human_input,
+            plan_type=plan_type,
         )
         return decorator
 
@@ -784,6 +838,55 @@ class FastAgent(ContextDependent):
         )
         return decorator
 
+    def chain(
+        self,
+        name: str = "Chain",
+        *,
+        sequence: List[str] = None,
+        agents: List[str] = None,  # Alias for sequence
+        instruction: str = None,
+        model: str | None = None,
+        use_history: bool = True,
+        request_params: Optional[Dict] = None,
+    ) -> Callable:
+        """
+        Decorator to create and register a chain of agents.
+
+        Args:
+            name: Name of the chain
+            sequence: List of agent names in order of execution (preferred name)
+            agents: Alias for sequence (backwards compatibility)
+            instruction: Optional custom instruction for the chain (if none provided, will autogenerate based on sequence)
+            model: Model specification string (not used directly in chain)
+            use_history: Whether to maintain conversation history
+            request_params: Additional request parameters
+        """
+        # Support both parameter names
+        agent_sequence = sequence or agents
+        if agent_sequence is None:
+            raise ValueError("Either 'sequence' or 'agents' parameter must be provided")
+
+        # Auto-generate instruction if not provided
+        if instruction is None:
+            # We'll generate it later when we have access to the agent configs and can see servers
+            instruction = f"Chain of agents: {', '.join(agent_sequence)}"
+
+        decorator = self._create_decorator(
+            AgentType.CHAIN,
+            default_name="Chain",
+            default_instruction=instruction,
+            default_use_history=True,
+            wrapper_needed=True,
+        )(
+            name=name,
+            sequence=agent_sequence,
+            instruction=instruction,
+            model=model,
+            use_history=use_history,
+            request_params=request_params,
+        )
+        return decorator
+
     async def _create_agents_by_type(
         self,
         agent_app: MCPApp,
@@ -864,7 +967,7 @@ class FastAgent(ContextDependent):
                         which can be performed by LLMs with access to the servers or agents.
                         """,
                         servers=[],  # Planner doesn't need server access
-                        model=config.model,  # Use same model as orchestrator
+                        model=config.model,
                         default_request_params=base_params,
                     )
                     planner_agent = Agent(
@@ -885,8 +988,10 @@ class FastAgent(ContextDependent):
                         available_agents=child_agents,
                         context=agent_app.context,
                         request_params=planner.default_request_params,  # Base params already include model settings
-                        plan_type="full",  # TODO -- support iterative plan type properly
-                        verb=ProgressAction.PLANNING,  # Using PLANNING instead of ORCHESTRATING
+                        plan_type=agent_data.get(
+                            "plan_type", "full"
+                        ),  # Get plan_type from agent_data
+                        verb=ProgressAction.PLANNING,
                     )
 
                 elif agent_type == AgentType.EVALUATOR_OPTIMIZER:
@@ -941,6 +1046,43 @@ class FastAgent(ContextDependent):
                         verb=ProgressAction.ROUTING,  # Set verb for progress display
                     )
 
+                elif agent_type == AgentType.CHAIN:
+                    # Get the sequence from either parameter
+                    sequence = agent_data.get("sequence", agent_data.get("agents", []))
+                    
+                    # Auto-generate instruction if not provided or if it's just the default
+                    default_instruction = f"Chain of agents: {', '.join(sequence)}"
+                    
+                    # If user provided a custom instruction, use that
+                    # Otherwise, generate a description based on the sequence and their servers
+                    if config.instruction == default_instruction:
+                        # Get all agent names in the sequence
+                        agent_names = []
+                        all_servers = set()
+                        
+                        # Collect information about the agents and their servers
+                        for agent_name in sequence:
+                            if agent_name in active_agents:
+                                agent_proxy = active_agents[agent_name]
+                                if hasattr(agent_proxy, "_agent"):
+                                    # For LLMAgentProxy
+                                    agent_instance = agent_proxy._agent
+                                    agent_names.append(agent_name)
+                                    if hasattr(agent_instance, "server_names"):
+                                        all_servers.update(agent_instance.server_names)
+                                elif hasattr(agent_proxy, "_workflow"):
+                                    # For WorkflowProxy
+                                    agent_names.append(agent_name)
+                        
+                        # Generate a better description
+                        if agent_names:
+                            server_part = f" with access to servers: {', '.join(sorted(all_servers))}" if all_servers else ""
+                            config.instruction = f"Sequence of agents: {', '.join(agent_names)}{server_part}."
+                    
+                    # Create a ChainProxy without needing a new instance
+                    # Just pass the agent proxies and sequence
+                    instance = ChainProxy(self.app, name, sequence, active_agents)
+
                 elif agent_type == AgentType.PARALLEL:
                     # Get fan-out agents (could be basic agents or other parallels)
                     fan_out_agents = self._get_agent_instances(
@@ -1020,16 +1162,18 @@ class FastAgent(ContextDependent):
             agent_app, AgentType.EVALUATOR_OPTIMIZER, active_agents
         )
 
-    def _get_parallel_dependencies(
-        self, name: str, visited: set, path: set
+    def _get_dependencies(
+        self, name: str, visited: set, path: set, agent_type: AgentType = None
     ) -> List[str]:
         """
-        Get dependencies for a parallel agent in topological order.
+        Get dependencies for an agent in topological order.
+        Works for both Parallel and Chain workflows.
 
         Args:
-            name: Name of the parallel agent
+            name: Name of the agent
             visited: Set of already visited agents
             path: Current path for cycle detection
+            agent_type: Optional type filter (e.g., only check Parallel or Chain)
 
         Returns:
             List of agent names in dependency order
@@ -1039,7 +1183,7 @@ class FastAgent(ContextDependent):
         """
         if name in path:
             path_str = " -> ".join(path)
-            raise ValueError(f"Circular dependency detected: {path_str} -> {name}")
+            raise CircularDependencyError(f"Path: {path_str} -> {name}")
 
         if name in visited:
             return []
@@ -1048,15 +1192,26 @@ class FastAgent(ContextDependent):
             return []
 
         config = self.agents[name]
-        if config["type"] != AgentType.PARALLEL.value:
+
+        # Skip if not the requested type (when filtering)
+        if agent_type and config["type"] != agent_type.value:
             return []
 
         path.add(name)
         deps = []
 
-        # Get dependencies from fan-out agents
-        for fan_out in config["fan_out"]:
-            deps.extend(self._get_parallel_dependencies(fan_out, visited, path))
+        # Handle dependencies based on agent type
+        if config["type"] == AgentType.PARALLEL.value:
+            # Get dependencies from fan-out agents
+            for fan_out in config["fan_out"]:
+                deps.extend(self._get_dependencies(fan_out, visited, path, agent_type))
+        elif config["type"] == AgentType.CHAIN.value:
+            # Get dependencies from sequence agents
+            sequence = config.get("sequence", config.get("agents", []))
+            for agent_name in sequence:
+                deps.extend(
+                    self._get_dependencies(agent_name, visited, path, agent_type)
+                )
 
         # Add this agent after its dependencies
         deps.append(name)
@@ -1065,54 +1220,95 @@ class FastAgent(ContextDependent):
 
         return deps
 
-    async def _create_parallel_agents(
-        self, agent_app: MCPApp, active_agents: ProxyDict
+    def _get_parallel_dependencies(
+        self, name: str, visited: set, path: set
+    ) -> List[str]:
+        """
+        Get dependencies for a parallel agent in topological order.
+        Legacy function that calls the more general _get_dependencies.
+
+        Args:
+            name: Name of the parallel agent
+            visited: Set of already visited agents
+            path: Current path for cycle detection
+
+        Returns:
+            List of agent names in dependency order
+
+        Raises:
+            ValueError: If circular dependency detected
+        """
+        return self._get_dependencies(name, visited, path, AgentType.PARALLEL)
+
+    async def _create_agents_in_dependency_order(
+        self, agent_app: MCPApp, active_agents: ProxyDict, agent_type: AgentType
     ) -> ProxyDict:
         """
-        Create parallel execution agents in dependency order.
+        Create agents in dependency order to avoid circular references.
+        Works for both Parallel and Chain workflows.
 
         Args:
             agent_app: The main application instance
             active_agents: Dictionary of already created agents/proxies
+            agent_type: Type of agents to create (AgentType.PARALLEL or AgentType.CHAIN)
 
         Returns:
-            Dictionary of initialized parallel agents
+            Dictionary of initialized agents
         """
-        parallel_agents = {}
+        result_agents = {}
         visited = set()
 
-        # Get all parallel agents
-        parallel_names = [
+        # Get all agents of the specified type
+        agent_names = [
             name
             for name, agent_data in self.agents.items()
-            if agent_data["type"] == AgentType.PARALLEL.value
+            if agent_data["type"] == agent_type.value
         ]
 
         # Create agents in dependency order
-        for name in parallel_names:
+        for name in agent_names:
             # Get ordered dependencies if not already processed
             if name not in visited:
                 try:
-                    ordered_agents = self._get_parallel_dependencies(
-                        name, visited, set()
+                    ordered_agents = self._get_dependencies(
+                        name, visited, set(), agent_type
                     )
                 except ValueError as e:
-                    raise ValueError(f"Error creating parallel agent {name}: {str(e)}")
+                    raise ValueError(
+                        f"Error creating {agent_type.name.lower()} agent {name}: {str(e)}"
+                    )
 
                 # Create each agent in order
                 for agent_name in ordered_agents:
-                    if agent_name not in parallel_agents:
-                        # Create one parallel agent at a time using the generic method
+                    if agent_name not in result_agents:
+                        # Create one agent at a time using the generic method
                         agent_result = await self._create_agents_by_type(
                             agent_app,
-                            AgentType.PARALLEL,
+                            agent_type,
                             active_agents,
                             agent_name=agent_name,
                         )
                         if agent_name in agent_result:
-                            parallel_agents[agent_name] = agent_result[agent_name]
+                            result_agents[agent_name] = agent_result[agent_name]
+
+        return result_agents
+
+    async def _create_parallel_agents(
+        self, agent_app: MCPApp, active_agents: ProxyDict
+    ) -> ProxyDict:
+        """
+        Create parallel execution agents in dependency order.
+
+        Args:
+            agent_app: The main application instance
+            active_agents: Dictionary of already created agents/proxies
 
-        return parallel_agents
+        Returns:
+            Dictionary of initialized parallel agents
+        """
+        return await self._create_agents_in_dependency_order(
+            agent_app, active_agents, AgentType.PARALLEL
+        )
 
     async def _create_routers(
         self, agent_app: MCPApp, active_agents: ProxyDict
@@ -1186,12 +1382,16 @@ class FastAgent(ContextDependent):
                     agent_app, active_agents
                 )
                 routers = await self._create_routers(agent_app, active_agents)
+                chains = await self._create_agents_in_dependency_order(
+                    agent_app, active_agents, AgentType.CHAIN
+                )
 
                 # Merge all agents into active_agents
                 active_agents.update(orchestrators)
                 active_agents.update(parallel_agents)
                 active_agents.update(evaluator_optimizers)
                 active_agents.update(routers)
+                active_agents.update(chains)
 
                 # Create wrapper with all agents
                 wrapper = AgentApp(agent_app, active_agents)
@@ -1228,10 +1428,37 @@ class FastAgent(ContextDependent):
             had_error = True
             self._handle_error(
                 e,
-                "Server Startup Error",
+                "MCP Server Startup Error",
                 "There was an error starting up the MCP Server.",
             )
             raise SystemExit(1)
+
+        except ModelConfigError as e:
+            had_error = True
+            self._handle_error(
+                e,
+                "Model Configuration Error",
+                "Common models: gpt-4o, o3-mini, sonnet, haiku. for o3, set reasoning effort with o3-mini.high",
+            )
+            raise SystemExit(1)
+
+        except CircularDependencyError as e:
+            had_error = True
+            self._handle_error(
+                e,
+                "Circular Dependency Detected",
+                "Check your agent configuration for circular dependencies.",
+            )
+            raise SystemExit(1)
+
+        except PromptExitError as e:
+            had_error = True
+            self._handle_error(
+                e,
+                "User requested exit",
+            )
+            raise SystemExit(1)
+
         finally:
             # Clean up any active agents without re-raising errors
             if active_agents and not had_error:
@@ -1239,7 +1466,8 @@ class FastAgent(ContextDependent):
                     if isinstance(proxy, LLMAgentProxy):
                         try:
                             await proxy._agent.__aexit__(None, None, None)
-                        except Exception:
+                        except Exception as e:
+                            print(f"DEBUG {e.message}")
                             pass  # Ignore cleanup errors
 
     def _handle_error(

mcp_agent/human_input/handler.py

@@ -1,6 +1,5 @@
 import asyncio
 from rich.panel import Panel
-from rich.prompt import Prompt
 
 from mcp_agent.console import console
 from mcp_agent.human_input.types import (
@@ -8,10 +7,11 @@ from mcp_agent.human_input.types import (
     HumanInputResponse,
 )
 from mcp_agent.progress_display import progress_display
+from mcp_agent.core.enhanced_prompt import get_enhanced_input, handle_special_commands
 
 
 async def console_input_callback(request: HumanInputRequest) -> HumanInputResponse:
-    """Request input from a human user via console using rich panel and prompt."""
+    """Request input from a human user via console using prompt_toolkit."""
 
     # Prepare the prompt text
     prompt_text = request.prompt
@@ -28,26 +28,51 @@ async def console_input_callback(request: HumanInputRequest) -> HumanInputRespon
         padding=(1, 2),
     )
 
+    # Extract agent name from metadata dictionary
+    agent_name = (
+        request.metadata.get("agent_name", "Unknown Agent")
+        if request.metadata
+        else "Unknown Agent"
+    )
+
     # Use the context manager to pause the progress display while getting input
     with progress_display.paused():
         console.print(panel)
 
-        if request.timeout_seconds:
-            try:
-                loop = asyncio.get_event_loop()
-                response = await asyncio.wait_for(
-                    loop.run_in_executor(
-                        None, lambda: Prompt.ask("Provide your response ")
-                    ),
-                    request.timeout_seconds,
+        try:
+            if request.timeout_seconds:
+                try:
+                    # Use get_enhanced_input with empty agent list to disable agent switching
+                    response = await asyncio.wait_for(
+                        get_enhanced_input(
+                            agent_name=agent_name,
+                            available_agent_names=[],  # No agents for selection
+                            show_stop_hint=False,
+                            is_human_input=True,
+                            toolbar_color="ansimagenta",
+                        ),
+                        request.timeout_seconds,
+                    )
+                except asyncio.TimeoutError:
+                    console.print("\n[red]Timeout waiting for input[/red]")
+                    raise TimeoutError("No response received within timeout period")
+            else:
+                response = await get_enhanced_input(
+                    agent_name=agent_name,
+                    available_agent_names=[],  # No agents for selection
+                    show_stop_hint=False,
+                    is_human_input=True,
+                    toolbar_color="ansimagenta",
                 )
-            except asyncio.TimeoutError:
-                console.print("\n[red]Timeout waiting for input[/red]")
-                raise TimeoutError("No response received within timeout period")
-        else:
-            loop = asyncio.get_event_loop()
-            response = await loop.run_in_executor(
-                None, lambda: Prompt.ask("Provide your response ")
-            )
+
+            #            if response and (response.startswith("/") or response.startswith("@")):
+            await handle_special_commands(response)
+
+        except KeyboardInterrupt:
+            console.print("\n[yellow]Input interrupted[/yellow]")
+            response = ""
+        except EOFError:
+            console.print("\n[yellow]Input terminated[/yellow]")
+            response = ""
 
     return HumanInputResponse(request_id=request.request_id, response=response.strip())

mcp_agent/mcp/mcp_connection_manager.py

@@ -75,15 +75,15 @@ class ServerConnection:
 
         # Signal we want to shut down
         self._shutdown_event = Event()
-        
+
         # Track error state
         self._error_occurred = False
         self._error_message = None
-        
+
     def is_healthy(self) -> bool:
         """Check if the server connection is healthy and ready to use."""
         return self.session is not None and not self._error_occurred
-        
+
     def reset_error_state(self) -> None:
         """Reset the error state, allowing reconnection attempts."""
         self._error_occurred = False
@@ -216,10 +216,10 @@ class MCPConnectionManager(ContextDependent):
         try:
             # First request all servers to shutdown
             await self.disconnect_all()
-            
+
             # Add a small delay to allow for clean shutdown
             await asyncio.sleep(0.5)
-            
+
             # Then close the task group if it's active
             if self._task_group_active:
                 await self._task_group.__aexit__(exc_type, exc_val, exc_tb)
@@ -305,10 +305,12 @@ class MCPConnectionManager(ContextDependent):
             server_conn = self.running_servers.get(server_name)
             if server_conn and server_conn.is_healthy():
                 return server_conn
-                
+
             # If server exists but isn't healthy, remove it so we can create a new one
             if server_conn:
-                logger.info(f"{server_name}: Server exists but is unhealthy, recreating...")
+                logger.info(
+                    f"{server_name}: Server exists but is unhealthy, recreating..."
+                )
                 self.running_servers.pop(server_name)
                 server_conn.request_shutdown()
 
@@ -326,9 +328,9 @@ class MCPConnectionManager(ContextDependent):
         if not server_conn.is_healthy():
             error_msg = server_conn._error_message or "Unknown error"
             raise ServerInitializationError(
-                f"{server_name}: Failed to initialize server: {error_msg}"
+                f"MCP Server: '{server_name}': Failed to initialize with error: '{error_msg}'. Check fastagent.config.yaml"
             )
-        
+
         return server_conn
 
     async def disconnect_server(self, server_name: str) -> None:
@@ -353,16 +355,16 @@ class MCPConnectionManager(ContextDependent):
         """Disconnect all servers that are running under this connection manager."""
         # Get a copy of servers to shutdown
         servers_to_shutdown = []
-        
+
         async with self._lock:
             if not self.running_servers:
                 return
-                
+
             # Make a copy of the servers to shut down
             servers_to_shutdown = list(self.running_servers.items())
             # Clear the dict immediately to prevent any new access
             self.running_servers.clear()
-            
+
         # Release the lock before waiting for servers to shut down
         for name, conn in servers_to_shutdown:
             logger.info(f"{name}: Requesting shutdown...")