fast-agent-mcp 0.0.7__py3-none-any.whl → 0.0.9__py3-none-any.whl

mcp_agent/core/fastagent.py

@@ -9,6 +9,13 @@ import yaml
 import argparse
 from contextlib import asynccontextmanager
 
+from mcp_agent.core.exceptions import (
+    AgentConfigError,
+    ServerConfigError,
+    ProviderKeyError,
+    ServerInitializationError,
+)
+
 from mcp_agent.app import MCPApp
 from mcp_agent.agents.agent import Agent, AgentConfig
 from mcp_agent.context_dependent import ContextDependent
@@ -24,10 +31,10 @@ from rich.prompt import Prompt
 from rich import print
 from mcp_agent.progress_display import progress_display
 from mcp_agent.workflows.llm.model_factory import ModelFactory
-from mcp_agent.workflows.llm.augmented_llm import RequestParams
-
-import readline  # noqa: F401
+from mcp_agent.workflows.llm.augmented_llm import AugmentedLLM, RequestParams
 
+# TODO -- resintate once Windows&Python 3.13 platform issues are fixed
+# import readline  # noqa: F401
 
 # Type aliases for better readability
 WorkflowType: TypeAlias = Union[
@@ -304,6 +311,98 @@ class FastAgent(ContextDependent):
             with open(self.config_path) as f:
                 self.config = yaml.safe_load(f)
 
+    def _validate_server_references(self) -> None:
+        """
+        Validate that all server references in agent configurations exist in config.
+        Raises ServerConfigError if any referenced servers are not defined.
+        """
+        if not self.context.config.mcp or not self.context.config.mcp.servers:
+            available_servers = set()
+        else:
+            available_servers = set(self.context.config.mcp.servers.keys())
+
+        # Check each agent's server references
+        for name, agent_data in self.agents.items():
+            config = agent_data["config"]
+            if config.servers:
+                missing = [s for s in config.servers if s not in available_servers]
+                if missing:
+                    raise ServerConfigError(
+                        f"Missing server configuration for agent '{name}'",
+                        f"The following servers are referenced but not defined in config: {', '.join(missing)}",
+                    )
+
+    def _validate_workflow_references(self) -> None:
+        """
+        Validate that all workflow references point to valid agents/workflows.
+        Also validates that referenced agents have required configuration.
+        Raises AgentConfigError if any validation fails.
+        """
+        available_components = set(self.agents.keys())
+
+        for name, agent_data in self.agents.items():
+            agent_type = agent_data["type"]
+
+            if agent_type == AgentType.PARALLEL.value:
+                # Check fan_in exists
+                fan_in = agent_data["fan_in"]
+                if fan_in not in available_components:
+                    raise AgentConfigError(
+                        f"Parallel workflow '{name}' references non-existent fan_in component: {fan_in}"
+                    )
+
+                # Check fan_out agents exist
+                fan_out = agent_data["fan_out"]
+                missing = [a for a in fan_out if a not in available_components]
+                if missing:
+                    raise AgentConfigError(
+                        f"Parallel workflow '{name}' references non-existent fan_out components: {', '.join(missing)}"
+                    )
+
+            elif agent_type == AgentType.ORCHESTRATOR.value:
+                # Check all child agents exist and are properly configured
+                child_agents = agent_data["child_agents"]
+                missing = [a for a in child_agents if a not in available_components]
+                if missing:
+                    raise AgentConfigError(
+                        f"Orchestrator '{name}' references non-existent agents: {', '.join(missing)}"
+                    )
+
+                # Validate child agents have required LLM configuration
+                for agent_name in child_agents:
+                    child_data = self.agents[agent_name]
+                    if child_data["type"] == AgentType.BASIC.value:
+                        # For basic agents, we'll validate LLM config during creation
+                        continue
+                    elif not isinstance(child_data["func"], AugmentedLLM):
+                        raise AgentConfigError(
+                            f"Agent '{agent_name}' used by orchestrator '{name}' lacks LLM capability",
+                            "All agents used by orchestrators must be LLM-capable",
+                        )
+
+            elif agent_type == AgentType.ROUTER.value:
+                # Check all referenced agents exist
+                router_agents = agent_data["agents"]
+                missing = [a for a in router_agents if a not in available_components]
+                if missing:
+                    raise AgentConfigError(
+                        f"Router '{name}' references non-existent agents: {', '.join(missing)}"
+                    )
+
+            elif agent_type == AgentType.EVALUATOR_OPTIMIZER.value:
+                # Check both evaluator and optimizer exist
+                evaluator = agent_data["evaluator"]
+                optimizer = agent_data["optimizer"]
+                missing = []
+                if evaluator not in available_components:
+                    missing.append(f"evaluator: {evaluator}")
+                if optimizer not in available_components:
+                    missing.append(f"optimizer: {optimizer}")
+                if missing:
+                    raise AgentConfigError(
+                        f"Evaluator-Optimizer '{name}' references non-existent components: {', '.join(missing)}"
+                    )
+
     def _get_model_factory(
         self,
         model: Optional[str] = None,
@@ -347,9 +446,10 @@ class FastAgent(ContextDependent):
         *,
         instruction: str = "You are a helpful agent.",
         servers: List[str] = [],
-        model: Optional[str] = None,
+        model: str | None = None,
         use_history: bool = True,
         request_params: Optional[Dict] = None,
+        human_input: bool = False,
     ) -> Callable:
         """
         Decorator to create and register an agent with configuration.
@@ -362,9 +462,9 @@ class FastAgent(ContextDependent):
             use_history: Whether to maintain conversation history
             request_params: Additional request parameters for the LLM
         """
-        #        print(f"\nDecorating agent {name} with model={model}")
 
         def decorator(func: Callable) -> Callable:
+            # Create base request params
             base_params = RequestParams(
                 use_history=use_history,
                 model=model,  # Include model in initial params
@@ -380,6 +480,7 @@ class FastAgent(ContextDependent):
                 model=model,  # Highest precedence
                 use_history=use_history,
                 default_request_params=base_params,
+                human_input=human_input,
             )
 
             # Store the agent configuration
@@ -389,21 +490,20 @@ class FastAgent(ContextDependent):
                 "func": func,
             }
 
