fast-agent-mcp 0.1.13__py3-none-any.whl → 0.2.0__py3-none-any.whl

mcp_agent/agents/workflow/parallel_agent.py

@@ -0,0 +1,182 @@
+import asyncio
+from typing import Any, List, Optional
+
+from mcp.types import TextContent
+
+from mcp_agent.agents.agent import Agent, AgentConfig
+from mcp_agent.agents.base_agent import BaseAgent
+from mcp_agent.core.request_params import RequestParams
+from mcp_agent.mcp.interfaces import ModelT
+from mcp_agent.mcp.prompt_message_multipart import PromptMessageMultipart
+
+
+class ParallelAgent(BaseAgent):
+    """
+    LLMs can sometimes work simultaneously on a task (fan-out)
+    and have their outputs aggregated programmatically (fan-in).
+    This workflow performs both the fan-out and fan-in operations using LLMs.
+    From the user's perspective, an input is specified and the output is returned.
+    """
+
+    def __init__(
+        self,
+        config: AgentConfig,
+        fan_in_agent: Agent,
+        fan_out_agents: List[Agent],
+        include_request: bool = True,
+        **kwargs,
+    ) -> None:
+        """
+        Initialize a ParallelLLM agent.
+
+        Args:
+            config: Agent configuration or name
+            fan_in_agent: Agent that aggregates results from fan-out agents
+            fan_out_agents: List of agents to execute in parallel
+            include_request: Whether to include the original request in the aggregation
+            **kwargs: Additional keyword arguments to pass to BaseAgent
+        """
+        super().__init__(config, **kwargs)
+        self.fan_in_agent = fan_in_agent
+        self.fan_out_agents = fan_out_agents
+        self.include_request = include_request
+
+    async def generate(
+        self,
+        multipart_messages: List[PromptMessageMultipart],
+        request_params: Optional[RequestParams] = None,
+    ) -> PromptMessageMultipart:
+        """
+        Execute fan-out agents in parallel and aggregate their results with the fan-in agent.
+
+        Args:
+            multipart_messages: List of messages to send to the fan-out agents
+            request_params: Optional parameters to configure the request
+
+        Returns:
+            The aggregated response from the fan-in agent
+        """
+        # Execute all fan-out agents in parallel
+        responses: List[PromptMessageMultipart] = await asyncio.gather(
+            *[agent.generate(multipart_messages, request_params) for agent in self.fan_out_agents]
+        )
+
+        # Extract the received message from the input
+        received_message: Optional[str] = (
+            multipart_messages[-1].all_text() if multipart_messages else None
+        )
+
+        # Convert responses to strings for aggregation
+        string_responses = []
+        for response in responses:
+            string_responses.append(response.all_text())
+
+        # Format the responses and send to the fan-in agent
+        aggregated_prompt = self._format_responses(string_responses, received_message)
+
+        # Create a new multipart message with the formatted responses
+        formatted_prompt = PromptMessageMultipart(
+            role="user", content=[TextContent(type="text", text=aggregated_prompt)]
+        )
+
+        # Use the fan-in agent to aggregate the responses
+        return await self.fan_in_agent.generate([formatted_prompt], request_params)
+
+    def _format_responses(self, responses: List[Any], message: Optional[str] = None) -> str:
+        """
+        Format a list of responses for the fan-in agent.
+
+        Args:
+            responses: List of responses from fan-out agents
+            message: Optional original message that was sent to the agents
+
+        Returns:
+            Formatted string with responses
+        """
+        formatted = []
+
+        # Include the original message if specified
+        if self.include_request and message:
+            formatted.append("The following request was sent to the agents:")
+            formatted.append(f"<fastagent:request>\n{message}\n</fastagent:request>")
+
+        # Format each agent's response
+        for i, response in enumerate(responses):
+            agent_name = self.fan_out_agents[i].name
+            formatted.append(
+                f'<fastagent:response agent="{agent_name}">\n{response}\n</fastagent:response>'
+            )
+        return "\n\n".join(formatted)
+
+    async def structured(
+        self,
+        prompt: List[PromptMessageMultipart],
+        model: type[ModelT],
+        request_params: Optional[RequestParams] = None,
+    ) -> Optional[ModelT]:
+        """
+        Apply the prompt and return the result as a Pydantic model.
+
+        This implementation delegates to the fan-in agent's structured method.
+
+        Args:
+            prompt: List of PromptMessageMultipart objects
+            model: The Pydantic model class to parse the result into
+            request_params: Optional parameters to configure the LLM request
+
+        Returns:
+            An instance of the specified model, or None if coercion fails
+        """
+        # Generate parallel responses first
+        responses: List[PromptMessageMultipart] = await asyncio.gather(
+            *[agent.generate(prompt, request_params) for agent in self.fan_out_agents]
+        )
+
+        # Extract the received message
+        received_message: Optional[str] = prompt[-1].all_text() if prompt else None
+
+        # Convert responses to strings
+        string_responses = [response.all_text() for response in responses]
+
+        # Format the responses for the fan-in agent
+        aggregated_prompt = self._format_responses(string_responses, received_message)
+
+        # Create a multipart message
+        formatted_prompt = PromptMessageMultipart(
+            role="user", content=[TextContent(type="text", text=aggregated_prompt)]
+        )
+
+        # Use the fan-in agent to parse the structured output
+        return await self.fan_in_agent.structured([formatted_prompt], model, request_params)
+
+    async def initialize(self) -> None:
+        """
+        Initialize the agent and its fan-in and fan-out agents.
+        """
+        await super().initialize()
+
+        # Initialize fan-in and fan-out agents if not already initialized
+        if not getattr(self.fan_in_agent, "initialized", False):
+            await self.fan_in_agent.initialize()
+
+        for agent in self.fan_out_agents:
+            if not getattr(agent, "initialized", False):
+                await agent.initialize()
+
+    async def shutdown(self) -> None:
+        """
+        Shutdown the agent and its fan-in and fan-out agents.
+        """
+        await super().shutdown()
+
+        # Shutdown fan-in and fan-out agents
+        try:
+            await self.fan_in_agent.shutdown()
+        except Exception as e:
+            self.logger.warning(f"Error shutting down fan-in agent: {str(e)}")
+
+        for agent in self.fan_out_agents:
+            try:
+                await agent.shutdown()
+            except Exception as e:
+                self.logger.warning(f"Error shutting down fan-out agent {agent.name}: {str(e)}")

