fast-agent-mcp 0.0.9__py3-none-any.whl → 0.0.12__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/internal/agent.py

@@ -0,0 +1,17 @@
+import asyncio
+from mcp_agent.core.fastagent import FastAgent
+
+# Create the application
+fast = FastAgent("FastAgent Example")
+
+
+# Define the agent
+@fast.agent(servers=["fetch"])
+async def main():
+    # use the --model command line switch or agent arguments to change model
+    async with fast.run() as agent:
+        await agent()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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",
+    generator="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/mcp_researcher/researcher-eval.py

@@ -35,7 +35,7 @@ Summarize your evaluation as a structured response with:
 - Specific feedback and areas for improvement.""",
 )
 @agents.evaluator_optimizer(
-    optimizer="Researcher",
+    generator="Researcher",
     evaluator="Evaluator",
     max_refinements=5,
     min_rating="EXCELLENT",

mcp_agent/resources/examples/researcher/fastagent.config.yaml

@@ -0,0 +1,53 @@
+#
+# Please edit this configuration file to match your environment (on Windows).
+# Examples in comments below - check/change the paths.
+#
+#
+
+execution_engine: asyncio
+logger:
+  type: file
+  level: error
+  truncate_tools: true
+
+mcp:
+  servers:
+    brave:
+      # On windows replace the command and args line to use `node` and the absolute path to the server.
+      # Use `npm i -g @modelcontextprotocol/server-brave-search` to install the server globally.
+      # Use `npm -g root` to find the global node_modules path.`
+      # command: "node"
+      # args: ["c:/Program Files/nodejs/node_modules/@modelcontextprotocol/server-brave-search/dist/index.js"]
+      command: "npx"
+      args: ["-y", "@modelcontextprotocol/server-brave-search"]
+      env:
+        # You can also place your BRAVE_API_KEY in the fastagent.secrets.yaml file.
+        BRAVE_API_KEY: <your_brave_api_key>
+    filesystem:
+      # On windows update the command and arguments to use `node` and the absolute path to the server.
+      # Use `npm i -g @modelcontextprotocol/server-filesystem` to install the server globally.
+      # Use `npm -g root` to find the global node_modules path.`
+      # command: "node"
+      # args: ["c:/Program Files/nodejs/node_modules/@modelcontextprotocol/server-filesystem/dist/index.js","./agent_folder"]
+      command: "npx"
+      args: ["-y", "@modelcontextprotocol/server-filesystem", "./agent_folder/"]
+    interpreter:
+      command: "docker"
+      args: [
+          "run",
+          "-i",
+          "--rm",
+          "--pull=always",
+          "-v",
+          "./agent_folder:/mnt/data/",
+          # Docker needs the absolute path on Windows (e.g. "x:/fastagent/agent_folder:/mnt/data/")
+          # "./agent_folder:/mnt/data/",
+          "ghcr.io/evalstate/mcp-py-repl:latest",
+        ]
+      roots:
+        - uri: "file://./agent_folder/"
+          name: "agent_folder"
+          server_uri_alias: "file:///mnt/data/"
+    fetch:
+      command: "uvx"
+      args: ["mcp-server-fetch"]

mcp_agent/resources/examples/researcher/researcher-eval.py

@@ -0,0 +1,53 @@
+import asyncio
+
+from mcp_agent.core.fastagent import FastAgent
+
+agents = FastAgent(name="Researcher")
+
+
+@agents.agent(
+    name="Researcher",
+    instruction="""
+You are a research assistant, with access to internet search (via Brave),
+website fetch, a python interpreter (you can install packages with uv) and a filesystem.
+Use the current working directory to save and create files with both the Interpreter and Filesystem tools.
+The interpreter has numpy, pandas, matplotlib and seaborn already installed.
+
+You must always provide a summary of the specific sources you have used in your research.
+    """,
+    servers=["brave", "interpreter", "filesystem", "fetch"],
+)
+@agents.agent(
+    name="Evaluator",
+    model="sonnet",
+    instruction="""
+Evaluate the response from the researcher based on the criteria:
+ - Sources cited. Has the researcher provided a summary of the specific sources used in the research?
+ - Validity. Has the researcher cross-checked and validated data and assumptions.
+ - Alignment. Has the researher acted and addressed feedback from any previous assessments?
+ 
+For each criterion:
+- Provide a rating (EXCELLENT, GOOD, FAIR, or POOR).
+- Offer specific feedback or suggestions for improvement.
+
+Summarize your evaluation as a structured response with:
+- Overall quality rating.
+- Specific feedback and areas for improvement.""",
+)
+@agents.evaluator_optimizer(
+    generator="Researcher",
+    evaluator="Evaluator",
+    max_refinements=5,
+    min_rating="EXCELLENT",
+    name="Researcher_Evaluator",
+)
+async def main():
+    async with agents.run() as agent:
+        await agent.prompt("Researcher_Evaluator")
+
+        print("Ask follow up quesions to the Researcher?")
+        await agent.prompt("Researcher", default="STOP")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

mcp_agent/resources/examples/researcher/researcher.py

@@ -0,0 +1,38 @@
+import asyncio
+
+from mcp_agent.core.fastagent import FastAgent
+# from rich import print
+
+agents = FastAgent(name="Researcher")
+
+
+@agents.agent(
+    "Researcher",
+    instruction="""
+You are a research assistant, with access to internet search (via Brave),
+website fetch, a python interpreter (you can install packages with uv) and a filesystem.
+Use the current working directory to save and create files with both the Interpreter and Filesystem tools.
+The interpreter has numpy, pandas, matplotlib and seaborn already installed
+    """,
+    servers=["brave", "interpreter", "filesystem", "fetch"],
+)
+async def main():
+    research_prompt = """
+Produce an investment report for the company Eutelsat. The final report should be saved in the filesystem in markdown format, and
+contain at least the following: 
+1 - A brief description of the company
+2 - Current financial position (find data, create and incorporate charts)
+3 - A PESTLE analysis
+4 - An investment thesis for the next 3 years. Include both 'buy side' and 'sell side' arguments, and a final 
+summary and recommendation.
+Todays date is 15 February 2025. Include the main data sources consulted in presenting the report."""  # noqa: F841
+
+    async with agents.run() as agent:
+        await agent.prompt()
+
+        # await agent.prompt(default="STOP")
+        #        await agent.prompt(default=research_prompt)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

mcp_agent/resources/examples/workflows/agent.py

@@ -0,0 +1,17 @@
+import asyncio
+from mcp_agent.core.fastagent import FastAgent
+
+# Create the application
+fast = FastAgent("FastAgent Example")
+
+
+# Define the agent
+@fast.agent(servers=["fetch"])
+async def main():
+    # use the --model command line switch or agent arguments to change model
+    async with fast.run() as agent:
+        await agent()
+
+
+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",