-            async def wrapper(*args, **kwargs):
-                return await func(*args, **kwargs)
-
-            return wrapper
+            return func  # Don't wrap the function, just return it
 
         return decorator
 
     def orchestrator(
         self,
-        name: str,
-        instruction: str,
+        name: str = "Orchestrator",
+        *,
+        instruction: str | None = None,
         agents: List[str],
         model: str | None = None,
-        use_history: bool = True,
+        use_history: bool = False,
         request_params: Optional[Dict] = None,
+        human_input: bool = False,
     ) -> Callable:
         """
         Decorator to create and register an orchestrator.
@@ -413,14 +513,14 @@ class FastAgent(ContextDependent):
             instruction: Base instruction for the orchestrator
             agents: List of agent names this orchestrator can use
             model: Model specification string (highest precedence)
-            use_history: Whether to maintain conversation history
+            use_history: Whether to maintain conversation history (forced false)
             request_params: Additional request parameters for the LLM
         """
 
         def decorator(func: Callable) -> Callable:
             # Create base request params
             base_params = RequestParams(
-                use_history=use_history, **(request_params or {})
+                use_history=use_history, model=model, **(request_params or {})
             )
 
             # Create agent configuration
@@ -431,6 +531,7 @@ class FastAgent(ContextDependent):
                 model=model,  # Highest precedence
                 use_history=use_history,
                 default_request_params=base_params,
+                human_input=human_input,
             )
 
             # Store the orchestrator configuration
@@ -441,10 +542,7 @@ class FastAgent(ContextDependent):
                 "func": func,
             }
 
-            async def wrapper(*args, **kwargs):
-                return await func(*args, **kwargs)
-
-            return wrapper
+            return func
 
         return decorator
 
@@ -495,10 +593,7 @@ class FastAgent(ContextDependent):
                 "func": func,
             }
 
-            async def wrapper(*args, **kwargs):
-                return await func(*args, **kwargs)
-
-            return wrapper
+            return func
 
         return decorator
 
@@ -557,10 +652,11 @@ class FastAgent(ContextDependent):
         self,
         name: str,
         agents: List[str],
-        servers: List[str] = [],
+        #        servers: List[str] = [],
         model: Optional[str] = None,
         use_history: bool = True,
         request_params: Optional[Dict] = None,
+        human_input: bool = False,
     ) -> Callable:
         """
         Decorator to create and register a router.
@@ -584,10 +680,11 @@ class FastAgent(ContextDependent):
             config = AgentConfig(
                 name=name,
                 instruction="",  # Router uses its own routing instruction
-                servers=servers,
+                servers=[],  # , servers are not supported now
                 model=model,
                 use_history=use_history,
                 default_request_params=base_params,
+                human_input=human_input,
             )
 
             # Store the router configuration
@@ -639,7 +736,7 @@ class FastAgent(ContextDependent):
 
         return active_agents
 
-    def _create_orchestrators(
+    async def _create_orchestrators(
         self, agent_app: MCPApp, active_agents: ProxyDict
     ) -> ProxyDict:
         """
@@ -657,44 +754,57 @@ class FastAgent(ContextDependent):
             if agent_data["type"] == AgentType.ORCHESTRATOR.value:
                 config = agent_data["config"]
 