mcp_agent/agents/workflow/router_agent.py

@@ -0,0 +1,307 @@
+"""
+Router agent implementation using the BaseAgent adapter pattern.
+
+This provides a simplified implementation that routes messages to agents
+by determining the best agent for a request and dispatching to it.
+"""
+
+from typing import TYPE_CHECKING, List, Optional, Type
+
+from mcp.types import TextContent
+from pydantic import BaseModel
+
+from mcp_agent.agents.agent import Agent
+from mcp_agent.agents.base_agent import BaseAgent
+from mcp_agent.core.agent_types import AgentConfig
+from mcp_agent.core.exceptions import AgentConfigError
+from mcp_agent.core.request_params import RequestParams
+from mcp_agent.logging.logger import get_logger
+from mcp_agent.mcp.interfaces import ModelT
+from mcp_agent.mcp.prompt_message_multipart import PromptMessageMultipart
+
+if TYPE_CHECKING:
+    from mcp_agent.context import Context
+
+logger = get_logger(__name__)
+
+# Simple system instruction for the router
+ROUTING_SYSTEM_INSTRUCTION = """
+You are a highly accurate request router that directs incoming requests to the most appropriate agent.
+Analyze each request and determine which specialized agent would be best suited to handle it based on their capabilities.
+
+Follow these guidelines:
+- Carefully match the request's needs with each agent's capabilities and description
+- Select the single most appropriate agent for the request
+- Provide your confidence level (high, medium, low) and brief reasoning for your selection
+"""
+
+# Default routing instruction with placeholders for context and request
+DEFAULT_ROUTING_INSTRUCTION = """
+You are a highly accurate request router that directs incoming requests to the most appropriate agent.
+
+<fastagent:data>
+<fastagent:agents>
+{context}
+</fastagent:agents>
+
+<fastagent:request>
+{request}
+</fastagent:request>
+</fastagent:data>
+
+Your task is to analyze the request and determine the most appropriate agent from the options above.
+
+<fastagent:instruction>
+Respond in JSON format. NEVER include Code Fences:
+{{
+    "agent": "<agent name>",
+    "confidence": "<high, medium or low>",
+    "reasoning": "<brief explanation>"
+}}
+</fastagent:instruction>
+"""
+
+
+class RoutingResponse(BaseModel):
+    """Model for the structured routing response from the LLM."""
+
+    agent: str
+    confidence: str
+    reasoning: Optional[str] = None
+
+
+class RouterResult(BaseModel):
+    """Router result with agent reference and confidence rating."""
+
+    result: Agent
+    confidence: str
+    reasoning: Optional[str] = None
+
+    # Allow Agent objects to be stored without serialization
+    model_config = {"arbitrary_types_allowed": True}
+
+
+class RouterAgent(BaseAgent):
+    """
+    A simplified router that uses an LLM to determine the best agent for a request,
+    then dispatches the request to that agent and returns the response.
+    """
+
+    def __init__(
+        self,
+        config: AgentConfig,
+        agents: List[Agent],
+        routing_instruction: Optional[str] = None,
+        context: Optional["Context"] = None,
+        default_request_params: Optional[RequestParams] = None,
+        **kwargs,
+    ) -> None:
+        """
+        Initialize a RouterAgent.
+
+        Args:
+            config: Agent configuration or name
+            agents: List of agents to route between
+            routing_instruction: Optional custom routing instruction
+            context: Optional application context
+            default_request_params: Optional default request parameters
+            **kwargs: Additional keyword arguments to pass to BaseAgent
+        """
+        super().__init__(config=config, context=context, **kwargs)
+
+        if not agents:
+            raise AgentConfigError("At least one agent must be provided")
+
+        self.agents = agents
+        self.routing_instruction = routing_instruction
+        self.agent_map = {agent.name: agent for agent in agents}
+
+        # Set up base router request parameters
+        base_params = {"systemPrompt": ROUTING_SYSTEM_INSTRUCTION, "use_history": False}
+
+        # Merge with provided defaults if any
+        if default_request_params:
+            # Start with defaults and override with router-specific settings
+            merged_params = default_request_params.model_copy(update=base_params)
+        else:
+            merged_params = RequestParams(**base_params)
+
+        self._default_request_params = merged_params
+
+    async def initialize(self) -> None:
+        """Initialize the router and all agents."""
+        if not self.initialized:
+            await super().initialize()
+
+            # Initialize all agents if not already initialized
+            for agent in self.agents:
+                if not getattr(agent, "initialized", False):
+                    await agent.initialize()
+
+            self.initialized = True
+
+    async def shutdown(self) -> None:
+        """Shutdown the router and all agents."""
+        await super().shutdown()
+
+        # Shutdown all agents
+        for agent in self.agents:
+            try:
+                await agent.shutdown()
+            except Exception as e:
+                logger.warning(f"Error shutting down agent: {str(e)}")
+
+    async def _get_routing_result(
+        self,
+        messages: List[PromptMessageMultipart],
+    ) -> Optional[RouterResult]:
+        """
+        Common method to extract request and get routing result.
+
+        Args:
+            messages: The messages to extract request from
+
+        Returns:
+            RouterResult containing the selected agent, or None if no suitable agent found
+        """
+        if not self.initialized:
+            await self.initialize()
+
+        # Extract the request text from the last message
+        request = messages[-1].all_text() if messages else ""
+
+        # Determine which agent to route to
+        routing_result = await self._route_request(request)
+
+        if not routing_result:
+            logger.warning("Could not determine appropriate agent for this request")
+
+        return routing_result
+
+    async def generate(
+        self,
+        multipart_messages: List[PromptMessageMultipart],
+        request_params: Optional[RequestParams] = None,
+    ) -> PromptMessageMultipart:
+        """
+        Route the request to the most appropriate agent and return its response.
+
+        Args:
+            multipart_messages: Messages to route
+            request_params: Optional request parameters
+
+        Returns:
+            The response from the selected agent
+        """
+        routing_result = await self._get_routing_result(multipart_messages)
+
+        if not routing_result:
+            return PromptMessageMultipart(
+                role="assistant",
+                content=[
+                    TextContent(
+                        type="text", text="Could not determine appropriate agent for this request."
+                    )
+                ],
+            )
+
+        # Get the selected agent
+        selected_agent = routing_result.result
+
+        # Log the routing decision
+        logger.info(
+            f"Routing request to agent: {selected_agent.name} (confidence: {routing_result.confidence})"
+        )
+
+        # Dispatch the request to the selected agent
+        return await selected_agent.generate(multipart_messages, request_params)
+
+    async def structured(
+        self,
+        prompt: List[PromptMessageMultipart],
+        model: Type[ModelT],
+        request_params: Optional[RequestParams] = None,
+    ) -> Optional[ModelT]:
+        """
+        Route the request to the most appropriate agent and parse its response.
+
+        Args:
+            prompt: Messages to route
+            model: Pydantic model to parse the response into
+            request_params: Optional request parameters
+
+        Returns:
+            The parsed response from the selected agent, or None if parsing fails
+        """
+        routing_result = await self._get_routing_result(prompt)
+
+        if not routing_result:
+            return None
+
+        # Get the selected agent
+        selected_agent = routing_result.result
+
+        # Log the routing decision
+        logger.info(
+            f"Routing structured request to agent: {selected_agent.name} (confidence: {routing_result.confidence})"
+        )
+
+        # Dispatch the request to the selected agent
+        return await selected_agent.structured(prompt, model, request_params)
+
+    async def _route_request(self, request: str) -> Optional[RouterResult]:
+        """
+        Determine which agent to route the request to.
+
+        Args:
+            request: The request to route
+
+        Returns:
+            RouterResult containing the selected agent, or None if no suitable agent was found
+        """
+        if not self.agents:
+            logger.warning("No agents available for routing")
+            return None
+
+        # If only one agent is available, use it directly
+        if len(self.agents) == 1:
+            return RouterResult(
+                result=self.agents[0], confidence="high", reasoning="Only one agent available"
+            )
+
+        # Generate agent descriptions for the context
+        agent_descriptions = []
+        for i, agent in enumerate(self.agents, 1):
+            description = agent.instruction if isinstance(agent.instruction, str) else ""
+            agent_descriptions.append(f"{i}. Name: {agent.name} - {description}")
+
+        context = "\n\n".join(agent_descriptions)
+
+        # Format the routing prompt
+        routing_instruction = self.routing_instruction or DEFAULT_ROUTING_INSTRUCTION
+        prompt_text = routing_instruction.format(context=context, request=request)
+
+        # Create multipart message for the router
+        prompt = PromptMessageMultipart(
+            role="user", content=[TextContent(type="text", text=prompt_text)]
+        )
+
+        # Get structured response from LLM
+        response = await self._llm.structured(
+            [prompt], RoutingResponse, self._default_request_params
+        )
+
+        if not response:
+            logger.warning("No routing response received from LLM")
+            return None
+
+        # Look up the agent by name
+        selected_agent = self.agent_map.get(response.agent)
+
+        if not selected_agent:
+            logger.warning(f"Agent '{response.agent}' not found in available agents")
+            return None
+
+        return RouterResult(
+            result=selected_agent, confidence=response.confidence, reasoning=response.reasoning
+        )

