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

mcp_agent/resources/examples/data-analysis/analysis-campaign.py

@@ -0,0 +1,188 @@
+import asyncio
+
+from mcp_agent.core.fastagent import FastAgent
+from mcp_agent.workflows.llm.augmented_llm import RequestParams
+
+# Create the application
+fast = FastAgent("Data Analysis & Campaign Generator")
+
+
+# Original data analysis components
+@fast.agent(
+    name="data_analysis",
+    instruction="""
+You have access to a Python 3.12 interpreter and you can use this to analyse and process data. 
+Common analysis packages such as Pandas, Seaborn and Matplotlib are already installed. 
+You can add further packages if needed.
+Data files are accessible from the /mnt/data/ directory (this is the current working directory).
+Visualisations should be saved as .png files in the current working directory.
+Extract key insights that would be compelling for a social media campaign.
+""",
+    servers=["interpreter"],
+    request_params=RequestParams(maxTokens=8192),
+    model="sonnet",
+)
+@fast.agent(
+    "evaluator",
+    """You are collaborating with a Data Analysis tool that has the capability to analyse data and produce visualisations.
+    You must make sure that the tool has:
+     - Considered the best way for a Human to interpret the data
+     - Produced insightful visualisations.
+     - Provided a high level summary report for the Human.
+     - Has had its findings challenged, and justified
+     - Extracted compelling insights suitable for social media promotion
+    """,
+    request_params=RequestParams(maxTokens=8192),
+    model="gpt-4o",
+)
+@fast.evaluator_optimizer(
+    "analysis_tool",
+    generator="data_analysis",
+    evaluator="evaluator",
+    max_refinements=3,
+    min_rating="EXCELLENT",
+)
+# Research component using Brave search
+@fast.agent(
+    "context_researcher",
+    """You are a research specialist who provides cultural context for different regions.
+    For any given data insight and target language/region, research:
+    1. Cultural sensitivities related to presenting this type of data
+    2. Local social media trends and preferences
+    3. Region-specific considerations for marketing campaigns
+    
+    Always provide actionable recommendations for adapting content to each culture.
+    """,
+    servers=["fetch", "brave"],  # Using the fetch MCP server for Brave search
+    request_params=RequestParams(temperature=0.3),
+    model="gpt-4o",
+)
+# Social media content generator
+@fast.agent(
+    "campaign_generator",
+    """Generate engaging social media content based on data insights.
+    Create compelling, shareable content that:
+    - Highlights key research findings in an accessible way
+    - Uses appropriate tone for the platform (Twitter/X, LinkedIn, Instagram, etc.)
+    - Is concise and impactful
+    - Includes suggested hashtags and posting schedule
+    
+    Format your response with clear sections for each platform.
+    Save different campaign elements as separate files in the current directory.
+    """,
+    servers=["filesystem"],  # Using filesystem MCP server to save files
+    request_params=RequestParams(temperature=0.7),
+    model="sonnet",
+    use_history=False,
+)
+# Translation agents with cultural adaptation
+@fast.agent(
+    "translate_fr",
+    """Translate social media content to French with cultural adaptation.
+    Consider French cultural norms, expressions, and social media preferences.
+    Ensure the translation maintains the impact of the original while being culturally appropriate.
+    Save the translated content to a file with appropriate naming.
+    """,
+    model="haiku",
+    use_history=False,
+    servers=["filesystem"],
+)
+@fast.agent(
+    "translate_es",
+    """Translate social media content to Spanish with cultural adaptation.
+    Consider Spanish-speaking cultural contexts, expressions, and social media preferences.
+    Ensure the translation maintains the impact of the original while being culturally appropriate.
+    Save the translated content to a file with appropriate naming.
+    """,
+    model="haiku",
+    use_history=False,
+    servers=["filesystem"],
+)
+@fast.agent(
+    "translate_de",
+    """Translate social media content to German with cultural adaptation.
+    Consider German cultural norms, expressions, and social media preferences.
+    Ensure the translation maintains the impact of the original while being culturally appropriate.
+    Save the translated content to a file with appropriate naming.
+    """,
+    model="haiku",
+    use_history=False,
+    servers=["filesystem"],
+)
+@fast.agent(
+    "translate_ja",
+    """Translate social media content to Japanese with cultural adaptation.
+    Consider Japanese cultural norms, expressions, and social media preferences.
+    Ensure the translation maintains the impact of the original while being culturally appropriate.
+    Save the translated content to a file with appropriate naming.
+    """,
+    model="haiku",
+    use_history=False,
+    servers=["filesystem"],
+)
+# Parallel workflow for translations
+@fast.parallel(
+    "translate_campaign",
+    instruction="Translates content to French, Spanish, German and Japanese. Supply the content to translate, translations will be saved to the filesystem.",
+    fan_out=["translate_fr", "translate_es", "translate_de", "translate_ja"],
+    include_request=True,
+)
+# Cultural sensitivity review agent
+@fast.agent(
+    "cultural_reviewer",
+    """Review all translated content for cultural sensitivity and appropriateness.
+    For each language version, evaluate:
+    - Cultural appropriateness
+    - Potential misunderstandings or sensitivities
+    - Effectiveness for the target culture
+    
+    Provide specific recommendations for any needed adjustments and save a review report.
+    """,
+    servers=["filesystem"],
+    request_params=RequestParams(temperature=0.2),
+)
+# Campaign optimization workflow
+@fast.evaluator_optimizer(
+    "campaign_optimizer",
+    generator="campaign_generator",
+    evaluator="cultural_reviewer",
+    max_refinements=2,
+    min_rating="EXCELLENT",
+)
+# Main workflow orchestration
+@fast.orchestrator(
+    "research_campaign_creator",
+    instruction="""
+    Create a complete multi-lingual social media campaign based on data analysis results.
+    The workflow will:
+    1. Analyze the provided data and extract key insights
+    2. Research cultural contexts for target languages
+    3. Generate appropriate social media content
+    4. Translate and culturally adapt the content
+    5. Review and optimize all materials
+    6. Save all campaign elements to files
+    """,
+    agents=[
+        "analysis_tool",
+        "context_researcher",
+        "campaign_optimizer",
+        "translate_campaign",
+    ],
+    model="sonnet",  # Using a more capable model for orchestration
+    request_params=RequestParams(maxTokens=8192),
+    plan_type="full",
+)
+async def main():
+    # Use the app's context manager
+    print(
+        "WARNING: This workflow will likely run for >10 minutes and consume a lot of tokens. Press Enter to accept the default prompt and proceed"
+    )
+
+    async with fast.run() as agent:
+        await agent.research_campaign_creator.prompt(
+            default_prompt="Analyze the CSV file in the current directory and create a comprehensive multi-lingual social media campaign based on the findings. Save all campaign elements as separate files."
+        )
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

