fast-agent-mcp 0.0.15__py3-none-any.whl → 0.1.0__py3-none-any.whl

mcp_agent/workflows/evaluator_optimizer/evaluator_optimizer.py

@@ -10,7 +10,7 @@ from mcp_agent.workflows.llm.augmented_llm import (
     ModelT,
     RequestParams,
 )
-from mcp_agent.agents.agent import Agent
+from mcp_agent.agents.agent import Agent, AgentConfig
 from mcp_agent.logging.logger import get_logger
 
 if TYPE_CHECKING:
@@ -64,6 +64,25 @@ class EvaluatorOptimizerLLM(AugmentedLLM[MessageParamT, MessageT]):
     - Document writing requiring multiple revisions
     """
 
+    def _initialize_default_params(self, kwargs: dict) -> RequestParams:
+        """Initialize default parameters using the workflow's settings."""
+        return RequestParams(
+            modelPreferences=self.model_preferences,
+            systemPrompt=self.instruction,
+            parallel_tool_calls=True,
+            max_iterations=10,
+            use_history=self.generator_use_history,  # Use generator's history setting
+        )
+
+    def _init_request_params(self):
+        """Initialize request parameters for both generator and evaluator components."""
+        # Set up workflow's default params based on generator's history setting
+        self.default_request_params = self._initialize_default_params({})
+
+        # Ensure evaluator's request params have history disabled
+        if hasattr(self.evaluator_llm, "default_request_params"):
+            self.evaluator_llm.default_request_params.use_history = False
+
     def __init__(
         self,
         generator: Agent | AugmentedLLM,
@@ -73,6 +92,8 @@ class EvaluatorOptimizerLLM(AugmentedLLM[MessageParamT, MessageT]):
         llm_factory: Callable[[Agent], AugmentedLLM]
         | None = None,  # TODO: Remove legacy - factory should only be needed for str evaluator
         context: Optional["Context"] = None,
+        name: Optional[str] = None,  # Allow overriding the name
+        instruction: Optional[str] = None,  # Allow overriding the instruction
     ):
         """
         Initialize the evaluator-optimizer workflow.
@@ -87,16 +108,50 @@ class EvaluatorOptimizerLLM(AugmentedLLM[MessageParamT, MessageT]):
             min_rating: Minimum acceptable quality rating
             max_refinements: Maximum refinement iterations
             llm_factory: Optional factory to create LLMs from agents
+            name: Optional name for the workflow (defaults to generator's name)
+            instruction: Optional instruction (defaults to generator's instruction)
+
+        Note on History Management:
+            This workflow manages two distinct history contexts:
+            1. Generator History: Controlled by the generator's use_history setting. When False,
+               each refinement iteration starts fresh without previous context.
+            2. Evaluator History: Always disabled as each evaluation should be independent
+               and based solely on the current response.
         """
-        super().__init__(context=context)
-
-        # Set up the optimizer
-        self.name = generator.name
+        # Set up initial instance attributes - allow name override
+        self.name = name or generator.name
         self.llm_factory = llm_factory
         self.generator = generator
         self.evaluator = evaluator
+        self.min_rating = min_rating
+        self.max_refinements = max_refinements
+
+        # Determine generator's history setting before super().__init__
+        if isinstance(generator, Agent):
+            self.generator_use_history = generator.config.use_history
+        elif isinstance(generator, AugmentedLLM):
+            if hasattr(generator, "aggregator") and isinstance(
+                generator.aggregator, Agent
+            ):
+                self.generator_use_history = generator.aggregator.config.use_history
+            else:
+                self.generator_use_history = getattr(
+                    generator,
+                    "use_history",
+                    getattr(generator.default_request_params, "use_history", False),
+                )
+        else:
+            raise ValueError(f"Unsupported optimizer type: {type(generator)}")
+
+        # Now we can call super().__init__ which will use generator_use_history
+        super().__init__(context=context, name=name or generator.name)
 
-        # TODO: Remove legacy - optimizer should always be an AugmentedLLM, no conversion needed
+        # Add a PassthroughLLM as _llm property for compatibility with Orchestrator
+        from mcp_agent.workflows.llm.augmented_llm import PassthroughLLM
+
+        self._llm = PassthroughLLM(name=f"{self.name}_passthrough", context=context)
+
+        # Set up the generator
         if isinstance(generator, Agent):
             if not llm_factory:
                 raise ValueError("llm_factory is required when using an Agent")
@@ -109,9 +164,12 @@ class EvaluatorOptimizerLLM(AugmentedLLM[MessageParamT, MessageT]):
 
             self.aggregator = generator
             self.instruction = (
-                generator.instruction
-                if isinstance(generator.instruction, str)
-                else None
+                instruction  # Use provided instruction if any
+                or (
+                    generator.instruction
+                    if isinstance(generator.instruction, str)
+                    else None
+                )  # Fallback to generator's
             )
 
         elif isinstance(generator, AugmentedLLM):
@@ -119,46 +177,58 @@ class EvaluatorOptimizerLLM(AugmentedLLM[MessageParamT, MessageT]):
             self.aggregator = generator.aggregator
             self.instruction = generator.instruction
 
-        else:
-            raise ValueError(f"Unsupported optimizer type: {type(generator)}")
-
-        self.history = self.generator_llm.history
-
-        # Set up the evaluator
+        # Set up the evaluator - evaluations should be independent, so history is always disabled
         if isinstance(evaluator, AugmentedLLM):
             self.evaluator_llm = evaluator
-        # TODO: Remove legacy - evaluator should be either AugmentedLLM or str
+            # Override evaluator's history setting
+            if hasattr(evaluator, "default_request_params"):
+                evaluator.default_request_params.use_history = False
         elif isinstance(evaluator, Agent):
             if not llm_factory:
                 raise ValueError(
                     "llm_factory is required when using an Agent evaluator"
                 )
 
-            # Only create new LLM if agent doesn't have one
+            # Create evaluator with history disabled
             if hasattr(evaluator, "_llm") and evaluator._llm:
                 self.evaluator_llm = evaluator._llm
+                if hasattr(self.evaluator_llm, "default_request_params"):
+                    self.evaluator_llm.default_request_params.use_history = False
             else:
+                # Force history off in config before creating LLM
+                evaluator.config.use_history = False
                 self.evaluator_llm = llm_factory(agent=evaluator)
         elif isinstance(evaluator, str):
-            # If a string is passed as the evaluator, we use it as the evaluation criteria
-            # and create an evaluator agent with that instruction
             if not llm_factory:
                 raise ValueError(
                     "llm_factory is required when using a string evaluator"
                 )
 
-            self.evaluator_llm = llm_factory(
-                agent=Agent(name="Evaluator", instruction=evaluator)
+            # Create evaluator agent with history disabled
+            evaluator_agent = Agent(
+                name="Evaluator",
+                instruction=evaluator,
+                config=AgentConfig(
+                    name="Evaluator",
+                    instruction=evaluator,
+                    servers=[],
+                    use_history=False,  # Force history off for evaluator
+                ),
             )
+            self.evaluator_llm = llm_factory(agent=evaluator_agent)
         else:
             raise ValueError(f"Unsupported evaluator type: {type(evaluator)}")
 
-        self.min_rating = min_rating
-        self.max_refinements = max_refinements
-
-        # Track iteration history
+        # Track iteration history (for the workflow itself)
         self.refinement_history = []
 
+        # Set up workflow's default params based on generator's history setting
+        self.default_request_params = self._initialize_default_params({})
+
+        # Ensure evaluator's request params have history disabled
+        if hasattr(self.evaluator_llm, "default_request_params"):
+            self.evaluator_llm.default_request_params.use_history = False
+
     async def generate(
         self,
         message: str | MessageParamT | List[MessageParamT],
@@ -171,6 +241,9 @@ class EvaluatorOptimizerLLM(AugmentedLLM[MessageParamT, MessageT]):
         best_rating = QualityRating.POOR
         self.refinement_history = []
 
+        # Get request params with proper use_history setting
+        params = self.get_request_params(request_params)
+
         # 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
@@ -180,22 +253,20 @@ class EvaluatorOptimizerLLM(AugmentedLLM[MessageParamT, MessageT]):
                 await stack.enter_async_context(self.evaluator)
 
             # Initial generation
-            response = await self.generator_llm.generate(
+            response = await self.generator_llm.generate_str(
                 message=message,
-                request_params=request_params,
+                request_params=params,  # Pass params which may override use_history
             )
 
             best_response = response
 
             while refinement_count < self.max_refinements:
-                logger.debug("Optimizer result:", data=response)
+                logger.debug("Generator 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),
+                    current_response=response,  # response is already a string
                     iteration=refinement_count,
                 )
 
@@ -244,22 +315,23 @@ class EvaluatorOptimizerLLM(AugmentedLLM[MessageParamT, MessageT]):
                 # 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),
+                    current_response=response,
                     feedback=evaluation_result,
                     iteration=refinement_count,
+                    use_history=self.generator_use_history,  # Use the generator's history setting
                 )
 
-                # No nested AsyncExitStack here either
-                response = await self.generator_llm.generate(
+                response = await self.generator_llm.generate_str(
                     message=refinement_prompt,
-                    request_params=request_params,
+                    request_params=params,  # Pass params which may override use_history
                 )
 
                 refinement_count += 1
 
-            return best_response
+            # Return the best response as a list with a single string element
+            # This makes it consistent with other AugmentedLLM implementations
+            # that return List[MessageT]
+            return [best_response]
 
     async def generate_str(
         self,
@@ -271,28 +343,8 @@ class EvaluatorOptimizerLLM(AugmentedLLM[MessageParamT, MessageT]):
             message=message,
             request_params=request_params,
         )
-
-        # Handle case where response is a single message
-        if not isinstance(response, list):
-            return str(response)
-
-        # Convert all messages to strings, handling different message types
-        result_strings = []
-        for r in response:
-            if hasattr(r, "text"):
-                result_strings.append(r.text)
-            elif hasattr(r, "content"):
-                # Handle ToolUseBlock and similar
-                if isinstance(r.content, list):
-                    # Typically content is a list of blocks
-                    result_strings.extend(str(block) for block in r.content)
-                else:
-                    result_strings.append(str(r.content))
-            else:
-                # Fallback to string representation
-                result_strings.append(str(r))
-
-        return "\n".join(result_strings)
+        # Since generate now returns [best_response], just return the first element
+        return str(response[0])
 
     async def generate_structured(
         self,
@@ -316,23 +368,50 @@ class EvaluatorOptimizerLLM(AugmentedLLM[MessageParamT, MessageT]):
     ) -> str:
         """Build the evaluation prompt for the evaluator"""
         return f"""
-        Evaluate the following response based on these criteria:
-        {self.evaluator.instruction}
-
-        Original Request: {original_request}
-        Current Response (Iteration {iteration + 1}): {current_response}
-
-        Provide your evaluation as a structured response with:
-        1. A quality rating (EXCELLENT, GOOD, FAIR, or POOR)
-        2. Specific feedback and suggestions
-        3. Whether improvement is needed (true/false)
-        4. Focus areas for improvement
-
-        Rate as EXCELLENT only if no improvements are needed.
-        Rate as GOOD if only minor improvements are possible.
-        Rate as FAIR if several improvements are needed.
-        Rate as POOR if major improvements are needed.
-        """
+You are an expert evaluator for content quality. Your task is to evaluate a response against the user's original request.
+
+Evaluate the response for iteration {iteration + 1} and provide structured feedback on its quality and areas for improvement.
+
+<fastagent:data>
+<fastagent:request>
+{original_request}
+</fastagent:request>
+
+<fastagent:response>
+{current_response}
+</fastagent:response>
+
+<fastagent:evaluation-criteria>
+{self.evaluator.instruction}
+</fastagent:evaluation-criteria>
+</fastagent:data>
+
+<fastagent:instruction>
+Provide a structured evaluation with the following components:
+
+<rating>
+Choose one: EXCELLENT, GOOD, FAIR, or POOR
+- EXCELLENT: No improvements needed
+- GOOD: Only minor improvements possible
+- FAIR: Several improvements needed
+- POOR: Major improvements needed
+</rating>
+
+<details>
+Provide specific, actionable feedback and suggestions for improvement.
+Be precise about what works well and what could be improved.
+</details>
+
+<needs_improvement>
+Indicate true/false whether further improvement is needed.
+</needs_improvement>
+
+<focus-areas>
+List 1-3 specific areas to focus on in the next iteration.
+Be concrete and actionable in your recommendations.
+</focus-areas>
+</fastagent:instruction>
+"""
 
     def _build_refinement_prompt(
         self,
@@ -340,19 +419,78 @@ class EvaluatorOptimizerLLM(AugmentedLLM[MessageParamT, MessageT]):
         current_response: str,
         feedback: EvaluationResult,
         iteration: int,
+        use_history: bool = None,
     ) -> str:
         """Build the refinement prompt for the optimizer"""
-        return f"""
-        Improve your previous response based on the evaluation feedback.
-        
-        Original Request: {original_request}
-        
-        Previous Response (Iteration {iteration + 1}): 
-        {current_response}
-        
-        Quality Rating: {feedback.rating}
-        Feedback: {feedback.feedback}
-        Areas to Focus On: {", ".join(feedback.focus_areas)}
-        
-        Generate an improved version addressing the feedback while maintaining accuracy and relevance.
-        """
+        # Get the correct history setting - use param if provided, otherwise class default
+        if use_history is None:
+            use_history = (
+                self.generator_use_history
+            )  # Use generator's setting as default
+
+        # Start with clear non-delimited instructions
+        prompt = f"""
+You are tasked with improving a response based on expert feedback. This is iteration {iteration + 1} of the refinement process.
+
+Your goal is to address all feedback points while maintaining accuracy and relevance to the original request.
+"""
+
+        # Add data section with all relevant information
+        prompt += """
+<fastagent:data>
+"""
+
+        # Add request
+        prompt += f"""
+<fastagent:request>
+{original_request}
+</fastagent:request>
+"""
+
+        # Only include previous response if history is not enabled
+        if not use_history:
+            prompt += f"""
+<fastagent:previous-response>
+{current_response}
+</fastagent:previous-response>
+"""
+
+        # Always include the feedback
+        prompt += f"""
+<fastagent:feedback>
+<rating>{feedback.rating}</rating>
+<details>{feedback.feedback}</details>
+<focus-areas>{", ".join(feedback.focus_areas) if feedback.focus_areas else "None specified"}</focus-areas>
+</fastagent:feedback>
+</fastagent:data>
+"""
+
+        # Customize instruction based on history availability
+        if not use_history:
+            prompt += """
+<fastagent:instruction>
+Create an improved version of the response that:
+1. Directly addresses each point in the feedback
+2. Focuses on the specific areas mentioned for improvement
+3. Maintains all the strengths of the original response
+4. Remains accurate and relevant to the original request
+
+Provide your complete improved response without explanations or commentary.
+</fastagent:instruction>
+"""
+        else:
+            prompt += """
+<fastagent:instruction>
+Your previous response is available in your conversation history.
+
+Create an improved version that:
+1. Directly addresses each point in the feedback
+2. Focuses on the specific areas mentioned for improvement
+3. Maintains all the strengths of your original response
+4. Remains accurate and relevant to the original request
+
+Provide your complete improved response without explanations or commentary.
+</fastagent:instruction>
+"""
+
+        return prompt

mcp_agent/workflows/llm/augmented_llm_anthropic.py

@@ -117,10 +117,11 @@ class AnthropicAugmentedLLM(AugmentedLLM[MessageParam, Message]):
         responses: List[Message] = []
         model = await self.select_model(params)
         chat_turn = (len(messages) + 1) // 2
-        self._log_chat_progress(chat_turn, model=model)
         self.show_user_message(str(message), model, chat_turn)
 
         for i in range(params.max_iterations):
+            chat_turn = (len(messages) + 1) // 2
+            self._log_chat_progress(chat_turn, model=model)
             arguments = {
                 "model": model,
                 "messages": messages,
@@ -208,10 +209,23 @@ class AnthropicAugmentedLLM(AugmentedLLM[MessageParam, Message]):
                 break
             elif response.stop_reason == "max_tokens":
                 # We have reached the max tokens limit
+
                 self.logger.debug(
                     f"Iteration {i}: Stopping because finish_reason is 'max_tokens'"
                 )
-                # TODO: saqadri - would be useful to return the reason for stopping to the caller
+                if params.maxTokens is not None:
+                    message_text = Text(
+                        f"the assistant has reached the maximum token limit ({params.maxTokens})",
+                        style="dim green italic",
+                    )
+                else:
+                    message_text = Text(
+                        "the assistant has reached the maximum token limit",
+                        style="dim green italic",
+                    )
+
+                await self.show_assistant_message(message_text)
+
                 break
             else:
                 message_text = ""

mcp_agent/workflows/llm/augmented_llm_openai.py

@@ -254,7 +254,7 @@ class OpenAIAugmentedLLM(
                         message_text,
                         message.tool_calls[
                             0
-                        ].function.name,  # TODO support multiple tool calls
+                        ].function.name,  # TODO support displaying multiple tool calls
                     )
                 else:
                     await self.show_assistant_message(
@@ -294,6 +294,18 @@ class OpenAIAugmentedLLM(
                 self.logger.debug(
                     f"Iteration {i}: Stopping because finish_reason is 'length'"
                 )
+                if request_params and request_params.maxTokens is not None:
+                    message_text = Text(
+                        f"the assistant has reached the maximum token limit ({request_params.maxTokens})",
+                        style="dim green italic",
+                    )
+                else:
+                    message_text = Text(
+                        "the assistant has reached the maximum token limit",
+                        style="dim green italic",
+                    )
+
+                await self.show_assistant_message(message_text)
                 # TODO: saqadri - would be useful to return the reason for stopping to the caller
                 break
             elif choice.finish_reason == "content_filter":

mcp_agent/workflows/llm/prompt_utils.py

@@ -0,0 +1,137 @@
+"""
+XML formatting utilities for consistent prompt engineering across components.
+"""
+
+from typing import Dict, List, Optional, Union
+
+
+def format_xml_tag(tag_name: str, content: Optional[str] = None, 
+                 attributes: Optional[Dict[str, str]] = None) -> str:
+    """
+    Format an XML tag with optional content and attributes.
+    Uses self-closing tag when content is None or empty.
+
+    Args:
+        tag_name: Name of the XML tag
+        content: Content to include inside the tag (None for self-closing)
+        attributes: Dictionary of attribute name-value pairs
+
+    Returns:
+        Formatted XML tag as string
+    """
+    # Format attributes if provided
+    attrs_str = ""
+    if attributes:
+        attrs_str = " " + " ".join(f'{k}="{v}"' for k, v in attributes.items())
+    
+    # Use self-closing tag if no content
+    if content is None or content == "":
+        return f"<{tag_name}{attrs_str} />"
+    
+    # Full tag with content
+    return f"<{tag_name}{attrs_str}>{content}</{tag_name}>"
+
+
+def format_fastagent_tag(tag_type: str, content: Optional[str] = None, 
+                        attributes: Optional[Dict[str, str]] = None) -> str:
+    """
+    Format a fastagent-namespaced XML tag with consistent formatting.
+    
+    Args:
+        tag_type: Type of fastagent tag (without namespace prefix)
+        content: Content to include inside the tag
+        attributes: Dictionary of attribute name-value pairs
+        
+    Returns:
+        Formatted fastagent XML tag as string
+    """
+    return format_xml_tag(f"fastagent:{tag_type}", content, attributes)
+
+
+def format_server_info(server_name: str, description: Optional[str] = None, 
+                      tools: Optional[List[Dict[str, str]]] = None) -> str:
+    """
+    Format server information consistently across router and orchestrator modules.
+    
+    Args:
+        server_name: Name of the server
+        description: Optional server description
+        tools: Optional list of tool dictionaries with 'name' and 'description' keys
+        
+    Returns:
+        Formatted server XML as string
+    """
+    # Use self-closing tag if no description or tools
+    if not description and not tools:
+        return format_fastagent_tag("server", None, {"name": server_name})
+    
+    # Start building components
+    components = []
+    
+    # Add description if present
+    if description:
+        desc_tag = format_fastagent_tag("description", description)
+        components.append(desc_tag)
+    
+    # Add tools section if tools exist
+    if tools and len(tools) > 0:
+        tool_tags = []
+        for tool in tools:
+            tool_name = tool.get("name", "")
+            tool_desc = tool.get("description", "")
+            tool_tag = format_fastagent_tag("tool", tool_desc, {"name": tool_name})
+            tool_tags.append(tool_tag)
+        
+        tools_content = "\n".join(tool_tags)
+        tools_tag = format_fastagent_tag("tools", f"\n{tools_content}\n")
+        components.append(tools_tag)
+    
+    # Combine all components
+    server_content = "\n".join(components)
+    return format_fastagent_tag("server", f"\n{server_content}\n", {"name": server_name})
+
+
+def format_agent_info(agent_name: str, description: Optional[str] = None, 
+                     servers: Optional[List[Dict[str, Union[str, List[Dict[str, str]]]]]] = None) -> str:
+    """
+    Format agent information consistently across router and orchestrator modules.
+    
+    Args:
+        agent_name: Name of the agent
+        description: Optional agent description/instruction
+        servers: Optional list of server dictionaries with 'name', 'description', and 'tools' keys
+        
+    Returns:
+        Formatted agent XML as string
+    """
+    # Start building components
+    components = []
+    
+    # Add description if present
+    if description:
+        desc_tag = format_fastagent_tag("description", description)
+        components.append(desc_tag)
+    
+    # If no description or servers, use self-closing tag
+    if not description and not servers:
+        return format_fastagent_tag("agent", None, {"name": agent_name})
+        
+    # If has servers, format them
+    if servers and len(servers) > 0:
+        server_tags = []
+        for server in servers:
+            server_name = server.get("name", "")
+            server_desc = server.get("description", "")
+            server_tools = server.get("tools", [])
+            server_tag = format_server_info(server_name, server_desc, server_tools)
+            server_tags.append(server_tag)
+        
+        # Only add servers section if we have servers
+        if server_tags:
+            servers_content = "\n".join(server_tags)
+            servers_tag = format_fastagent_tag("servers", f"\n{servers_content}\n")
+            components.append(servers_tag)
+    
+    # Combine all components
+    agent_content = "\n".join(components)
+    return format_fastagent_tag("agent", f"\n{agent_content}\n", {"name": agent_name})