mcp_agent/app.py

@@ -72,7 +72,9 @@ class MCPApp:
     @property
     def context(self) -> Context:
         if self._context is None:
-            raise RuntimeError("MCPApp not initialized, please call initialize() first, or use async with app.run().")
+            raise RuntimeError(
+                "MCPApp not initialized, please call initialize() first, or use async with app.run()."
+            )
         return self._context
 
     @property

mcp_agent/cli/commands/bootstrap.py

@@ -70,8 +70,9 @@ def copy_example_files(example_type: str, target_dir: Path, force: bool = False)
             mount_point_dir.mkdir(parents=True)
             console.print(f"Created mount-point directory: {mount_point_dir}")
 
-    # Use the resources directory from the package
-    source_dir = Path(__file__).parent.parent.parent / "resources" / "examples" / ("workflows" if example_type == "workflow" else f"{example_type}")
+    # Use examples from top-level directory
+    package_dir = Path(__file__).parent.parent.parent.parent.parent
+    source_dir = package_dir / "examples" / ("workflows" if example_type == "workflow" else f"{example_type}")
 
     if not source_dir.exists():
         console.print(f"[red]Error: Source directory not found: {source_dir}[/red]")
@@ -110,7 +111,9 @@ def copy_example_files(example_type: str, target_dir: Path, force: bool = False)
                     continue
 
                 if target.exists() and not force:
-                    console.print(f"[yellow]Skipping[/yellow] mount-point/{filename} (already exists)")
+                    console.print(
+                        f"[yellow]Skipping[/yellow] mount-point/{filename} (already exists)"
+                    )
                     continue
 
                 shutil.copy2(source, target)
@@ -137,7 +140,9 @@ def show_overview() -> None:
     for name, info in EXAMPLE_TYPES.items():
         files_list = "\n".join(f"• {f}" for f in info["files"])
         if "mount_point_files" in info:
-            files_list += "\n[blue]mount-point:[/blue]\n" + "\n".join(f"• {f}" for f in info["mount_point_files"])
+            files_list += "\n[blue]mount-point:[/blue]\n" + "\n".join(
+                f"• {f}" for f in info["mount_point_files"]
+            )
         table.add_row(f"[green]{name}[/green]", info["description"], files_list)
 
     console.print(table)
@@ -229,17 +234,23 @@ def _show_completion_message(example_type: str, created: list[str]) -> None:
             console.print("   - evaluator.py: Add evaluation capabilities")
             console.print("   - human_input.py: Incorporate human feedback")
             console.print("3. Run an example with: uv run <example>.py")
-            console.print("4. Try a different model with --model=<model>, or update the agent config")
+            console.print(
+                "4. Try a different model with --model=<model>, or update the agent config"
+            )
 
         elif example_type == "researcher":
