fast-agent-mcp 0.1.12__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

@@ -1,16 +1,18 @@
-from typing import Any, Dict, Optional, Type, TypeVar, Callable
-from datetime import timedelta
 import asyncio
 from contextlib import asynccontextmanager
+from datetime import timedelta
+from typing import TYPE_CHECKING, Any, Callable, Dict, Optional, Type, TypeVar
 
-from mcp import ServerSession
-from mcp_agent.context import Context, initialize_context, cleanup_context
 from mcp_agent.config import Settings
+from mcp_agent.context import Context, cleanup_context, initialize_context
 from mcp_agent.event_progress import ProgressAction
-from mcp_agent.logging.logger import get_logger
 from mcp_agent.executor.workflow_signal import SignalWaitCallback
-from mcp_agent.human_input.types import HumanInputCallback
 from mcp_agent.human_input.handler import console_input_callback
+from mcp_agent.human_input.types import HumanInputCallback
+from mcp_agent.logging.logger import get_logger
+
+if TYPE_CHECKING:
+    from mcp import ServerSession
 
 R = TypeVar("R")
 
@@ -43,7 +45,7 @@ class MCPApp:
         human_input_callback: Optional[HumanInputCallback] = console_input_callback,
         signal_notification: Optional[SignalWaitCallback] = None,
         upstream_session: Optional["ServerSession"] = None,
-    ):
+    ) -> None:
         """
         Initialize the application with a name and optional settings.
         Args:
@@ -96,7 +98,7 @@ class MCPApp:
         return self._context.upstream_session
 
     @upstream_session.setter
-    def upstream_session(self, value):
+    def upstream_session(self, value) -> None:
         self._context.upstream_session = value
 
     @property
@@ -113,7 +115,7 @@ class MCPApp:
             self._logger = get_logger(f"mcp_agent.{self.name}")
         return self._logger
 
-    async def initialize(self):
+    async def initialize(self) -> None:
         """Initialize the application."""
         if self._initialized:
             return
@@ -135,7 +137,7 @@ class MCPApp:
             },
         )
 
-    async def cleanup(self):
+    async def cleanup(self) -> None:
         """Cleanup application resources."""
         if not self._initialized:
             return
@@ -173,9 +175,7 @@ class MCPApp:
         finally:
             await self.cleanup()
 
-    def workflow(
-        self, cls: Type, *args, workflow_id: str | None = None, **kwargs
-    ) -> Type:
+    def workflow(self, cls: Type, *args, workflow_id: str | None = None, **kwargs) -> Type:
         """
         Decorator for a workflow class. By default it's a no-op,
         but different executors can use this to customize behavior
@@ -187,9 +187,7 @@ class MCPApp:
         """
         decorator_registry = self.context.decorator_registry
         execution_engine = self.engine
-        workflow_defn_decorator = decorator_registry.get_workflow_defn_decorator(
-            execution_engine
-        )
+        workflow_defn_decorator = decorator_registry.get_workflow_defn_decorator(execution_engine)
 
         if workflow_defn_decorator:
             return workflow_defn_decorator(cls, *args, **kwargs)
@@ -211,9 +209,7 @@ class MCPApp:
 
         decorator_registry = self.context.decorator_registry
         execution_engine = self.engine
-        workflow_run_decorator = decorator_registry.get_workflow_run_decorator(
-            execution_engine
-        )
+        workflow_run_decorator = decorator_registry.get_workflow_run_decorator(execution_engine)
 
         if workflow_run_decorator:
             return workflow_run_decorator(fn)