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

mcp_agent/core/fastagent.py

@@ -89,21 +89,23 @@ class FastAgent(ContextDependent):
             help="Specify the agent to send a message to (used with --message)",
         )
         parser.add_argument(
-            "-m", "--message",
+            "-m",
+            "--message",
             help="Message to send to the specified agent (requires --agent)",
         )
         parser.add_argument(
-            "--quiet", action="store_true",
+            "--quiet",
+            action="store_true",
             help="Disable progress display, tool and message logging for cleaner output",
         )
         self.args = parser.parse_args()
-        
+
         # Quiet mode will be handled in _load_config()
 
         self.name = name
         self.config_path = config_path
         self._load_config()
-        
+
         # Create the MCPApp with the config
         self.app = MCPApp(
             name=name,
@@ -244,10 +246,24 @@ class FastAgent(ContextDependent):
                     if child_data["type"] == AgentType.BASIC.value:
                         # For basic agents, we'll validate LLM config during creation
                         continue
-                    elif not isinstance(child_data["func"], AugmentedLLM):
+                    # Check if it's a workflow type or has LLM capability
+                    # Workflows like EvaluatorOptimizer and Parallel are valid for orchestrator
+                    func = child_data["func"]
+                    workflow_types = [
+                        AgentType.EVALUATOR_OPTIMIZER.value,
+                        AgentType.PARALLEL.value,
+                        AgentType.ROUTER.value,
+                        AgentType.CHAIN.value,
+                    ]
+
+                    if not (
+                        isinstance(func, AugmentedLLM)
+                        or child_data["type"] in workflow_types
+                        or (hasattr(func, "_llm") and func._llm is not None)
+                    ):
                         raise AgentConfigError(
                             f"Agent '{agent_name}' used by orchestrator '{name}' lacks LLM capability",
-                            "All agents used by orchestrators must be LLM-capable",
+                            "All agents used by orchestrators must be LLM-capable (either an AugmentedLLM or have an _llm property)",
                         )
 
             elif agent_type == AgentType.ROUTER.value:
@@ -536,7 +552,7 @@ class FastAgent(ContextDependent):
         Args:
             name: Name of the parallel executing agent
             fan_out: List of parallel execution agents
-            fan_in: Optional name of collecting agent. If not provided, a passthrough agent 
+            fan_in: Optional name of collecting agent. If not provided, a passthrough agent
                     will be created automatically with the name "{name}_fan_in"
             instruction: Optional instruction for the parallel agent
             model: Model specification string
@@ -547,7 +563,7 @@ class FastAgent(ContextDependent):
         # If fan_in is not provided, create a passthrough agent with a derived name
         if fan_in is None:
             passthrough_name = f"{name}_fan_in"
-            
+
             # Register the passthrough agent directly in self.agents
             self.agents[passthrough_name] = {
                 "config": AgentConfig(
@@ -559,10 +575,10 @@ class FastAgent(ContextDependent):
                 "type": AgentType.BASIC.value,  # Using BASIC type since we're just attaching a PassthroughLLM
                 "func": lambda x: x,  # Simple passthrough function (never actually called)
             }
-            
+
             # Use this passthrough as the fan-in
             fan_in = passthrough_name
-        
+
         decorator = self._create_decorator(
             AgentType.PARALLEL,
             default_instruction="",
@@ -589,6 +605,7 @@ class FastAgent(ContextDependent):
         max_refinements: int = 3,
         use_history: bool = True,
         request_params: Optional[Dict] = None,
+        instruction: Optional[str] = None,
     ) -> Callable:
         """
         Decorator to create and register an evaluator-optimizer workflow.
@@ -601,10 +618,11 @@ class FastAgent(ContextDependent):
             max_refinements: Maximum number of refinement iterations
             use_history: Whether to maintain conversation history
             request_params: Additional request parameters for the LLM
+            instruction: Optional instruction for the workflow (if not provided, uses generator's instruction)
         """
         decorator = self._create_decorator(
             AgentType.EVALUATOR_OPTIMIZER,
-            default_instruction="",
+            default_instruction="",  # We'll get instruction from generator or override
             default_servers=[],
             default_use_history=True,
             wrapper_needed=True,
@@ -616,6 +634,7 @@ class FastAgent(ContextDependent):
             max_refinements=max_refinements,
             use_history=use_history,
             request_params=request_params,
+            instruction=instruction,  # Pass through any custom instruction
         )
         return decorator
 
@@ -645,7 +664,7 @@ class FastAgent(ContextDependent):
             AgentType.ROUTER,
             default_instruction="",
             default_servers=[],
-            default_use_history=True,
+            default_use_history=False,
             wrapper_needed=True,
         )(
             name=name,
@@ -708,17 +727,14 @@ class FastAgent(ContextDependent):
             continue_with_final=continue_with_final,
         )
         return decorator
-        
+
     def passthrough(
-        self,
-        name: str = "Passthrough",
-        use_history: bool = True,
-        **kwargs
+        self, name: str = "Passthrough", use_history: bool = True, **kwargs
     ) -> Callable:
         """
         Decorator to create and register a passthrough agent.
         A passthrough agent simply returns any input message without modification.
-        
+
         This is useful for parallel workflows where no fan-in aggregation is needed
         (the fan-in agent can be a passthrough that simply returns the combined outputs).
 
@@ -774,15 +790,17 @@ class FastAgent(ContextDependent):
                 if agent_type == AgentType.BASIC:
                     # Get the agent name for special handling
                     agent_name = agent_data["config"].name
-                    
+
                     # Check if this is an agent that should use the PassthroughLLM
-                    if agent_name.endswith("_fan_in") or agent_name.startswith("passthrough"):
+                    if agent_name.endswith("_fan_in") or agent_name.startswith(
+                        "passthrough"
+                    ):
                         # Import here to avoid circular imports
                         from mcp_agent.workflows.llm.augmented_llm import PassthroughLLM
-                        
+
                         # Create basic agent with configuration
                         agent = Agent(config=config, context=agent_app.context)
-                        
+
                         # Set up a PassthroughLLM directly
                         async with agent:
                             agent._llm = PassthroughLLM(
@@ -791,13 +809,13 @@ class FastAgent(ContextDependent):
                                 agent=agent,
                                 default_request_params=config.default_request_params,
                             )
-                            
+
                         # Store the agent
                         instance = agent
                     else:
                         # Standard basic agent with LLM
                         agent = Agent(config=config, context=agent_app.context)
-    
+
                         # Set up LLM with proper configuration
                         async with agent:
                             llm_factory = self._get_model_factory(
@@ -805,7 +823,7 @@ class FastAgent(ContextDependent):
                                 request_params=config.default_request_params,
                             )
                             agent._llm = await agent.attach_llm(llm_factory)
-    
+
                         # Store the agent
                         instance = agent
 
@@ -885,18 +903,19 @@ class FastAgent(ContextDependent):
                             f"evaluator={agent_data['evaluator']}"
                         )
 
-                    # TODO: Remove legacy - factory usage is only needed for str evaluators
-                    # Later this should only be passed when evaluator is a string
                     optimizer_model = (
                         generator.config.model if isinstance(generator, Agent) else None
                     )
+
                     instance = EvaluatorOptimizerLLM(
+                        name=config.name,  # Pass name from config
                         generator=generator,
                         evaluator=evaluator,
                         min_rating=QualityRating[agent_data["min_rating"]],
                         max_refinements=agent_data["max_refinements"],
                         llm_factory=self._get_model_factory(model=optimizer_model),
                         context=agent_app.context,
+                        instruction=config.instruction,  # Pass any custom instruction
                     )
 
                 elif agent_type == AgentType.ROUTER:
@@ -1249,77 +1268,96 @@ class FastAgent(ContextDependent):
         """
         active_agents = {}
         had_error = False
-        
+
         # Handle quiet mode by disabling logger settings after initialization
         quiet_mode = hasattr(self, "args") and self.args.quiet
-        
+
         try:
             async with self.app.run() as agent_app:
                 # Apply quiet mode directly to the context's config if needed
-                if quiet_mode and hasattr(agent_app.context, "config") and hasattr(agent_app.context.config, "logger"):
+                if (
+                    quiet_mode
+                    and hasattr(agent_app.context, "config")
+                    and hasattr(agent_app.context.config, "logger")
+                ):
                     # Apply after initialization but before agents are created
                     agent_app.context.config.logger.progress_display = False
                     agent_app.context.config.logger.show_chat = False
                     agent_app.context.config.logger.show_tools = False
-                    
+
                     # Directly disable the progress display singleton
                     from mcp_agent.progress_display import progress_display
+
                     progress_display.stop()  # This will stop and hide the display
-                
+
                 # Pre-flight validation
                 self._validate_server_references()
                 self._validate_workflow_references()
 
                 # Create all types of agents in dependency order
+                # First create basic agents
                 active_agents = await self._create_basic_agents(agent_app)
 
-                orchestrators = await self._create_orchestrators(
+                # Create workflow types that don't depend on other workflows first
+                evaluator_optimizers = await self._create_evaluator_optimizers(
                     agent_app, active_agents
                 )
+                active_agents.update(evaluator_optimizers)
+
+                # Create parallel agents next as they might be dependencies
                 parallel_agents = await self._create_parallel_agents(
                     agent_app, active_agents
                 )
-                evaluator_optimizers = await self._create_evaluator_optimizers(
-                    agent_app, active_agents
-                )
+                active_agents.update(parallel_agents)
+
+                # Create routers next
                 routers = await self._create_routers(agent_app, active_agents)
+                active_agents.update(routers)
+
+                # Create chains next
                 chains = await self._create_agents_in_dependency_order(
                     agent_app, active_agents, AgentType.CHAIN
                 )
+                active_agents.update(chains)
 
-                # Merge all agents into active_agents
+                # Create orchestrators last as they might depend on any other agent type
+                orchestrators = await self._create_orchestrators(
+                    agent_app, active_agents
+                )
+
+                # Add orchestrators to active_agents (other types were already added)
                 active_agents.update(orchestrators)
-                active_agents.update(parallel_agents)
-                active_agents.update(evaluator_optimizers)
-                active_agents.update(routers)
-                active_agents.update(chains)
 
                 # Create wrapper with all agents
                 wrapper = AgentApp(agent_app, active_agents)
-                
+
                 # Handle direct message sending if --agent and --message are provided
                 if self.args.agent and self.args.message:
                     agent_name = self.args.agent
                     message = self.args.message
-                    
+
                     if agent_name not in active_agents:
                         available_agents = ", ".join(active_agents.keys())
-                        print(f"\n\nError: Agent '{agent_name}' not found. Available agents: {available_agents}")
+                        print(
+                            f"\n\nError: Agent '{agent_name}' not found. Available agents: {available_agents}"
+                        )
                         raise SystemExit(1)
-                    
+
                     try:
                         # Get response
                         response = await wrapper[agent_name].send(message)
-                        
+
                         # Only print the response in quiet mode
                         if self.args.quiet:
                             print(f"{response}")
-                        
+
                         raise SystemExit(0)
                     except Exception as e:
-                        print(f"\n\nError sending message to agent '{agent_name}': {str(e)}")
+                        print(
+                            f"\n\nError sending message to agent '{agent_name}': {str(e)}"
+                        )
                         raise SystemExit(1)
-                
+
                 yield wrapper
 
         except ServerConfigError as e:

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

@@ -1,6 +1,7 @@
 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 (Roots)")
@@ -16,6 +17,7 @@ Data files are accessible from the /mnt/data/ directory (this is the current wor
 Visualisations should be saved as .png files in the current working directory.
 """,
     servers=["interpreter"],
+    request_params=RequestParams(maxTokens=8192),
 )
 async def main():
     # Use the app's context manager
@@ -29,7 +31,31 @@ async def main():
             "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,8 +39,7 @@ fast = FastAgent("Evaluator-Optimizer")
     Summarize your evaluation as a structured response with:
     - Overall quality rating.
     - Specific feedback and areas for improvement.""",
-    # instructor doesn't seem to work for sonnet37
-    # model="sonnet35",
+    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/resources/examples/workflows/parallel.py

@@ -60,10 +60,6 @@ and whispers of a hidden agenda linger among the villagers.
     and give an overall grade based on the feedback.""",
     model="o3-mini.low",
 )
-@fast.agent(
-    name="cats-to-dogs",
-    instruction="you should take any text, and change references about cats to dogs",
-)
 @fast.parallel(
     fan_out=["proofreader", "fact_checker", "style_enforcer"],
     fan_in="grader",