fast-agent-mcp 0.0.8__py3-none-any.whl → 0.0.11__py3-none-any.whl

mcp_agent/event_progress.py

@@ -11,14 +11,16 @@ class ProgressAction(str, Enum):
     """Progress actions available in the system."""
 
     STARTING = "Starting"
+    LOADED = "Loaded"
     INITIALIZED = "Initialized"
     CHATTING = "Chatting"
+    ROUTING = "Routing"
+    PLANNING = "Planning"
     READY = "Ready"
     CALLING_TOOL = "Calling Tool"
     FINISHED = "Finished"
     SHUTDOWN = "Shutdown"
     AGGREGATOR_INITIALIZED = "Running"
-    ROUTING = "Routing"
     FATAL_ERROR = "Error"
 
 
@@ -81,7 +83,8 @@ def convert_log_event(event: Event) -> Optional[ProgressEvent]:
         if chat_turn is not None:
             details = f"{model} turn {chat_turn}"
     else:
-        target = event_data.get("target", "unknown")
+        if not target:
+            target = event_data.get("target", "unknown")
 
     return ProgressEvent(
         ProgressAction(progress_action),

mcp_agent/human_input/handler.py

@@ -36,7 +36,9 @@ async def console_input_callback(request: HumanInputRequest) -> HumanInputRespon
             try:
                 loop = asyncio.get_event_loop()
                 response = await asyncio.wait_for(
-                    loop.run_in_executor(None, lambda: Prompt.ask()),
+                    loop.run_in_executor(
+                        None, lambda: Prompt.ask("Provide your response ")
+                    ),
                     request.timeout_seconds,
                 )
             except asyncio.TimeoutError:
@@ -44,6 +46,8 @@ async def console_input_callback(request: HumanInputRequest) -> HumanInputRespon
                 raise TimeoutError("No response received within timeout period")
         else:
             loop = asyncio.get_event_loop()
-            response = await loop.run_in_executor(None, lambda: Prompt.ask())
+            response = await loop.run_in_executor(
+                None, lambda: Prompt.ask("Provide your response ")
+            )
 
     return HumanInputResponse(request_id=request.request_id, response=response.strip())

mcp_agent/logging/rich_progress.py

@@ -68,10 +68,12 @@ class RichProgressDisplay:
         """Map actions to appropriate styles."""
         return {
             ProgressAction.STARTING: "bold yellow",
+            ProgressAction.LOADED: "dim green",
             ProgressAction.INITIALIZED: "dim green",
             ProgressAction.CHATTING: "bold blue",
-            ProgressAction.READY: "dim green",
             ProgressAction.ROUTING: "bold blue",
+            ProgressAction.PLANNING: "bold blue",
+            ProgressAction.READY: "dim green",
             ProgressAction.CALLING_TOOL: "bold magenta",
             ProgressAction.FINISHED: "black on green",
             ProgressAction.SHUTDOWN: "black on red",
@@ -82,29 +84,32 @@ class RichProgressDisplay:
     def update(self, event: ProgressEvent) -> None:
         """Update the progress display with a new event."""
         task_name = event.agent_name or "default"
+
         # Create new task if needed
         if task_name not in self._taskmap:
             task_id = self._progress.add_task(
                 "",
                 total=None,
-                target=f"{event.target}",
-                details=f"{event.agent_name}",
+                target=f"{event.target or task_name}",  # Use task_name as fallback for target
+                details=f"{event.agent_name or ''}",
             )
             self._taskmap[task_name] = task_id
         else:
             task_id = self._taskmap[task_name]
 
+        # Ensure no None values in the update
         self._progress.update(
             task_id,
             description=f"[{self._get_action_style(event.action)}]{event.action.value:<15}",
-            target=event.target,
-            details=event.details if event.details else "",
+            target=event.target or task_name,  # Use task_name as fallback for target
+            details=event.details or "",
             task_name=task_name,
         )
 
         if (
             event.action == ProgressAction.INITIALIZED
             or event.action == ProgressAction.READY
+            or event.action == ProgressAction.LOADED
         ):
             self._progress.update(task_id, completed=100, total=100)
         elif event.action == ProgressAction.FINISHED:

mcp_agent/mcp/mcp_aggregator.py

@@ -81,13 +81,14 @@ class MCPAggregator(ContextDependent):
     def __init__(
         self,
         server_names: List[str],
-        connection_persistence: bool = False,
+        connection_persistence: bool = True,  # Default to True for better stability
         context: Optional["Context"] = None,
         name: str = None,
         **kwargs,
     ):
         """
         :param server_names: A list of server names to connect to.
+        :param connection_persistence: Whether to maintain persistent connections to servers (default: True).
         Note: The server names must be resolvable by the gen_client function, and specified in the server registry.
         """
         super().__init__(

mcp_agent/mcp/mcp_connection_manager.py

@@ -75,6 +75,19 @@ 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
+        self._error_message = None
 
     def request_shutdown(self) -> None:
         """
@@ -164,10 +177,12 @@ async def _server_lifecycle_task(server_conn: ServerConnection) -> None:
                 "server_name": server_name,
             },
         )
+        server_conn._error_occurred = True
+        server_conn._error_message = str(exc)
         # If there's an error, we should also set the event so that
         # 'get_server' won't hang
         server_conn._initialized_event.set()
-        raise
+        # No raise - allow graceful exit
 
 
 class MCPConnectionManager(ContextDependent):
@@ -183,38 +198,34 @@ class MCPConnectionManager(ContextDependent):
         self.server_registry = server_registry
         self.running_servers: Dict[str, ServerConnection] = {}
         self._lock = Lock()
+        # Manage our own task group - independent of task context
+        self._task_group = None
+        self._task_group_active = False
 
     async def __aenter__(self):
-        current_task = asyncio.current_task()
-
-        # Get or create task group from context
-        if not hasattr(self.context, "_connection_task_group"):
-            self.context._connection_task_group = create_task_group()
-            self.context._connection_task_group_context = current_task.get_name()
-            await self.context._connection_task_group.__aenter__()
-
-        self._tg = self.context._connection_task_group
+        # Create a task group that isn't tied to a specific task
+        self._task_group = create_task_group()
+        # Enter the task group context
+        await self._task_group.__aenter__()
+        self._task_group_active = True
+        self._tg = self._task_group
         return self
 
     async def __aexit__(self, exc_type, exc_val, exc_tb):
         """Ensure clean shutdown of all connections before exiting."""
-        current_task = asyncio.current_task()
-
         try:
             # First request all servers to shutdown
             await self.disconnect_all()
-
-            # Only clean up task group if we're in the original context
-            if (
-                hasattr(self.context, "_connection_task_group")
-                and current_task.get_name()
-                == self.context._connection_task_group_context
-            ):
-                await self.context._connection_task_group.__aexit__(
-                    exc_type, exc_val, exc_tb
-                )
-                delattr(self.context, "_connection_task_group")
-                delattr(self.context, "_connection_task_group_context")
+            
+            # 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)
+                self._task_group_active = False
+                self._task_group = None
+                self._tg = None
         except Exception as e:
             logger.error(f"Error during connection manager shutdown: {e}")
 
@@ -231,10 +242,13 @@ class MCPConnectionManager(ContextDependent):
         Connect to a server and return a RunningServer instance that will persist
         until explicitly disconnected.
         """
-        if not self._tg:
-            raise RuntimeError(
-                "MCPConnectionManager must be used inside an async context (i.e. 'async with' or after __aenter__)."
-            )
+        # Create task group if it doesn't exist yet - make this method more resilient
+        if not self._task_group_active:
+            self._task_group = create_task_group()
+            await self._task_group.__aenter__()
+            self._task_group_active = True
+            self._tg = self._task_group
+            logger.info(f"Auto-created task group for server: {server_name}")
 
         config = self.server_registry.registry.get(server_name)
         if not config:
@@ -286,11 +300,17 @@ class MCPConnectionManager(ContextDependent):
         """
         Get a running server instance, launching it if needed.
         """
-        # Get the server connection if it's already running
+        # Get the server connection if it's already running and healthy
         async with self._lock:
             server_conn = self.running_servers.get(server_name)
-            if server_conn:
+            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...")
+                self.running_servers.pop(server_name)
+                server_conn.request_shutdown()
 
         # Launch the connection
         server_conn = await self.launch_server(
@@ -302,11 +322,13 @@ class MCPConnectionManager(ContextDependent):
         # Wait until it's fully initialized, or an error occurs
         await server_conn.wait_for_initialized()
 
-        # If the session is still None, it means the lifecycle task crashed
-        if not server_conn or not server_conn.session:
+        # Check if the server is healthy after initialization
+        if not server_conn.is_healthy():
+            error_msg = server_conn._error_message or "Unknown error"
             raise ServerInitializationError(
-                f"{server_name}: Failed to initialize server; check logs for errors."
+                f"{server_name}: Failed to initialize server: {error_msg}"
             )
+        
         return server_conn
 
     async def disconnect_server(self, server_name: str) -> None:
@@ -329,11 +351,19 @@ class MCPConnectionManager(ContextDependent):
 
     async def disconnect_all(self) -> None:
         """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
-
-            for name, conn in self.running_servers.items():
-                conn.request_shutdown()
-
+                
+            # 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...")
+            conn.request_shutdown()

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

@@ -7,7 +7,7 @@ fast = FastAgent("Data Analysis (Roots)")
 
 
 @fast.agent(
-    name="Data_Analysis",
+    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. 

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

@@ -1,5 +1,7 @@
 default_model: sonnet
 
+# on windows, adjust the mount point to be the full path e.g. x:/temp/data-analysis/mount-point:/mnt/data/
+
 mcp:
   servers:
     interpreter:

mcp_agent/resources/examples/internal/job.py

@@ -0,0 +1,83 @@
+"""
+PMO Job Description Generator Agent
+  Purpose: Generate comprehensive PMO job descriptions using a multi-stage approach
+  for clarity, consistency and quality control
+"""
+
+import asyncio
+from mcp_agent.core.fastagent import FastAgent
+
+# Create the application
+fast = FastAgent("PMO Job Description Generator")
+
+
+@fast.agent(
+    name="content_generator",
+    instruction="""You are a PMO job description expert. Generate job descriptions for PMO roles         
+    following these guidelines:                                                                          
+    - Focus on modern lean/agile and product-based approaches                                            
+    - Emphasize practical experience and demonstrated results over formal requirements                   
+    - Ensure clear role differentiation with minimal overlap                                             
+    - Format output in Markdown                                                                          
+    - Context: Telecommunications industry in open organization valuing practical experience             
+                                                                                                        
+    Structure each job description with:                                                                 
+    1. Role Title                                                                                        
+    2. Position Summary                                                                                  
+    3. Key Responsibilities                                                                              
+    4. Required Experience                                                                               
+    5. Desired Capabilities                                                                              
+    """,
+    model="anthropic.claude-3-5-haiku-latest",
+)
+@fast.agent(
+    name="consistency_checker",
+    instruction="""Review PMO job descriptions for:                                                      
+    1. Alignment with lean/agile principles                                                              
+    2. Clear role differentiation                                                                        
+    3. Progressive responsibility levels                                                                 
+    4. Consistent formatting and structure                                                               
+    5. Telecommunications industry relevance                                                             
+    6. Emphasis on practical experience over formal requirements                                         
+                                                                                                        
+    Provide specific feedback for improvements.""",
+    model="gpt-4o",
+)
+@fast.agent(
+    name="file_handler",
+    instruction="""Save the finalized job descriptions as individual Markdown files.                     
+    Use consistent naming like 'pmo_director.md', 'pmo_manager.md' etc.""",
+    servers=["filesystem"],
+    use_history=False,
+)
+@fast.evaluator_optimizer(
+    name="job_description_writer",
+    optimizer="content_generator",
+    evaluator="consistency_checker",
+    min_rating="EXCELLENT",
+    max_refinements=2,
+)
+async def main():
+    async with fast.run() as agent:
+        roles = [
+            "PMO Director",
+            "Portfolio Manager",
+            "Senior Program Manager",
+            "Project Manager",
+            "PMO Analyst",
+            "Project Coordinator",
+        ]
+
+        # Pre-initialize the file_handler to establish a persistent connection
+        await agent.file_handler("Test connection to filesystem")
+
+        for role in roles:
+            # Generate and refine job description
+            description = await agent.job_description_writer(
+                f"Create job description for {role} role"
+            )
+            await agent.file_handler(f"Save this job description: {description}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

mcp_agent/resources/examples/workflows/agent_build.py

@@ -0,0 +1,61 @@
+"""
+This demonstrates creating multiple agents and an orchestrator to coordinate them.
+"""
+
+import asyncio
+from mcp_agent.core.fastagent import FastAgent
+
+# Create the application
+fast = FastAgent("Agent Builder")
+
+
+@fast.agent(
+    "agent_expert",
+    instruction="""
+You design agent workflows, using the practices from 'Building Effective Agents'. You provide concise
+specific guidance on design and composition. Prefer simple solutions, and don't nest workflows more 
+than one level deep. Your ultimate goal will be to produce a single '.py' agent in the style
+shown to you that fulfils the Human's needs.
+Keep the application simple, define agents with appropriate  MCP Servers, Tools  and the Human Input Tool.
+The style of the program should be like the examples you have been showm, very little additional code (use
+very simple Python where necessary). """,
+    servers=["filesystem", "fetch"],
+)
+# Define worker agents
+@fast.agent(
+    "requirements_capture",
+    instruction="""
+You help the Human define their requirements for building Agent based systems. Keep questions short and
+simple, collaborate with the agent_expert or other agents in the workflow to refine human interaction. 
+Keep requests to the Human simple and minimal. """,
+    human_input=True,
+)
+# Define the orchestrator to coordinate the other agents
+@fast.orchestrator(
+    name="orchestrator_worker",
+    agents=["agent_expert", "requirements_capture"],
+    model="sonnet",
+)
+async def main():
+    async with fast.run() as agent:
+        await agent.agent_expert("""
+- Read this paper: https://www.anthropic.com/research/building-effective-agents" to understand
+the principles of Building Effective Agents. 
+- Read and examing the sample agent and workflow definitions in the current directory:
+  - chaining.py - simple agent chaining example.
+  - parallel.py - parallel agents example.
+  - evaluator.py - evaluator optimizer example.
+  - orchestrator.py - complex orchestration example.
+  - router.py - workflow routing example.
+- Load the 'fastagent.config.yaml' file to see the available and configured MCP Servers.
+When producing the agent/workflow definition, keep to a simple single .py file in the style
+of the examples.
+        """)
+
+        await agent.orchestrator_worker(
+            "Write an Agent program that fulfils the Human's needs."
+        )
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

mcp_agent/resources/examples/workflows/chaining.py

@@ -9,7 +9,6 @@ fast = FastAgent("Agent Chaining")
     "url_fetcher",
     instruction="Given a URL, provide a complete and comprehensive summary",
     servers=["fetch"],
-    model="haiku",
 )
 @fast.agent(
     "social_media",

mcp_agent/resources/examples/workflows/human_input.py

@@ -13,7 +13,6 @@ fast = FastAgent("Human Input")
 @fast.agent(
     instruction="An AI agent that assists with basic tasks. Request Human Input when needed.",
     human_input=True,
-    model="gpt-4o",
 )
 async def main():
     async with fast.run() as agent:

mcp_agent/resources/examples/workflows/orchestrator.py

@@ -24,7 +24,7 @@ fast = FastAgent("Orchestrator-Workers")
             the closest match to a user's request, make the appropriate tool calls, 
             and return the URI and CONTENTS of the closest match.""",
     servers=["fetch", "filesystem"],
-    model="gpt-4o-mini",
+    model="gpt-4o",
 )
 @fast.agent(
     name="writer",
@@ -44,12 +44,6 @@ fast = FastAgent("Orchestrator-Workers")
 # Define the orchestrator to coordinate the other agents
 @fast.orchestrator(
     name="orchestrate",
-    instruction="""Load the student's short story from short_story.md, 
-    and generate a report with feedback across proofreading, 
-    factuality/logical consistency and style adherence. Use the style rules from 
-    https://apastyle.apa.org/learn/quick-guide-on-formatting and 
-    https://apastyle.apa.org/learn/quick-guide-on-references.
-    Write the graded report to graded_report.md in the same directory as short_story.md""",
     agents=["finder", "writer", "proofreader"],
     model="sonnet",
 )

mcp_agent/workflows/evaluator_optimizer/evaluator_optimizer.py

@@ -169,98 +169,96 @@ class EvaluatorOptimizerLLM(AugmentedLLM[MessageParamT, MessageT]):
         best_response = None
         best_rating = QualityRating.POOR
         self.refinement_history = []
-
-        # Initial generation
+        
+        # Use a single AsyncExitStack for the entire method to maintain connections
         async with contextlib.AsyncExitStack() as stack:
+            # Enter all agent contexts once at the beginning
             if isinstance(self.optimizer, Agent):
                 await stack.enter_async_context(self.optimizer)
+            if isinstance(self.evaluator, Agent):
+                await stack.enter_async_context(self.evaluator)
+                
+            # Initial generation
             response = await self.optimizer_llm.generate(
                 message=message,
                 request_params=request_params,
             )
 
-        best_response = response
+            best_response = response
 
-        while refinement_count < self.max_refinements:
-            logger.debug("Optimizer result:", data=response)
+            while refinement_count < self.max_refinements:
+                logger.debug("Optimizer result:", data=response)
 
-            # Evaluate current response
-            eval_prompt = self._build_eval_prompt(
-                original_request=str(message),
-                current_response="\n".join(str(r) for r in response)
-                if isinstance(response, list)
-                else str(response),
-                iteration=refinement_count,
-            )
-
-            evaluation_result = None
-            async with contextlib.AsyncExitStack() as stack:
-                if isinstance(self.evaluator, Agent):
-                    await stack.enter_async_context(self.evaluator)
+                # Evaluate current response
+                eval_prompt = self._build_eval_prompt(
+                    original_request=str(message),
+                    current_response="\n".join(str(r) for r in response)
+                    if isinstance(response, list)
+                    else str(response),
+                    iteration=refinement_count,
+                )
 
+                # No need for nested AsyncExitStack here - using the outer one
                 evaluation_result = await self.evaluator_llm.generate_structured(
                     message=eval_prompt,
                     response_model=EvaluationResult,
                     request_params=request_params,
                 )
 
-            # Track iteration
-            self.refinement_history.append(
-                {
-                    "attempt": refinement_count + 1,
-                    "response": response,
-                    "evaluation_result": evaluation_result,
-                }
-            )
-
-            logger.debug("Evaluator result:", data=evaluation_result)
-
-            # Track best response (using enum ordering)
-            if evaluation_result.rating.value > best_rating.value:
-                best_rating = evaluation_result.rating
-                best_response = response
-                logger.debug(
-                    "New best response:",
-                    data={"rating": best_rating, "response": best_response},
+                # Track iteration
+                self.refinement_history.append(
+                    {
+                        "attempt": refinement_count + 1,
+                        "response": response,
+                        "evaluation_result": evaluation_result,
+                    }
                 )
 
-            # Check if we've reached acceptable quality
-            if (
-                evaluation_result.rating.value >= self.min_rating.value
-                or not evaluation_result.needs_improvement
-            ):
-                logger.debug(
-                    f"Acceptable quality {evaluation_result.rating.value} reached",
-                    data={
-                        "rating": evaluation_result.rating.value,
-                        "needs_improvement": evaluation_result.needs_improvement,
-                        "min_rating": self.min_rating.value,
-                    },
+                logger.debug("Evaluator result:", data=evaluation_result)
+
+                # Track best response (using enum ordering)
+                if evaluation_result.rating.value > best_rating.value:
+                    best_rating = evaluation_result.rating
+                    best_response = response
+                    logger.debug(
+                        "New best response:",
+                        data={"rating": best_rating, "response": best_response},
+                    )
+
+                # Check if we've reached acceptable quality
+                if (
+                    evaluation_result.rating.value >= self.min_rating.value
+                    or not evaluation_result.needs_improvement
+                ):
+                    logger.debug(
+                        f"Acceptable quality {evaluation_result.rating.value} reached",
+                        data={
+                            "rating": evaluation_result.rating.value,
+                            "needs_improvement": evaluation_result.needs_improvement,
+                            "min_rating": self.min_rating.value,
+                        },
+                    )
+                    break
+
+                # Generate refined response
+                refinement_prompt = self._build_refinement_prompt(
+                    original_request=str(message),
+                    current_response="\n".join(str(r) for r in response)
+                    if isinstance(response, list)
+                    else str(response),
+                    feedback=evaluation_result,
+                    iteration=refinement_count,
                 )
-                break
-
-            # Generate refined response
-            refinement_prompt = self._build_refinement_prompt(
-                original_request=str(message),
-                current_response="\n".join(str(r) for r in response)
-                if isinstance(response, list)
-                else str(response),
-                feedback=evaluation_result,
-                iteration=refinement_count,
-            )
-
-            async with contextlib.AsyncExitStack() as stack:
-                if isinstance(self.optimizer, Agent):
-                    await stack.enter_async_context(self.optimizer)
 
+                # No nested AsyncExitStack here either
                 response = await self.optimizer_llm.generate(
                     message=refinement_prompt,
                     request_params=request_params,
                 )
 
-            refinement_count += 1
+                refinement_count += 1
 
-        return best_response
+            return best_response
 
     async def generate_str(
         self,