mcp_agent/resources/examples/data-analysis/analysis.py

@@ -19,43 +19,43 @@ Visualisations should be saved as .png files in the current working directory.
     servers=["interpreter"],
     request_params=RequestParams(maxTokens=8192),
 )
-@fast.agent(
-    "evaluator",
-    """You are collaborating with a Data Analysis tool that has the capability to analyse data and produce visualisations.
-    You must make sure that the tool has:
-     - Considered the best way for a Human to interpret the data
-     - Produced insightful visualasions.
-     - Provided a high level summary report for the Human.
-     - Has had its findings challenged, and justified
-    """,
-    request_params=RequestParams(maxTokens=8192),
-)
-@fast.evaluator_optimizer(
-    "analysis_tool",
-    generator="data_analysis",
-    evaluator="evaluator",
-    max_refinements=3,
-    min_rating="EXCELLENT",
-)
-@fast.passthrough(
-    "sample",
-)
 async def main():
     # Use the app's context manager
     async with fast.run() as agent:
-        # await agent(
-        #     "There is a csv file in the current directory. "
-        #     "Analyse the file, produce a detailed description of the data, and any patterns it contains.",
-        # )
-        # await agent(
-        #     "Consider the data, and how to usefully group it for presentation to a Human. Find insights, using the Python Interpreter as needed.\n"
-        #     "Use MatPlotLib to produce insightful visualisations. Save them as '.png' files in the current directory. Be sure to run the code and save the files.\n"
-        #     "Produce a summary with major insights to the data",
-        # )
-        await agent.analysis_tool.prompt(
-            "Analyse the CSV File in the working directory"
+        await agent(
+            "There is a csv file in the current directory. "
+            "Analyse the file, produce a detailed description of the data, and any patterns it contains.",
+        )
+        await agent(
+            "Consider the data, and how to usefully group it for presentation to a Human. Find insights, using the Python Interpreter as needed.\n"
+            "Use MatPlotLib to produce insightful visualisations. Save them as '.png' files in the current directory. Be sure to run the code and save the files.\n"
+            "Produce a summary with major insights to the data",
         )
+        await agent()
 
 
 if __name__ == "__main__":
     asyncio.run(main())
+
+
+############################################################################################################
+# Example of evaluator/optimizer flow
+############################################################################################################
+# @fast.agent(
+#     "evaluator",
+#     """You are collaborating with a Data Analysis tool that has the capability to analyse data and produce visualisations.
+#     You must make sure that the tool has:
+#      - Considered the best way for a Human to interpret the data
+#      - Produced insightful visualasions.
+#      - Provided a high level summary report for the Human.
+#      - Has had its findings challenged, and justified
+#     """,
+#     request_params=RequestParams(maxTokens=8192),
+# )
+# @fast.evaluator_optimizer(
+#     "analysis_tool",
+#     generator="data_analysis",
+#     evaluator="evaluator",
+#     max_refinements=3,
+#     min_rating="EXCELLENT",
+# )

mcp_agent/resources/examples/workflows/evaluator.py

@@ -17,7 +17,8 @@ fast = FastAgent("Evaluator-Optimizer")
     candidate details, and company information. Tailor the response to the company and job requirements.
     """,
     servers=["fetch"],
-    model="gpt-4o-mini",
+    model="haiku3",
+    use_history=True,
 )
 # Define evaluator agent
 @fast.agent(
@@ -38,6 +39,7 @@ fast = FastAgent("Evaluator-Optimizer")
     Summarize your evaluation as a structured response with:
     - Overall quality rating.
     - Specific feedback and areas for improvement.""",
+    model="gpt-4o",
 )
 # Define the evaluator-optimizer workflow
 @fast.evaluator_optimizer(

mcp_agent/resources/examples/workflows/orchestrator.py

@@ -49,7 +49,6 @@ fast = FastAgent("Orchestrator-Workers")
 )
 async def main():
     async with fast.run() as agent:
