fast-agent-mcp 0.4.7__py3-none-any.whl

fast_agent/agents/workflow/orchestrator_prompts.py

@@ -0,0 +1,248 @@
+"""
+Prompt templates used by the Orchestrator workflow.
+"""
+
+# Templates for formatting results
+TASK_RESULT_TEMPLATE = """Task: {task_description}
+Result: {task_result}"""
+
+STEP_RESULT_TEMPLATE = """Step: {step_description}
+Step Subtasks:
+{tasks_str}"""
+
+PLAN_RESULT_TEMPLATE = """Plan Objective: {plan_objective}
+
+Progress So Far (steps completed):
+{steps_str}
+
+Result: {plan_result}"""
+
+FULL_PLAN_PROMPT_TEMPLATE = """You are tasked with orchestrating a plan to complete an objective.
+You can analyze results from the previous steps already executed to decide if the objective is complete.
+
+<fastagent:data>
+<fastagent:objective>
+{objective}
+</fastagent:objective>
+
+<fastagent:available-agents>
+{agents}
+</fastagent:available-agents>
+
+<fastagent:progress>
+{plan_result}
+</fastagent:progress>
+
+<fastagent:status>
+{plan_status}
+{iterations_info}
+</fastagent:status>
+</fastagent:data>
+
+Your plan must be structured in sequential steps, with each step containing independent parallel subtasks.
+If the previous results achieve the objective, return is_complete=True.
+Otherwise, generate remaining steps needed.
+
+<fastagent:instruction>
+You are operating in "full plan" mode, where you generate a complete plan with ALL remaining steps needed.
+After receiving your plan, the system will execute ALL steps in your plan before asking for your input again.
+If the plan needs multiple iterations, you'll be called again with updated results.
+
+Generate a plan with all remaining steps needed.
+Steps are sequential, but each Step can have parallel subtasks.
+For each Step, specify a description of the step and independent subtasks that can run in parallel.
+For each subtask specify:
+    1. Clear description of the task that an LLM can execute  
+    2. Name of 1 Agent from the available agents list above
+    
+CRITICAL: You MUST ONLY use agent names that are EXACTLY as they appear in <fastagent:available-agents> above.
+Do NOT invent new agents. Do NOT modify agent names. The plan will FAIL if you use an agent that doesn't exist.
+
+Return your response in the following JSON structure:
+    {{
+        "steps": [
+            {{
+                "description": "Description of step 1",
+                "tasks": [
+                    {{
+                        "description": "Description of task 1",
+                        "agent": "agent_name"  // agent MUST be exactly one of the agent names listed above
+                    }},
+                    {{
+                        "description": "Description of task 2", 
+                        "agent": "agent_name2"  // agent MUST be exactly one of the agent names listed above
+                    }}
+                ]
+            }}
+        ],
+        "is_complete": false
+    }}
+
+Set "is_complete" to true when ANY of these conditions are met:
+1. The objective has been achieved in full or substantively
+2. The remaining work is minor or trivial compared to what's been accomplished
+3. Additional steps provide minimal value toward the core objective
+4. The plan has gathered sufficient information to answer the original request
+
+Be decisive - avoid excessive planning steps that add little value. It's better to complete a plan early than to continue with marginal improvements. Focus on the core intent of the objective, not perfection.
+
+You must respond with valid JSON only, with no triple backticks. No markdown formatting.
+No extra text. Do not wrap in ```json code fences.
+</fastagent:instruction>
+"""
+
+ITERATIVE_PLAN_PROMPT_TEMPLATE = """You are tasked with determining only the next step in a plan
+needed to complete an objective. You must analyze the current state and progress from previous steps 
+to decide what to do next.
+
+<fastagent:data>
+<fastagent:objective>
+{objective}
+</fastagent:objective>
+
+<fastagent:available-agents>
+{agents}
+</fastagent:available-agents>
+
+<fastagent:progress>
+{plan_result}
+</fastagent:progress>
+
+<fastagent:status>
+{plan_status}
+{iterations_info}
+</fastagent:status>
+</fastagent:data>
+
+A Step must be sequential in the plan, but can have independent parallel subtasks. Only return a single Step.
+If the previous results achieve the objective, return is_complete=True.
+Otherwise, generate the next Step.
+
+<fastagent:instruction>
+You are operating in "iterative plan" mode, where you generate ONLY ONE STEP at a time.
+After each step is executed, you'll be called again to determine the next step based on updated results.
+
+Generate the next step, by specifying a description of the step and independent subtasks that can run in parallel:
+For each subtask specify:
+    1. Clear description of the task that an LLM can execute  
+    2. Name of 1 Agent from the available agents list above
+
+CRITICAL: You MUST ONLY use agent names that are EXACTLY as they appear in <fastagent:available-agents> above.
+Do NOT invent new agents. Do NOT modify agent names. The plan will FAIL if you use an agent that doesn't exist.
+
+Return your response in the following JSON structure:
+    {{
+        "description": "Description of step 1",
+        "tasks": [
+            {{
+                "description": "Description of task 1",
+                "agent": "agent_name"  // agent MUST be exactly one of the agent names listed above
+            }}
+        ],
+        "is_complete": false
+    }}
+
+Set "is_complete" to true when ANY of these conditions are met:
+1. The objective has been achieved in full or substantively
+2. The remaining work is minor or trivial compared to what's been accomplished
+3. Additional steps provide minimal value toward the core objective
+4. The plan has gathered sufficient information to answer the original request
+
+Be decisive - avoid excessive planning steps that add little value. It's better to complete a plan early than to continue with marginal improvements. Focus on the core intent of the objective, not perfection.
+
+You must respond with valid JSON only, with no triple backticks. No markdown formatting.
+No extra text. Do not wrap in ```json code fences.
+</fastagent:instruction>
+"""
+
+TASK_PROMPT_TEMPLATE = """You are part of a larger workflow to achieve an objective.
+
+<fastagent:data>
+<fastagent:objective>
+{objective}
+</fastagent:objective>
+
+<fastagent:task>
+{task}
+</fastagent:task>
+
+<fastagent:context>
+{context}
+</fastagent:context>
+</fastagent:data>
+
+<fastagent:instruction>
+Your job is to accomplish only the task specified above.
+Use the context from previous steps to inform your approach.
+The context contains structured XML with the results from previous steps - pay close attention to:
+- The objective in <fastagent:objective>
+- Previous step results in <fastagent:steps>
+- Task results and their attribution in <fastagent:task-result>
+
+Provide a direct, focused response that addresses the task.
+</fastagent:instruction>
+"""
+
+SYNTHESIZE_STEP_PROMPT_TEMPLATE = """You need to synthesize the results of parallel tasks into a cohesive result.
+
+<fastagent:data>
+<fastagent:step-results>
+{step_result}
+</fastagent:step-results>
+</fastagent:data>
+
+<fastagent:instruction>
+Analyze the results from all tasks in this step.
+Each task was executed by a specific agent (finder, writer, etc.)
+Consider the expertise of each agent when weighing their results.
+Combine the information into a coherent, unified response.
+Focus on key insights and important outcomes.
+Resolve any conflicting information if present.
+</fastagent:instruction>
+"""
+
+SYNTHESIZE_PLAN_PROMPT_TEMPLATE = """You need to synthesize the results of all completed plan steps into a final response.
+
+<fastagent:data>
+<fastagent:plan-results>
+{plan_result}
+</fastagent:plan-results>
+</fastagent:data>
+
+<fastagent:instruction>
+Create a comprehensive final response that addresses the original objective.
+Integrate all the information gathered across all plan steps.
+Provide a clear, complete answer that achieves the objective.
+Focus on delivering value through your synthesis, not just summarizing.
+
+If the plan was marked as incomplete but the maximum number of iterations was reached,
+make sure to state clearly what was accomplished and what remains to be done.
+</fastagent:instruction>
+"""
+
+# New template for incomplete plans due to iteration limits
+SYNTHESIZE_INCOMPLETE_PLAN_TEMPLATE = """You need to synthesize the results of all completed plan steps into a final response.
+
+<fastagent:data>
+<fastagent:plan-results>
+{plan_result}
+</fastagent:plan-results>
+</fastagent:data>
+
+<fastagent:status>
+The maximum number of iterations ({max_iterations}) was reached before the objective could be completed.
+</fastagent:status>
+
+<fastagent:instruction>
+Create a comprehensive response that summarizes what was accomplished so far.
+The objective was NOT fully completed due to reaching the maximum number of iterations.
+
+In your response:
+1. Clearly state that the objective was not fully completed
+2. Summarize what WAS accomplished across all the executed steps
+3. Identify what remains to be done to complete the objective
+4. Organize the information to provide maximum value despite being incomplete
+
+Focus on being transparent about the incomplete status while providing as much value as possible.
+</fastagent:instruction>
+"""

fast_agent/agents/workflow/parallel_agent.py

@@ -0,0 +1,250 @@
+import asyncio
+from typing import Any, List, Optional, Tuple
+
+from mcp import Tool
+from mcp.types import TextContent
+from opentelemetry import trace
+
+from fast_agent.agents.agent_types import AgentConfig, AgentType
+from fast_agent.agents.llm_agent import LlmAgent
+from fast_agent.core.logging.logger import get_logger
+from fast_agent.interfaces import AgentProtocol, ModelT
+from fast_agent.types import PromptMessageExtended, RequestParams
+
+logger = get_logger(__name__)
+
+
+class ParallelAgent(LlmAgent):
+    """
+    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.
+    """
+
+    @property
+    def agent_type(self) -> AgentType:
+        """Return the type of this agent."""
+        return AgentType.PARALLEL
+
+    def __init__(
+        self,
+        config: AgentConfig,
+        fan_in_agent: AgentProtocol,
+        fan_out_agents: List[AgentProtocol],
+        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_impl(
+        self,
+        messages: List[PromptMessageExtended],
+        request_params: Optional[RequestParams] = None,
+        tools: List[Tool] | None = None,
+    ) -> PromptMessageExtended:
+        """
+        Execute fan-out agents in parallel and aggregate their results with the fan-in agent.
+
+        Args:
+            normalized_messages: Already normalized list of PromptMessageExtended
+            request_params: Optional parameters to configure the request
+
+        Returns:
+            The aggregated response from the fan-in agent
+        """
+
+        tracer = trace.get_tracer(__name__)
+        with tracer.start_as_current_span(f"Parallel: '{self._name}' generate"):
+            responses: List[PromptMessageExtended] = await self._execute_fan_out(
+                messages, request_params
+            )
+
+            # Extract the received message from the input
+            received_message: Optional[str] = messages[-1].all_text() if 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 = PromptMessageExtended(
+                role="user", content=[TextContent(type="text", text=aggregated_prompt)]
+            )
+
+            # Use the fan-in agent to aggregate the responses
+            return await self._fan_in_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_impl(
+        self,
+        messages: List[PromptMessageExtended],
+        model: type[ModelT],
+        request_params: Optional[RequestParams] = None,
+    ) -> Tuple[ModelT | None, PromptMessageExtended]:
+        """
+        Apply the prompt and return the result as a Pydantic model.
+
+        This implementation delegates to the fan-in agent's structured method.
+
+        Args:
+            messages: List of PromptMessageExtended 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
+        """
+
+        tracer = trace.get_tracer(__name__)
+        with tracer.start_as_current_span(f"Parallel: '{self._name}' generate"):
+            responses: List[PromptMessageExtended] = await self._execute_fan_out(
+                messages, request_params
+            )
+
+            # Extract the received message
+            received_message: Optional[str] = messages[-1].all_text() if messages 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 = PromptMessageExtended(
+                role="user", content=[TextContent(type="text", text=aggregated_prompt)]
+            )
+
+            # Use the fan-in agent to parse the structured output
+            return await self._fan_in_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 self.fan_in_agent.initialized:
+            await self.fan_in_agent.initialize()
+
+        for agent in self.fan_out_agents:
+            if not agent.initialized:
+                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:
+            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:
+                logger.warning(f"Error shutting down fan-out agent {agent.name}: {str(e)}")
+
+    async def _execute_fan_out(
+        self,
+        messages: List[PromptMessageExtended],
+        request_params: Optional[RequestParams],
+    ) -> List[PromptMessageExtended]:
+        """
+        Run fan-out agents with telemetry so transports can surface progress.
+        """
+
+        async def _run_agent(agent: AgentProtocol) -> PromptMessageExtended:
+            async with self.workflow_telemetry.start_step(
+                "parallel.fan_out",
+                server_name=self.name,
+                arguments={"agent": agent.name},
+            ) as step:
+                result = await agent.generate(messages, request_params)
+                await step.finish(True, text=f"{agent.name} completed fan-out work")
+                return result
+
+        return await asyncio.gather(*[_run_agent(agent) for agent in self.fan_out_agents])
+
+    async def _fan_in_generate(
+        self,
+        prompt: PromptMessageExtended,
+        request_params: Optional[RequestParams],
+    ) -> PromptMessageExtended:
+        """
+        Aggregate fan-out output with telemetry.
+        """
+        async with self.workflow_telemetry.start_step(
+            "parallel.fan_in",
+            server_name=self.name,
+            arguments={"agent": self.fan_in_agent.name},
+        ) as step:
+            result = await self.fan_in_agent.generate([prompt], request_params)
+            await step.finish(True, text=f"{self.fan_in_agent.name} aggregated results")
+            return result
+
+    async def _fan_in_structured(
+        self,
+        prompt: PromptMessageExtended,
+        model: type[ModelT],
+        request_params: Optional[RequestParams],
+    ) -> Tuple[ModelT | None, PromptMessageExtended]:
+        """
+        Structured aggregation with telemetry.
+        """
+        async with self.workflow_telemetry.start_step(
+            "parallel.fan_in_structured",
+            server_name=self.name,
+            arguments={"agent": self.fan_in_agent.name},
+        ) as step:
+            result = await self.fan_in_agent.structured([prompt], model, request_params)
+            await step.finish(True, text=f"{self.fan_in_agent.name} produced structured output")
+            return result