-                # TODO: Remove legacy - This model/params setup should be in Agent class
-                # Resolve model alias if present
-                model_config = ModelFactory.parse_model_string(config.model)
-                resolved_model = model_config.model_name
-
-                # Start with existing params if available
-                if config.default_request_params:
-                    base_params = config.default_request_params.model_copy()
-                    # Update with orchestrator-specific settings
-                    base_params.use_history = config.use_history
-                    base_params.model = resolved_model
-                else:
-                    base_params = RequestParams(
-                        use_history=config.use_history, model=resolved_model
-                    )
-
-                llm_factory = self._get_model_factory(
-                    model=config.model,  # Use original model string for factory creation
-                    request_params=base_params,
+                # Get base params configured with model settings
+                base_params = (
+                    config.default_request_params.model_copy()
+                    if config.default_request_params
+                    else RequestParams()
                 )
+                base_params.use_history = False  # Force no history for orchestrator
 
-                # Get the child agents - need to unwrap proxies
+                # Get the child agents - need to unwrap proxies and validate LLM config
                 child_agents = []
                 for agent_name in agent_data["child_agents"]:
                     proxy = active_agents[agent_name]
-                    if isinstance(proxy, LLMAgentProxy):
-                        child_agents.append(proxy._agent)  # Get the actual Agent
-                    else:
-                        # Handle case where it might be another workflow
-                        child_agents.append(proxy._workflow)
+                    instance = self._unwrap_proxy(proxy)
+                    # Validate basic agents have LLM
+                    if isinstance(instance, Agent):
+                        if not hasattr(instance, "_llm") or not instance._llm:
+                            raise AgentConfigError(
+                                f"Agent '{agent_name}' used by orchestrator '{name}' missing LLM configuration",
+                                "All agents must be fully configured with LLMs before being used in an orchestrator",
+                            )
+                    child_agents.append(instance)
+
+                # Create a properly configured planner agent
+                planner_config = AgentConfig(
+                    name=f"{name}",  # Use orchestrator name as prefix
+                    instruction=config.instruction
+                    or """
+                    You are an expert planner. Given an objective task and a list of MCP servers (which are collections of tools)
+                    or Agents (which are collections of servers), your job is to break down the objective into a series of steps,
+                    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
+                    default_request_params=base_params,
+                )
+                planner_agent = Agent(config=planner_config, context=agent_app.context)
+                planner_factory = self._get_model_factory(
+                    model=config.model,
+                    request_params=config.default_request_params,
+                )
 
+                async with planner_agent:
+                    planner = await planner_agent.attach_llm(planner_factory)
+
+                # Create the orchestrator with pre-configured planner
                 orchestrator = Orchestrator(
                     name=config.name,
-                    instruction=config.instruction,
+                    planner=planner,  # Pass pre-configured planner
                     available_agents=child_agents,
                     context=agent_app.context,
-                    llm_factory=llm_factory,
-                    request_params=base_params,  # Use our base params that include model
+                    request_params=planner.default_request_params,  # Base params already include model settings
                     plan_type="full",
                 )
 
@@ -702,6 +812,7 @@ class FastAgent(ContextDependent):
                 orchestrators[name] = self._create_proxy(
                     name, orchestrator, AgentType.ORCHESTRATOR.value
                 )
+
         return orchestrators
 
     async def _create_evaluator_optimizers(
@@ -796,7 +907,7 @@ class FastAgent(ContextDependent):
 
         return deps
 
-    def _create_parallel_agents(
+    async def _create_parallel_agents(
         self, agent_app: MCPApp, active_agents: ProxyDict
     ) -> ProxyDict:
         """
@@ -864,7 +975,9 @@ class FastAgent(ContextDependent):
 
         return parallel_agents
 
-    def _create_routers(self, agent_app: MCPApp, active_agents: ProxyDict) -> ProxyDict:
+    async def _create_routers(
+        self, agent_app: MCPApp, active_agents: ProxyDict
+    ) -> ProxyDict:
         """
         Create router agents.
 
@@ -937,77 +1050,90 @@ class FastAgent(ContextDependent):
     async def run(self):
         """
         Context manager for running the application.
-        Handles setup and teardown of the app and agents.
-
-        Yields:
-            AgentAppWrapper instance with all initialized agents
-        """
-        async with self.app.run() as agent_app:
-            # Create all types of agents
-            active_agents = await self._create_basic_agents(agent_app)
-            orchestrators = self._create_orchestrators(agent_app, active_agents)
-            parallel_agents = self._create_parallel_agents(agent_app, active_agents)
-            evaluator_optimizers = await self._create_evaluator_optimizers(
-                agent_app, active_agents
-            )
-            routers = self._create_routers(agent_app, active_agents)
+        Performs validation and provides user-friendly error messages.
+        """
+        active_agents = {}
+        had_error = False
+        try:
+            async with self.app.run() as agent_app:
+                # Pre-flight validation
+                self._validate_server_references()
+                self._validate_workflow_references()
+
+                # Create all types of agents in dependency order
+                active_agents = await self._create_basic_agents(agent_app)
+                orchestrators = await self._create_orchestrators(
+                    agent_app, active_agents
+                )
+                parallel_agents = await self._create_parallel_agents(
+                    agent_app, active_agents
+                )
+                evaluator_optimizers = await self._create_evaluator_optimizers(
+                    agent_app, active_agents
+                )
+                routers = await self._create_routers(agent_app, active_agents)
 
-            # Merge all agents into active_agents
-            active_agents.update(orchestrators)
-            active_agents.update(parallel_agents)
-            active_agents.update(evaluator_optimizers)
-            active_agents.update(routers)
+                # Merge all agents into active_agents
+                active_agents.update(orchestrators)
+                active_agents.update(parallel_agents)
+                active_agents.update(evaluator_optimizers)
+                active_agents.update(routers)
 
-            # Create wrapper with all agents
-            wrapper = AgentApp(agent_app, active_agents)
-            try:
+                # Create wrapper with all agents
+                wrapper = AgentApp(agent_app, active_agents)
                 yield wrapper
-            finally:
-                # Clean up basic agents - need to get the actual agent from the proxy
+
+        except ServerConfigError as e:
+            had_error = True
+            print("\n[bold red]Server Configuration Error:")
+            print(e.message)
+            if e.details:
+                print("\nDetails:")
+                print(e.details)
+            print(
+                "\nPlease check your 'fastagent.config.yaml' configuration file and add the missing server definitions."
+            )
+            raise SystemExit(1)
+
+        except ProviderKeyError as e:
+            had_error = True
+            print("\n[bold red]Provider Configuration Error:")
+            print(e.message)
+            if e.details:
+                print("\nDetails:")
+                print(e.details)
+            print(
+                "\nPlease check your 'fastagent.secrets.yaml' configuration file and ensure all required API keys are set."
+            )
+            raise SystemExit(1)
+
+        except AgentConfigError as e:
+            had_error = True
+            print("\n[bold red]Workflow or Agent Configuration Error:")
+            print(e.message)
+            if e.details:
+                print("\nDetails:")
+                print(e.details)
+            print(
+                "\nPlease check your agent definition and ensure names and references are correct."
+            )
+            raise SystemExit(1)
+
+        except ServerInitializationError as e:
+            had_error = True
+            print("\n[bold red]Server Startup Error:")
+            print(e.message)
+            if e.details:
+                print("\nDetails:")
+                print(e.details)
+            print("\nThere was an error starting up the MCP Server.")
+            raise SystemExit(1)
+        finally:
+            # Clean up any active agents without re-raising errors
+            if active_agents and not had_error:
                 for name, proxy in active_agents.items():
                     if isinstance(proxy, LLMAgentProxy):
-                        await proxy._agent.__aexit__(None, None, None)
-
-        # async def send(self, agent_name: str, message: str) -> Any:
-        # """
-        # Send a message to a specific agent and get the response.
-
-        # Args:
-        #     agent_name: Name of the target agent
-        #     message: Message to send
-
-        # Returns:
-        #     Agent's response
-
-        # Raises:
-        #     ValueError: If agent not found
-        #     RuntimeError: If agent has no LLM attached
-        # """
-        # if agent_name not in self.agents:
-        #     raise ValueError(f"Agent {agent_name} not found")
-
-        # agent = self.agents[agent_name]
-
-        # # Special handling for routers
-        # if isinstance(agent._llm, LLMRouter):
-        #     # Route the message and get results
-        #     results = await agent._llm.route(message)
-        #     if not results:
-        #         return "No appropriate route found for the request."
-
-        #     # Get the top result
-        #     top_result = results[0]
-        #     if isinstance(top_result.result, Agent):
-        #         # Agent route - delegate to the agent
-        #         return await top_result.result._llm.generate_str(message)
-        #     elif isinstance(top_result.result, str):
-        #         # Server route - use the router directly
-        #         return "Tool call requested by router - not yet supported"
-        #     else:
-        #         return f"Routed to: {top_result.result} ({top_result.confidence}): {top_result.reasoning}"
-
-        # # Normal agent handling
-        # if not hasattr(agent, "_llm") or agent._llm is None:
-        #     raise RuntimeError(f"Agent {agent_name} has no LLM attached")
-
-        # return await agent._llm.generate_str(message)
+                        try:
+                            await proxy._agent.__aexit__(None, None, None)
+                        except Exception:
+                            pass  # Ignore cleanup errors

mcp_agent/core/server_validation.py

@@ -0,0 +1,44 @@
+"""FastAgent validation methods."""
+
+from mcp_agent.core.exceptions import ServerConfigError
+
+
+def _validate_server_references(self) -> None:
+    """
+    Validate that all server references in agent configurations exist in config.
+    Raises ServerConfigError if any referenced servers are not defined.
+    """
+    # First check if any agents need servers
+    agents_needing_servers = {
+        name: agent_data["config"].servers
+        for name, agent_data in self.agents.items()
+        if agent_data["config"].servers
+    }
+
+    if not agents_needing_servers:
+        return  # No validation needed
+
+    # If we need servers, verify MCP config exists
+    if not hasattr(self.context.config, "mcp"):
+        raise ServerConfigError(
+            "MCP configuration missing",
+            "Agents require server access but no MCP configuration found.\n"
+            "Add an 'mcp' section to your configuration file.",
+        )
+
+    if not self.context.config.mcp.servers:
+        raise ServerConfigError(
+            "No MCP servers configured",
+            "Agents require server access but no servers are defined.\n"
+            "Add server definitions under mcp.servers in your configuration file.",
+        )
+
+    # Now check each agent's servers exist
+    available_servers = set(self.context.config.mcp.servers.keys())
+    for name, servers in agents_needing_servers.items():
+        missing = [s for s in servers if s not in available_servers]
+        if missing:
+            raise ServerConfigError(
+                f"Missing server configuration for agent '{name}'",
+                f"The following servers are referenced but not defined in config: {', '.join(missing)}",
+            )

mcp_agent/event_progress.py

@@ -19,6 +19,7 @@ class ProgressAction(str, Enum):
     SHUTDOWN = "Shutdown"
     AGGREGATOR_INITIALIZED = "Running"
     ROUTING = "Routing"
+    FATAL_ERROR = "Error"
 
 
 @dataclass
@@ -61,7 +62,9 @@ def convert_log_event(event: Event) -> Optional[ProgressEvent]:
     agent_name = event_data.get("agent_name")
     target = agent_name
     details = ""
-    if "mcp_aggregator" in namespace:
+    if progress_action == ProgressAction.FATAL_ERROR:
+        details = event_data.get("error_message", "An error occurred")
+    elif "mcp_aggregator" in namespace:
         server_name = event_data.get("server_name", "")
         tool_name = event_data.get("tool_name")
         if tool_name:

mcp_agent/logging/rich_progress.py

@@ -76,6 +76,7 @@ class RichProgressDisplay:
             ProgressAction.FINISHED: "black on green",
             ProgressAction.SHUTDOWN: "black on red",
             ProgressAction.AGGREGATOR_INITIALIZED: "bold green",
+            ProgressAction.FATAL_ERROR: "black on red",
         }.get(action, "white")
 
     def update(self, event: ProgressEvent) -> None:
@@ -116,5 +117,15 @@ class RichProgressDisplay:
             for task in self._progress.tasks:
                 if task.id != task_id:
                     task.visible = False
+        elif event.action == ProgressAction.FATAL_ERROR:
+            self._progress.update(
+                task_id,
+                completed=100,
+                total=100,
+                details=f" / {event.details}",
+            )
+            for task in self._progress.tasks:
+                if task.id != task_id:
+                    task.visible = False
         else:
             self._progress.reset(task_id)

mcp_agent/mcp/mcp_connection_manager.py

@@ -24,6 +24,8 @@ from mcp.client.sse import sse_client
 from mcp.types import JSONRPCMessage
 
 from mcp_agent.config import MCPServerSettings
+from mcp_agent.core.exceptions import ServerInitializationError
+from mcp_agent.event_progress import ProgressAction
 from mcp_agent.logging.logger import get_logger
 from mcp_agent.mcp.stdio import stdio_client_with_rich_stderr
 from mcp_agent.context_dependent import ContextDependent
@@ -144,7 +146,9 @@ async def _server_lifecycle_task(server_conn: ServerConnection) -> None:
         transport_context = server_conn._transport_context_factory()
 
         async with transport_context as (read_stream, write_stream):
+            #      try:
             server_conn.create_session(read_stream, write_stream)
+            #       except FileNotFoundError as e:
 
             async with server_conn.session:
                 await server_conn.initialize_session()
@@ -153,7 +157,12 @@ async def _server_lifecycle_task(server_conn: ServerConnection) -> None:
 
     except Exception as exc:
         logger.error(
-            f"{server_name}: Lifecycle task encountered an error: {exc}", exc_info=True
+            f"{server_name}: Lifecycle task encountered an error: {exc}",
+            exc_info=True,
+            data={
+                "progress_action": ProgressAction.FATAL_ERROR,
+                "server_name": server_name,
+            },
         )
         # If there's an error, we should also set the event so that
         # 'get_server' won't hang
@@ -295,7 +304,7 @@ class MCPConnectionManager(ContextDependent):
 
         # If the session is still None, it means the lifecycle task crashed
         if not server_conn or not server_conn.session:
-            raise RuntimeError(
+            raise ServerInitializationError(
                 f"{server_name}: Failed to initialize server; check logs for errors."
             )
         return server_conn