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

{fast_agent_mcp-0.1.0.dist-info → fast_agent_mcp-0.1.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fast-agent-mcp
-Version: 0.1.0
+Version: 0.1.2
 Summary: Define, Prompt and Test MCP enabled Agents and Workflows
 Author-email: Shaun Smith <fastagent@llmindset.co.uk>, Sarmad Qadri <sarmad@lastmileai.dev>
 License:                                  Apache License
@@ -257,7 +257,7 @@ Evaluate how different models handle Agent and MCP Server calling tasks, then bu
 
 Prompts and configurations that define your Agent Applications are stored in simple files, with minimal boilerplate, enabling simple management and version control.
 
-Chat with individual Agents and Components before, during and after workflow execution to tune and diagnose your application.
+Chat with individual Agents and Components before, during and after workflow execution to tune and diagnose your application. Agents can request human input to get additional context for task completion.
 
 Simple model selection makes testing Model <-> MCP Server interaction painless. You can read more about the motivation behind this project [here](https://llmindset.co.uk/resources/fast-agent/)
 
@@ -391,6 +391,21 @@ This starts an interactive session, which produces a short social media post for
 
 Chains can be incorporated in other workflows, or contain other workflow elements (including other Chains). You can set an `instruction` to precisely describe it's capabilities to other workflow steps if needed.
 
+### Human Input
+
+Agents can request Human Input to assist with a task or get additional context:
+
+```python
+@fast.agent(
+    instruction="An AI agent that assists with basic tasks. Request Human Input when needed.",
+    human_input=True,
+)
+
+await agent("print the next number in the sequence")
+```
+
+In the example `human_input.py`, the Agent will prompt the User for additional information to complete the task.
+
 ### Parallel
 
 The Parallel Workflow sends the same message to multiple Agents simultaneously (`fan-out`), then uses the `fan-in` Agent to process the combined content.
@@ -464,7 +479,7 @@ Given a complex task, the Orchestrator uses an LLM to generate a plan to divide
 )
 ```
 
-See `orchestrator.py` in the workflow examples.
+See the `orchestrator.py` or `agent_build.py` workflow example.
 
 ## Agent Features
 
@@ -559,9 +574,10 @@ agent["greeter"].send("Good Evening!")          # Dictionary access is supported
   instruction="instruction",             # base instruction for the orchestrator
   agents=["agent1", "agent2"],           # list of agent names this orchestrator can use
   model="o3-mini.high",                  # specify orchestrator planning model
-  use_history=False,                     # orchestrator doesn't maintain chat history by default
+  use_history=False,                     # orchestrator doesn't maintain chat history (no effect).
   human_input=False,                     # whether orchestrator can request human input
   plan_type="full",                      # planning approach: "full" or "iterative"
+  max_iterations=5,                      # maximum number of full plan attempts, or iterations
 )
 ```
 

{fast_agent_mcp-0.1.0.dist-info → fast_agent_mcp-0.1.2.dist-info}/RECORD

@@ -23,7 +23,7 @@ mcp_agent/core/agent_utils.py,sha256=yUJ-qvw5TblqqOsB1vj0Qvcz9mass9awPA6UNNvuw0A
 mcp_agent/core/enhanced_prompt.py,sha256=XraDKdIMW960KXCiMfCEPKDakbf1wHYgvHwD-9CBDi0,13011
 mcp_agent/core/error_handling.py,sha256=D3HMW5odrbJvaKqcpCGj6eDXrbFcuqYaCZz7fyYiTu4,623
 mcp_agent/core/exceptions.py,sha256=a2-JGRwFFRoQEPuAq0JC5PhAJ5TO3xVJfdS4-VN29cw,2225
-mcp_agent/core/fastagent.py,sha256=CuT50oaexYq7L5-1xHR5HfS7qYKNToH3wmBAeD8kcBY,58234
+mcp_agent/core/fastagent.py,sha256=drf11eHH1xCiyS91v_ADWfaV8T9asm_2Vw0NXxjinpc,58730
 mcp_agent/core/proxies.py,sha256=hXDUpsgGO4xBTIjdUeXj6vULPb8sf55vAFVQh6Ybn60,4411
 mcp_agent/core/server_validation.py,sha256=_59cn16nNT4HGPwg19HgxMtHK4MsdWYDUw_CuL-5xek,1696
 mcp_agent/core/types.py,sha256=Zhi9iW7uiOfdpSt9NC0FCtGRFtJPg4mpZPK2aYi7a7M,817
@@ -55,7 +55,7 @@ mcp_agent/mcp/mcp_aggregator.py,sha256=RVsgNnSJ1IPBkqKgF_Gp-Cpv97FVBIdppPey6FRoH
 mcp_agent/mcp/mcp_connection_manager.py,sha256=WLli0w3TVcsszyD9M7zP7vLKPetnQLTf_0PGhvMm9YM,13145
 mcp_agent/mcp/stdio.py,sha256=tW075R5rQ-UlflXWFKIFDgCbWbuhKqxhiYolWvyEkFs,3985
 mcp_agent/resources/examples/data-analysis/analysis-campaign.py,sha256=EG-HhaDHltZ4hHAqhgfX_pHM2wem48aYhSIKJxyWHKc,7269
-mcp_agent/resources/examples/data-analysis/analysis.py,sha256=yRwcYob-jaqwR1vdx_gYXpfqtBN4w7creNeNgimOHa4,2443
+mcp_agent/resources/examples/data-analysis/analysis.py,sha256=5zLoioZQNKUfXt1EXLrGX3TU06-0N06-L9Gtp9BIr6k,2611
 mcp_agent/resources/examples/data-analysis/fastagent.config.yaml,sha256=eTKGbjnTHhDTeNRPQvG_fr9OQpEZ5Y9v7X2NyCj0V70,530
 mcp_agent/resources/examples/data-analysis/mount-point/WA_Fn-UseC_-HR-Employee-Attrition.csv,sha256=pcMeOL1_r8m8MziE6xgbBrQbjl5Ijo98yycZn7O-dlk,227977
 mcp_agent/resources/examples/internal/agent.py,sha256=f-jTgYabV3nWCQm0ZP9NtSEWjx3nQbRngzArRufcELg,384
@@ -65,12 +65,12 @@ mcp_agent/resources/examples/mcp_researcher/researcher-eval.py,sha256=kNPjIU-JwE
 mcp_agent/resources/examples/researcher/fastagent.config.yaml,sha256=2_VXZneckR6zk6RWzzL-smV_oWmgg4uSkLWqZv8jF0I,1995
 mcp_agent/resources/examples/researcher/researcher-eval.py,sha256=kNPjIU-JwE0oIBQKwhv6lZsUF_SPtYVkiEEbY1ZVZxk,1807
 mcp_agent/resources/examples/researcher/researcher.py,sha256=jPRafm7jbpHKkX_dQiYGG3Sw-e1Dm86q-JZT-WZDhM0,1425
-mcp_agent/resources/examples/workflows/agent_build.py,sha256=vdjS02rZR88RU53WYzXxPscfFNEFFe_niHYE_i49I8Q,2396
+mcp_agent/resources/examples/workflows/agent_build.py,sha256=ioG4X8IbR8wwja8Zdncsk8YAu0VD2Xt1Vhr7saNJCZQ,2855
 mcp_agent/resources/examples/workflows/chaining.py,sha256=1G_0XBcFkSJCOXb6N_iXWlSc_oGAlhENR0k_CN1vJKI,1208
 mcp_agent/resources/examples/workflows/evaluator.py,sha256=3XmW1mjImlaWb0c5FWHYS9yP8nVGTbEdJySAoWXwrDg,3109
 mcp_agent/resources/examples/workflows/fastagent.config.yaml,sha256=k2AiapOcK42uqG2nWDVvnSLqN4okQIQZK0FTbZufBpY,809
 mcp_agent/resources/examples/workflows/human_input.py,sha256=c8cBdLEPbaMXddFwsfN3Z7RFs5PZXsdrjANfvq1VTPM,605
-mcp_agent/resources/examples/workflows/orchestrator.py,sha256=5TGFWrRQiTCdYY738cyd_OzZc7vckYkk1Up9VejFXB0,2574
+mcp_agent/resources/examples/workflows/orchestrator.py,sha256=oyKzmLA1z00wbAwDwBCthJ_qJx4fai6GAJpeOXDR-bE,2569
 mcp_agent/resources/examples/workflows/parallel.py,sha256=pLbQrtXfbdYqMVddxtg5dZnBnm5Wo2mXlIa1Vf2F1FQ,3096
 mcp_agent/resources/examples/workflows/router.py,sha256=XT_ewCrxPxdUTMCYQGw34qZQ3GGu8TYY_v5Lige8By4,1707
 mcp_agent/telemetry/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -92,15 +92,15 @@ mcp_agent/workflows/intent_classifier/intent_classifier_llm_anthropic.py,sha256=
 mcp_agent/workflows/intent_classifier/intent_classifier_llm_openai.py,sha256=zj76WlTYnSCYjBQ_IDi5vFBQGmNwYaoUq1rT730sY98,1940
 mcp_agent/workflows/llm/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 mcp_agent/workflows/llm/augmented_llm.py,sha256=Hyx-jwgbMjE_WQ--YjIUvdj6HAgX36IvXBesGy6uic0,25884
-mcp_agent/workflows/llm/augmented_llm_anthropic.py,sha256=iHfbn7bwC-ICTajEhGwg9vP-UEj681kNmZ9Cv6H05s4,22968
+mcp_agent/workflows/llm/augmented_llm_anthropic.py,sha256=XZmumX-og07VR4O2TnEYQ9ZPwGgzLWt3uq6MII-tjnI,23076
 mcp_agent/workflows/llm/augmented_llm_openai.py,sha256=a95Q4AFiVw36bXMgYNLFrC2zyDmHERWwkjxJFHlL6JU,25061
 mcp_agent/workflows/llm/llm_selector.py,sha256=G7pIybuBDwtmyxUDov_QrNYH2FoI0qFRu2JfoxWUF5Y,11045
 mcp_agent/workflows/llm/model_factory.py,sha256=7zTJrO2ReHa_6dfh_gY6xO8dTySqGFCKlOG9-AMJ-i8,6920
 mcp_agent/workflows/llm/prompt_utils.py,sha256=EY3eddqnmc_YDUQJFysPnpTH6hr4r2HneeEmX76P8TQ,4948
 mcp_agent/workflows/orchestrator/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-mcp_agent/workflows/orchestrator/orchestrator.py,sha256=nyn0vTjUz-lea7nIYY-aoVWOKB2ceNNV4x4z92bP3CI,23638
-mcp_agent/workflows/orchestrator/orchestrator_models.py,sha256=xTl2vUIqdLPvDAnqA485Hf_A3DD48TWhAbo-jfGrmRE,7182
-mcp_agent/workflows/orchestrator/orchestrator_prompts.py,sha256=eJSQThfd6Jvr1jTDx104sJI5R684yE55L_edCiWERsQ,6153
+mcp_agent/workflows/orchestrator/orchestrator.py,sha256=Cu8cfDoTpT_FhGJp-T4NnCVvjkyDO1sbEJ7oKamK47k,26021
+mcp_agent/workflows/orchestrator/orchestrator_models.py,sha256=1ldku1fYA_hu2F6K4l2C96mAdds05VibtSzSQrGm3yw,7321
+mcp_agent/workflows/orchestrator/orchestrator_prompts.py,sha256=EXKEI174sshkZyPPEnWbwwNafzSPuA39MXL7iqG9cWc,9106
 mcp_agent/workflows/parallel/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 mcp_agent/workflows/parallel/fan_in.py,sha256=EivpUL5-qftctws-tlfwmYS1QeSwr07POIbBUbwvwOk,13184
 mcp_agent/workflows/parallel/fan_out.py,sha256=J-yezgjzAWxfueW_Qcgwoet4PFDRIh0h4m48lIbFA4c,7023
@@ -115,8 +115,8 @@ mcp_agent/workflows/swarm/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJW
 mcp_agent/workflows/swarm/swarm.py,sha256=-lAIeSWDqbGHGRPTvjiP9nIKWvxxy9DAojl9yQzO1Pw,11050
 mcp_agent/workflows/swarm/swarm_anthropic.py,sha256=pW8zFx5baUWGd5Vw3nIDF2oVOOGNorij4qvGJKdYPcs,1624
 mcp_agent/workflows/swarm/swarm_openai.py,sha256=wfteywvAGkT5bLmIxX_StHJq8144whYmCRnJASAjOes,1596
-fast_agent_mcp-0.1.0.dist-info/METADATA,sha256=hN241Foz895Wj3dxkXWKDVeeTuIWmAT1zh7Jvgpo3Bo,27257
-fast_agent_mcp-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-fast_agent_mcp-0.1.0.dist-info/entry_points.txt,sha256=2IXtSmDK9XjWN__RWuRIJTgWyW17wJnJ_h-pb0pZAxo,174
-fast_agent_mcp-0.1.0.dist-info/licenses/LICENSE,sha256=cN3FxDURL9XuzE5mhK9L2paZo82LTfjwCYVT7e3j0e4,10939
-fast_agent_mcp-0.1.0.dist-info/RECORD,,
+fast_agent_mcp-0.1.2.dist-info/METADATA,sha256=qcYR5D0SlhnnqX7er7yFF_0nEOmt4J74hbWiftzw6iI,27861
+fast_agent_mcp-0.1.2.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+fast_agent_mcp-0.1.2.dist-info/entry_points.txt,sha256=2IXtSmDK9XjWN__RWuRIJTgWyW17wJnJ_h-pb0pZAxo,174
+fast_agent_mcp-0.1.2.dist-info/licenses/LICENSE,sha256=cN3FxDURL9XuzE5mhK9L2paZo82LTfjwCYVT7e3j0e4,10939
+fast_agent_mcp-0.1.2.dist-info/RECORD,,

mcp_agent/core/fastagent.py

@@ -497,6 +497,7 @@ class FastAgent(ContextDependent):
         request_params: Optional[Dict] = None,
         human_input: bool = False,
         plan_type: Literal["full", "iterative"] = "full",
+        max_iterations: int = 30,  # Add the max_iterations parameter with default value
     ) -> Callable:
         """
         Decorator to create and register an orchestrator.
@@ -510,6 +511,7 @@ class FastAgent(ContextDependent):
             request_params: Additional request parameters for the LLM
             human_input: Whether to enable human input capabilities
             plan_type: Planning approach - "full" generates entire plan first, "iterative" plans one step at a time
+            max_iterations: Maximum number of planning iterations (default: 10)
         """
         default_instruction = """
             You are an expert planner. Given an objective task and a list of MCP servers (which are collections of tools)
@@ -517,6 +519,13 @@ class FastAgent(ContextDependent):
             which can be performed by LLMs with access to the servers or agents.
             """
 