-
         await agent.author(
             "write a 250 word short story about kittens discovering a castle, and save it to short_story.md"
         )
@@ -68,5 +67,6 @@ async def main():
         await agent.orchestrate(task)
         await agent()
 
+
 if __name__ == "__main__":
     asyncio.run(main())

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)
+
+        # Add a PassthroughLLM as _llm property for compatibility with Orchestrator
+        from mcp_agent.workflows.llm.augmented_llm import PassthroughLLM
 
-        # TODO: Remove legacy - optimizer should always be an AugmentedLLM, no conversion needed
+        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,
@@ -367,9 +419,14 @@ Be concrete and actionable in your recommendations.
         current_response: str,
         feedback: EvaluationResult,
         iteration: int,
+        use_history: bool = None,
     ) -> str:
         """Build the refinement prompt for the optimizer"""
-        history_enabled = hasattr(self, "history") and self.history
+        # 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"""
@@ -391,7 +448,7 @@ Your goal is to address all feedback points while maintaining accuracy and relev
 """
 
         # Only include previous response if history is not enabled
-        if not history_enabled:
+        if not use_history:
             prompt += f"""
 <fastagent:previous-response>
 {current_response}
@@ -409,7 +466,7 @@ Your goal is to address all feedback points while maintaining accuracy and relev
 """
 
         # Customize instruction based on history availability
-        if not history_enabled:
+        if not use_history:
             prompt += """
 <fastagent:instruction>
 Create an improved version of the response that: