fast-agent-mcp 0.0.7__py3-none-any.whl → 0.0.8__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
@@ -28,7 +35,6 @@ from mcp_agent.workflows.llm.augmented_llm import RequestParams
 
 import readline  # noqa: F401
 
-
 # Type aliases for better readability
 WorkflowType: TypeAlias = Union[
     Orchestrator, ParallelLLM, EvaluatorOptimizerLLM, LLMRouter
@@ -304,6 +310,85 @@ 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.
+        Raises ValueError if any referenced components are not defined.
+        """
+        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
+                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)}"
+                    )
+
+            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,
@@ -350,6 +435,7 @@ class FastAgent(ContextDependent):
         model: Optional[str] = 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 +448,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 +466,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,10 +476,7 @@ 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
 
@@ -404,6 +488,7 @@ class FastAgent(ContextDependent):
         model: str | None = None,
         use_history: bool = True,
         request_params: Optional[Dict] = None,
+        human_input: bool = False,
     ) -> Callable:
         """
         Decorator to create and register an orchestrator.
@@ -431,6 +516,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 +527,7 @@ class FastAgent(ContextDependent):
                 "func": func,
             }
 
-            async def wrapper(*args, **kwargs):
-                return await func(*args, **kwargs)
-
-            return wrapper
+            return func
 
         return decorator
 
@@ -495,10 +578,7 @@ class FastAgent(ContextDependent):
                 "func": func,
             }
 
-            async def wrapper(*args, **kwargs):
-                return await func(*args, **kwargs)
-
-            return wrapper
+            return func
 
         return decorator
 
@@ -557,10 +637,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 +665,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
@@ -937,77 +1019,86 @@ 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
+                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)
 
-            # 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

mcp_agent/resources/examples/data-analysis/analysis.py

@@ -0,0 +1,35 @@
+import asyncio
+
+from mcp_agent.core.fastagent import FastAgent
+
+# Create the application
+fast = FastAgent("Data Analysis (Roots)")
+
+
+@fast.agent(
+    name="Data_Analysis",
+    instruction="""
+You have access to a Python 3.12 interpreter and you can use this to analyse and process data. 
+Common analysis packages such as Pandas, Seaborn and Matplotlib are already installed. 
+You can add further packages if needed.
+Data files are accessible from the /mnt/data/ directory (this is the current working directory).
+Visualisations should be saved as .png files in the current working directory.
+""",
+    servers=["interpreter"],
+)
+async def main():
+    # Use the app's context manager
+    async with fast.run() as agent:
+        await agent(
+            "There is a csv file in the current directory. "
+            "Analyse the file, produce a detailed description of the data, and any patterns it contains.",
+        )
+        await agent(
+            "Consider the data, and how to usefully group it for presentation to a Human. Find insights, using the Python Interpreter as needed.\n"
+            "Use MatPlotLib to produce insightful visualisations. Save them as '.png' files in the current directory. Be sure to run the code and save the files.\n"
+            "Produce a summary with major insights to the data",
+        )
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

mcp_agent/resources/examples/data-analysis/fastagent.config.yaml

@@ -0,0 +1,20 @@
+default_model: sonnet
+
+mcp:
+  servers:
+    interpreter:
+      command: "docker"
+      args:
+        [
+          "run",
+          "-i",
+          "--rm",
+          "--pull=always",
+          "-v",
+          "./mount-point:/mnt/data/",
+          "ghcr.io/evalstate/mcp-py-repl:latest",
+        ]
+      roots:
+        - uri: "file://./mount-point/"
+          name: "test_data"
+          server_uri_alias: "file:///mnt/data/"