+        # Handle request_params update with max_iterations
+        if request_params is None:
+            request_params = {"max_iterations": max_iterations}
+        elif isinstance(request_params, dict):
+            if "max_iterations" not in request_params:
+                request_params["max_iterations"] = max_iterations
+
         decorator = self._create_decorator(
             AgentType.ORCHESTRATOR,
             default_name="Orchestrator",

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

@@ -7,6 +7,10 @@ from mcp_agent.workflows.llm.augmented_llm import RequestParams
 fast = FastAgent("Data Analysis (Roots)")
 
 
+# The sample data is under Database Contents License (DbCL) v1.0.
+# Available here : https://www.kaggle.com/datasets/pavansubhasht/ibm-hr-analytics-attrition-dataset
+
+
 @fast.agent(
     name="data_analysis",
     instruction="""

mcp_agent/resources/examples/workflows/agent_build.py

@@ -4,6 +4,7 @@ This demonstrates creating multiple agents and an orchestrator to coordinate the
 
 import asyncio
 from mcp_agent.core.fastagent import FastAgent
+from mcp_agent.workflows.llm.augmented_llm import RequestParams
 
 # Create the application
 fast = FastAgent("Agent Builder")
@@ -12,49 +13,70 @@ fast = FastAgent("Agent Builder")
 @fast.agent(
     "agent_expert",
     instruction="""
-You design agent workflows, using the practices from 'Building Effective Agents'. You provide concise
-specific guidance on design and composition. Prefer simple solutions, and don't nest workflows more 
-than one level deep. Your ultimate goal will be to produce a single '.py' agent in the style
-shown to you that fulfils the Human's needs.
-Keep the application simple, define agents with appropriate  MCP Servers, Tools  and the Human Input Tool.
-The style of the program should be like the examples you have been showm, very little additional code (use
-very simple Python where necessary). """,
+You design agent workflows, adhering to 'Building Effective Agents' (details to follow). 
+
+You provide concise specific guidance on design and composition. Prefer simple solutions, 
+and don't nest workflows more than one level deep. 
+
+Your objective is to produce a single '.py' agent in the style of the examples.
+
+Keep the application simple, concentrationg on defining Agent instructions, MCP Servers and
+appropriate use of Workflows. 
+
+The style of the program should be like the examples you have been shown, with a minimum of
+additional code, using only very simple Python where absolutely necessary.
+
+Concentrate on the quality of the Agent instructions and "warmup" prompts given to them.
+
+Keep requirements minimal: focus on building the prompts and the best workflow. The program
+is expected to be adjusted and refined later.
+
+If you are unsure about how to proceed, request input from the Human.
+
+Use the filesystem tools to save your completed fastagent program, in an appropriately named '.py' file. 
+
+ """,
     servers=["filesystem", "fetch"],
+    request_params=RequestParams(maxTokens=8192),
 )
 # Define worker agents
 @fast.agent(
     "requirements_capture",
     instruction="""
-You help the Human define their requirements for building Agent based systems. Keep questions short and
-simple, collaborate with the agent_expert or other agents in the workflow to refine human interaction. 
-Keep requests to the Human simple and minimal. """,
+You help the Human define their requirements for building Agent based systems.
+
+Keep questions short, simple and minimal, always offering to complete the questioning
+if desired. If uncertain about something, respond asking the 'agent_expert' for guidance.
+
+Do not interrogate the Human, prefer to move the process on, as more details can be requested later 
+if needed. Remind the Human of this.
+ """,
     human_input=True,
 )
 # Define the orchestrator to coordinate the other agents
 @fast.orchestrator(
-    name="orchestrator_worker",
+    name="agent_builder",
     agents=["agent_expert", "requirements_capture"],
     model="sonnet",
+    plan_type="iterative",
+    request_params=RequestParams(maxTokens=8192),
+    max_iterations=5,
 )
 async def main():
     async with fast.run() as agent:
-        await agent.agent_expert("""
-- Read this paper: https://www.anthropic.com/research/building-effective-agents" to understand
-the principles of Building Effective Agents. 
-- Read and examing the sample agent and workflow definitions in the current directory:
-  - chaining.py - simple agent chaining example.
-  - parallel.py - parallel agents example.
-  - evaluator.py - evaluator optimizer example.
-  - orchestrator.py - complex orchestration example.
-  - router.py - workflow routing example.
-- Load the 'fastagent.config.yaml' file to see the available and configured MCP Servers.
-When producing the agent/workflow definition, keep to a simple single .py file in the style
-of the examples.
-        """)
-
-        await agent.orchestrator_worker(
-            "Write an Agent program that fulfils the Human's needs."
-        )
+        CODER_WARMUP = """
+- Read this paper: https://www.anthropic.com/research/building-effective-agents" to understand how 
+and when to use different types of Agents and Workflow types.
+
+- Read this README https://raw.githubusercontent.com/evalstate/fast-agent/refs/heads/main/README.md file
+to see how to use "fast-agent" framework.
+
+- Look at the 'fastagent.config.yaml' file to see the available and configured MCP Servers.
+
+"""
+        await agent.agent_expert(CODER_WARMUP)
+
+        await agent.agent_builder()
 
 
 if __name__ == "__main__":

mcp_agent/resources/examples/workflows/orchestrator.py

@@ -45,7 +45,7 @@ fast = FastAgent("Orchestrator-Workers")
 @fast.orchestrator(
     name="orchestrate",
     agents=["finder", "writer", "proofreader"],
-    plan_type="iterative",
+    plan_type="full",
 )
 async def main():
     async with fast.run() as agent:

mcp_agent/workflows/llm/augmented_llm_anthropic.py

@@ -246,15 +246,16 @@ class AnthropicAugmentedLLM(AugmentedLLM[MessageParam, Message]):
                             style="dim green italic",
                         )
 
-                    await self.show_assistant_message(message_text)
-
                     # Process all tool calls and collect results
                     tool_results = []
-                    for content in tool_uses:
+                    for i, content in enumerate(tool_uses):
                         tool_name = content.name
                         tool_args = content.input
                         tool_use_id = content.id
 
+                        if i == 0:  # Only show message for first tool use
+                            await self.show_assistant_message(message_text, tool_name)
+
                         self.show_tool_call(available_tools, tool_name, tool_args)
                         tool_call_request = CallToolRequest(
                             method="tools/call",

mcp_agent/workflows/orchestrator/orchestrator.py

@@ -32,6 +32,7 @@ from mcp_agent.workflows.orchestrator.orchestrator_models import (
 from mcp_agent.workflows.orchestrator.orchestrator_prompts import (
     FULL_PLAN_PROMPT_TEMPLATE,
     ITERATIVE_PLAN_PROMPT_TEMPLATE,
+    SYNTHESIZE_INCOMPLETE_PLAN_TEMPLATE,  # Add the missing import
     SYNTHESIZE_PLAN_PROMPT_TEMPLATE,
     TASK_PROMPT_TEMPLATE,
 )
@@ -90,7 +91,7 @@ class Orchestrator(AugmentedLLM[MessageParamT, MessageT]):
         # Initialize with orchestrator-specific defaults
         orchestrator_params = RequestParams(
             use_history=False,  # Orchestrator doesn't support history
-            max_iterations=30,  # Higher default for complex tasks
+            max_iterations=5,  # Reduced from 10 to prevent excessive iterations
             maxTokens=8192,  # Higher default for planning
             parallel_tool_calls=True,
         )
@@ -126,7 +127,6 @@ class Orchestrator(AugmentedLLM[MessageParamT, MessageT]):
         self.agents = {agent.name: agent for agent in available_agents}
 
         # Initialize logger
-        self.logger = logger
         self.name = name
 
         # Store agents by name - COMPLETE REWRITE OF AGENT STORAGE
@@ -213,8 +213,12 @@ class Orchestrator(AugmentedLLM[MessageParamT, MessageT]):
     ) -> PlanResult:
         """Execute task with result chaining between steps"""
         iterations = 0
+        total_steps_executed = 0
 
         params = self.get_request_params(request_params)
+        max_steps = getattr(
+            params, "max_steps", params.max_iterations * 5
+        )  # Default to 5× max_iterations
 
         # Single progress event for orchestration start
         model = await self.select_model(params) or "unknown-model"
@@ -231,6 +235,9 @@ class Orchestrator(AugmentedLLM[MessageParamT, MessageT]):
         )
 
         plan_result = PlanResult(objective=objective, step_results=[])
+        plan_result.max_iterations_reached = (
+            False  # Add a flag to track if we hit the limit
+        )
 
         while iterations < params.max_iterations:
             if self.plan_type == "iterative":
@@ -255,30 +262,34 @@ class Orchestrator(AugmentedLLM[MessageParamT, MessageT]):
             plan_result.plan = plan
 
             if plan.is_complete:
-                # Only mark as complete if we have actually executed some steps
-                if len(plan_result.step_results) > 0:
-                    plan_result.is_complete = True
-
-                    # Synthesize final result into a single message
-                    # Use the structured XML format for better context
-                    synthesis_prompt = SYNTHESIZE_PLAN_PROMPT_TEMPLATE.format(
-                        plan_result=format_plan_result(plan_result)
-                    )
+                # Modified: Remove the requirement for steps to be executed
+                plan_result.is_complete = True
 
-                    # Use planner directly - planner already has PLANNING verb
-                    plan_result.result = await self.planner.generate_str(
-                        message=synthesis_prompt,
-                        request_params=params.model_copy(update={"max_iterations": 1}),
-                    )
+                # Synthesize final result into a single message
+                # Use the structured XML format for better context
+                synthesis_prompt = SYNTHESIZE_PLAN_PROMPT_TEMPLATE.format(
+                    plan_result=format_plan_result(plan_result)
+                )
 
-                    return plan_result
-                else:
-                    # Don't allow completion without executing steps
-                    plan.is_complete = False
+                # Use planner directly - planner already has PLANNING verb
+                plan_result.result = await self.planner.generate_str(
+                    message=synthesis_prompt,
+                    request_params=params.model_copy(update={"max_iterations": 1}),
+                )
+
+                return plan_result
 
             # Execute each step, collecting results
             # Note that in iterative mode this will only be a single step
             for step in plan.steps:
+                # Check if we've hit the step limit
+                if total_steps_executed >= max_steps:
+                    self.logger.warning(
+                        f"Reached maximum step limit ({max_steps}) without completing objective."
+                    )
+                    plan_result.max_steps_reached = True
+                    break
+
                 step_result = await self._execute_step(
                     step=step,
                     previous_result=plan_result,
@@ -286,16 +297,48 @@ class Orchestrator(AugmentedLLM[MessageParamT, MessageT]):
                 )
 
                 plan_result.add_step_result(step_result)
+                total_steps_executed += 1
+
+            # Check for step limit after executing steps
+            if total_steps_executed >= max_steps:
+                plan_result.max_iterations_reached = True
+                break
 
             logger.debug(
                 f"Iteration {iterations}: Intermediate plan result:", data=plan_result
             )
+
+            # Check for diminishing returns
+            if iterations > 2 and len(plan.steps) <= 1:
+                # If plan has 0-1 steps after multiple iterations, might be done
+                self.logger.info("Minimal new steps detected, marking plan as complete")
+                plan_result.is_complete = True
+                break
+
             iterations += 1
 
-        raise RuntimeError(
-            f"Task failed to complete in {params.max_iterations} iterations"
+        # If we get here, we've hit the iteration limit without completing
+        self.logger.warning(
+            f"Failed to complete in {params.max_iterations} iterations."
+        )
+
+        # Mark that we hit the iteration limit
+        plan_result.max_iterations_reached = True
+
+        # Synthesize what we have so far, but use a different prompt that explains the incomplete status
+        synthesis_prompt = SYNTHESIZE_INCOMPLETE_PLAN_TEMPLATE.format(
+            plan_result=format_plan_result(plan_result),
+            max_iterations=params.max_iterations,
+        )
+
+        # Generate a final synthesis that acknowledges the incomplete status
+        plan_result.result = await self.planner.generate_str(
+            message=synthesis_prompt,
+            request_params=params.model_copy(update={"max_iterations": 1}),
         )
 
+        return plan_result
+
     async def _execute_step(
         self,
         step: Step,
@@ -399,18 +442,11 @@ class Orchestrator(AugmentedLLM[MessageParamT, MessageT]):
         params = self.get_request_params(request_params)
         params = params.model_copy(update={"use_history": False})
 
-        # Debug: Print agent names before formatting
-        print("\n------ AGENT NAMES BEFORE FORMATTING ------")
-        for agent_name in self.agents.keys():
-            print(f"Agent name: '{agent_name}'")
-        print("------------------------------------------\n")
-
         # Format agents without numeric prefixes for cleaner XML
         agent_formats = []
         for agent_name in self.agents.keys():
             formatted = self._format_agent_info(agent_name)
             agent_formats.append(formatted)
-            print(f"Formatted agent '{agent_name}':\n{formatted[:200]}...\n")
 
         agents = "\n".join(agent_formats)
 
@@ -423,10 +459,21 @@ class Orchestrator(AugmentedLLM[MessageParamT, MessageT]):
                 else "Plan Status: In Progress"
             )
 
+        # Fix the iteration counting display
+        max_iterations = params.max_iterations
+        # Simplified iteration counting logic
+        current_iteration = len(plan_result.step_results)
+        current_iteration = min(current_iteration, max_iterations - 1)  # Cap at max-1
+        iterations_remaining = max(
+            0, max_iterations - current_iteration - 1
+        )  # Ensure non-negative
+        iterations_info = f"Planning Budget: Iteration {current_iteration + 1} of {max_iterations} (with {iterations_remaining} remaining)"
+
         prompt = FULL_PLAN_PROMPT_TEMPLATE.format(
             objective=objective,
             plan_result=format_plan_result(plan_result),
             plan_status=plan_status,
+            iterations_info=iterations_info,
             agents=agents,
         )
 
@@ -507,10 +554,17 @@ class Orchestrator(AugmentedLLM[MessageParamT, MessageT]):
                 else "Plan Status: In Progress"
             )
 
+        # Add max_iterations info for the LLM
+        max_iterations = params.max_iterations
+        current_iteration = len(plan_result.step_results)
+        iterations_remaining = max_iterations - current_iteration
+        iterations_info = f"Planning Budget: {iterations_remaining} of {max_iterations} iterations remaining"
+
         prompt = ITERATIVE_PLAN_PROMPT_TEMPLATE.format(
             objective=objective,
             plan_result=format_plan_result(plan_result),
             plan_status=plan_status,
+            iterations_info=iterations_info,
             agents=agents,
         )
 

mcp_agent/workflows/orchestrator/orchestrator_models.py

@@ -102,6 +102,9 @@ class PlanResult(BaseModel):
     is_complete: bool = False
     """Whether the overall plan objective is complete"""
 
+    max_iterations_reached: bool = False
+    """Whether the plan execution reached the maximum number of iterations without completing"""
+
     result: str | None = None
     """Result of executing the plan"""
 

mcp_agent/workflows/orchestrator/orchestrator_prompts.py

@@ -1,3 +1,8 @@
+"""
+Prompt templates used by the Orchestrator workflow.
+"""
+
+# Templates for formatting results
 TASK_RESULT_TEMPLATE = """Task: {task_description}
 Result: {task_result}"""
 
@@ -30,6 +35,7 @@ You can analyze results from the previous steps already executed to decide if th
 
 <fastagent:status>
 {plan_status}
+{iterations_info}
 </fastagent:status>
 </fastagent:data>
 
@@ -38,6 +44,10 @@ 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.
@@ -68,6 +78,14 @@ Return your response in the following JSON structure:
         "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>
@@ -92,6 +110,7 @@ to decide what to do next.
 
 <fastagent:status>
 {plan_status}
+{iterations_info}
 </fastagent:status>
 </fastagent:data>
 
@@ -100,6 +119,9 @@ 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  
@@ -120,6 +142,14 @@ Return your response in the following JSON structure:
         "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>
@@ -184,5 +214,35 @@ 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>
 """