-            console.print("1. Set up the Brave MCP Server (get an API key from https://brave.com/search/api/)")
+            console.print(
+                "1. Set up the Brave MCP Server (get an API key from https://brave.com/search/api/)"
+            )
             console.print("2. Try `uv run researcher.py` for the basic version")
             console.print("3. Try `uv run researcher-eval.py` for the eval/optimize version")
         elif example_type == "data-analysis":
             console.print("1. Run uv `analysis.py` to perform data analysis and visualization")
             console.print("2. The dataset is available in the mount-point directory:")
             console.print("   - mount-point/WA_Fn-UseC_-HR-Employee-Attrition.csv")
-            console.print("On Windows platforms, please edit the fastagent.config.yaml and adjust the volume mount point.")
+            console.print(
+                "On Windows platforms, please edit the fastagent.config.yaml and adjust the volume mount point."
+            )
     else:
         console.print("\n[yellow]No files were created.[/yellow]")
 

mcp_agent/cli/commands/setup.py

@@ -173,7 +173,9 @@ def init(
 
     config_path = Path(config_dir).resolve()
     if not config_path.exists():
-        should_create = Confirm.ask(f"Directory {config_path} does not exist. Create it?", default=True)
+        should_create = Confirm.ask(
+            f"Directory {config_path} does not exist. Create it?", default=True
+        )
         if should_create:
             config_path.mkdir(parents=True)
         else:
@@ -212,9 +214,15 @@ def init(
         console.print("\n[green]Setup completed successfully![/green]")
         if "fastagent.secrets.yaml" in created:
             console.print("\n[yellow]Important:[/yellow] Remember to:")
-            console.print("1. Add your API keys to fastagent-secrets.yaml or set OPENAI_API_KEY and ANTHROPIC_API_KEY environment variables")
-            console.print("2. Keep fastagent.secrets.yaml secure and never commit it to version control")
-            console.print("3. Update fastagent.config.yaml to set a default model (currently system default is 'haiku')")
+            console.print(
+                "1. Add your API keys to fastagent-secrets.yaml or set OPENAI_API_KEY and ANTHROPIC_API_KEY environment variables"
+            )
+            console.print(
+                "2. Keep fastagent.secrets.yaml secure and never commit it to version control"
+            )
+            console.print(
+                "3. Update fastagent.config.yaml to set a default model (currently system default is 'haiku')"
+            )
         console.print("\nTo get started, run:")
         console.print("  uv run agent.py")
     else:

mcp_agent/cli/main.py

@@ -8,7 +8,7 @@ from mcp_agent.cli.commands import bootstrap, setup
 from mcp_agent.cli.terminal import Application
 
 app = typer.Typer(
-    help="MCP Agent CLI - Build effective agents using Model Context Protocol",
+    help="FastAgent CLI - Build effective agents using Model Context Protocol",
     add_completion=False,  # We'll add this later when we have more commands
 )
 

mcp_agent/cli/terminal.py

@@ -14,7 +14,7 @@ class Application:
             self.error_console = error_console
 
     def log(self, message: str, level: str = "info") -> None:
-        if level == "info" or (level == "debug" and self.verbosity > 0):
+        if (level == "info" or (level == "debug" and self.verbosity > 0) or level ==  "error"):
             if level == "error":
                 self.error_console.print(f"[{level.upper()}] {message}")
             else: