fast-agent-mcp 0.2.45__py3-none-any.whl → 0.2.47__py3-none-any.whl

mcp_agent/core/agent_types.py

@@ -22,6 +22,7 @@ class AgentType(Enum):
     EVALUATOR_OPTIMIZER = "evaluator_optimizer"
     ROUTER = "router"
     CHAIN = "chain"
+    ITERATIVE_PLANNER = "iterative_planner"
 
 
 @dataclass

mcp_agent/core/direct_decorators.py

@@ -6,6 +6,7 @@ for creating agents in the DirectFastAgent framework.
 
 import inspect
 from functools import wraps
+from pathlib import Path
 from typing import (
     Awaitable,
     Callable,
@@ -21,8 +22,10 @@ from typing import (
 )
 
 from mcp.client.session import ElicitationFnT
+from pydantic import AnyUrl
 
 from mcp_agent.agents.agent import AgentConfig
+from mcp_agent.agents.workflow.iterative_planner import ITERATIVE_PLAN_SYSTEM_PROMPT_TEMPLATE
 from mcp_agent.agents.workflow.router_agent import (
     ROUTING_SYSTEM_INSTRUCTION,
 )
@@ -85,6 +88,91 @@ class DecoratedEvaluatorOptimizerProtocol(DecoratedAgentProtocol[P, R], Protocol
     _evaluator: str
 
 
+def _fetch_url_content(url: str) -> str:
+    """
+    Fetch content from a URL.
+
+    Args:
+        url: The URL to fetch content from
+
+    Returns:
+        The text content from the URL
+
+    Raises:
+        requests.RequestException: If the URL cannot be fetched
+        UnicodeDecodeError: If the content cannot be decoded as UTF-8
+    """
+    import requests
+
+    response = requests.get(url, timeout=10)
+    response.raise_for_status()  # Raise exception for HTTP errors
+    return response.text
+
+
+def _apply_templates(text: str) -> str:
+    """
+    Apply template substitutions to instruction text.
+
+    Supported templates:
+        {{currentDate}} - Current date in format "24 July 2025"
+        {{url:https://...}} - Content fetched from the specified URL
+
+    Args:
+        text: The text to process
+
+    Returns:
+        Text with template substitutions applied
+
+    Raises:
+        requests.RequestException: If a URL in {{url:...}} cannot be fetched
+        UnicodeDecodeError: If URL content cannot be decoded as UTF-8
+    """
+    import re
+    from datetime import datetime
+
+    # Apply {{currentDate}} template
+    current_date = datetime.now().strftime("%d %B %Y")
+    text = text.replace("{{currentDate}}", current_date)
+
+    # Apply {{url:...}} templates
+    url_pattern = re.compile(r"\{\{url:(https?://[^}]+)\}\}")
+
+    def replace_url(match):
+        url = match.group(1)
+        return _fetch_url_content(url)
+
+    text = url_pattern.sub(replace_url, text)
+
+    return text
+
+
+def _resolve_instruction(instruction: str | Path | AnyUrl) -> str:
+    """
+    Resolve instruction from either a string, Path, or URL with template support.
+
+    Args:
+        instruction: Either a string instruction, Path to a file, or URL containing the instruction
+
+    Returns:
+        The resolved instruction string with templates applied
+
+    Raises:
+        FileNotFoundError: If the Path doesn't exist
+        PermissionError: If the Path can't be read
+        UnicodeDecodeError: If the file/URL content can't be decoded as UTF-8
+        requests.RequestException: If the URL cannot be fetched
+    """
+    if isinstance(instruction, Path):
+        text = instruction.read_text(encoding="utf-8")
+    elif isinstance(instruction, AnyUrl):
+        text = _fetch_url_content(str(instruction))
+    else:
+        text = instruction
+
+    # Apply template substitutions
+    return _apply_templates(text)
+
+
 def _decorator_impl(
     self,
     agent_type: AgentType,
@@ -183,9 +271,9 @@ def _decorator_impl(
 def agent(
     self,
     name: str = "default",
-    instruction_or_kwarg: Optional[str] = None,
+    instruction_or_kwarg: Optional[str | Path | AnyUrl] = None,
     *,
-    instruction: str = "You are a helpful agent.",
+    instruction: str | Path | AnyUrl = "You are a helpful agent.",
     servers: List[str] = [],
     tools: Optional[Dict[str, List[str]]] = None,
     resources: Optional[Dict[str, List[str]]] = None,
@@ -220,7 +308,10 @@ def agent(
     Returns:
         A decorator that registers the agent with proper type annotations
     """
-    final_instruction = instruction_or_kwarg if instruction_or_kwarg is not None else instruction
+    final_instruction_raw = (
+        instruction_or_kwarg if instruction_or_kwarg is not None else instruction
+    )
+    final_instruction = _resolve_instruction(final_instruction_raw)
 
     return _decorator_impl(
         self,
@@ -245,9 +336,9 @@ def custom(
     self,
     cls,
     name: str = "default",
-    instruction_or_kwarg: Optional[str] = None,
+    instruction_or_kwarg: Optional[str | Path | AnyUrl] = None,
     *,
-    instruction: str = "You are a helpful agent.",
+    instruction: str | Path | AnyUrl = "You are a helpful agent.",
     servers: List[str] = [],
     tools: Optional[Dict[str, List[str]]] = None,
     resources: Optional[Dict[str, List[str]]] = None,
@@ -277,7 +368,10 @@ def custom(
     Returns:
         A decorator that registers the agent with proper type annotations
     """
-    final_instruction = instruction_or_kwarg if instruction_or_kwarg is not None else instruction
+    final_instruction_raw = (
+        instruction_or_kwarg if instruction_or_kwarg is not None else instruction
+    )
+    final_instruction = _resolve_instruction(final_instruction_raw)
 
     return _decorator_impl(
         self,
@@ -311,7 +405,7 @@ def orchestrator(
     name: str,
     *,
     agents: List[str],
-    instruction: str = DEFAULT_INSTRUCTION_ORCHESTRATOR,
+    instruction: str | Path | AnyUrl = DEFAULT_INSTRUCTION_ORCHESTRATOR,
     model: Optional[str] = None,
     request_params: RequestParams | None = None,
     use_history: bool = False,
@@ -341,6 +435,7 @@ def orchestrator(
     """
 
     # Create final request params with plan_iterations
+    resolved_instruction = _resolve_instruction(instruction)
 
     return cast(
         "Callable[[AgentCallable[P, R]], DecoratedOrchestratorProtocol[P, R]]",
@@ -348,7 +443,7 @@ def orchestrator(
             self,
             AgentType.ORCHESTRATOR,
             name=name,
-            instruction=instruction,
+            instruction=resolved_instruction,
             servers=[],  # Orchestrators don't connect to servers directly
             model=model,
             use_history=use_history,
@@ -363,12 +458,65 @@ def orchestrator(
     )
 
 
+def iterative_planner(
+    self,
+    name: str,
+    *,
+    agents: List[str],
+    instruction: str | Path | AnyUrl = ITERATIVE_PLAN_SYSTEM_PROMPT_TEMPLATE,
+    model: Optional[str] = None,
+    request_params: RequestParams | None = None,
+    plan_iterations: int = -1,
+    default: bool = False,
+    api_key: str | None = None,
+) -> Callable[[AgentCallable[P, R]], DecoratedOrchestratorProtocol[P, R]]:
+    """
+    Decorator to create and register an orchestrator agent with type-safe signature.
+
+    Args:
+        name: Name of the orchestrator
+        agents: List of agent names this orchestrator can use
+        instruction: Base instruction for the orchestrator
+        model: Model specification string
+        use_history: Whether to maintain conversation history
+        request_params: Additional request parameters for the LLM
+        human_input: Whether to enable human input capabilities
+        plan_type: Planning approach - "full" or "iterative"
+        plan_iterations: Maximum number of planning iterations (0 for unlimited)
+        default: Whether to mark this as the default agent
+
+    Returns:
+        A decorator that registers the orchestrator with proper type annotations
+    """
+
+    # Create final request params with plan_iterations
+    resolved_instruction = _resolve_instruction(instruction)
+
+    return cast(
+        "Callable[[AgentCallable[P, R]], DecoratedOrchestratorProtocol[P, R]]",
+        _decorator_impl(
+            self,
+            AgentType.ITERATIVE_PLANNER,
+            name=name,
+            instruction=resolved_instruction,
+            servers=[],  # Orchestrators don't connect to servers directly
+            model=model,
+            use_history=False,
+            request_params=request_params,
+            child_agents=agents,
+            plan_iterations=plan_iterations,
+            default=default,
+            api_key=api_key,
+        ),
+    )
+
+
 def router(
     self,
     name: str,
     *,
     agents: List[str],
-    instruction: Optional[str] = None,
+    instruction: Optional[str | Path | AnyUrl] = None,
     servers: List[str] = [],
     tools: Optional[Dict[str, List[str]]] = None,
     resources: Optional[Dict[str, List[str]]] = None,
@@ -400,6 +548,7 @@ def router(
     Returns:
         A decorator that registers the router with proper type annotations
     """
+    resolved_instruction = _resolve_instruction(instruction or ROUTING_SYSTEM_INSTRUCTION)
 
     return cast(
         "Callable[[AgentCallable[P, R]], DecoratedRouterProtocol[P, R]]",
@@ -407,7 +556,7 @@ def router(
             self,
             AgentType.ROUTER,
             name=name,
-            instruction=instruction or ROUTING_SYSTEM_INSTRUCTION,
+            instruction=resolved_instruction,
             servers=servers,
             model=model,
             use_history=use_history,
@@ -429,7 +578,7 @@ def chain(
     name: str,
     *,
     sequence: List[str],
-    instruction: Optional[str] = None,
+    instruction: Optional[str | Path | AnyUrl] = None,
     cumulative: bool = False,
     default: bool = False,
 ) -> Callable[[AgentCallable[P, R]], DecoratedChainProtocol[P, R]]:
@@ -456,6 +605,7 @@ def chain(
     You are a chain that processes requests through a series of specialized agents in sequence.
     Pass the output of each agent to the next agent in the chain.
     """
+    resolved_instruction = _resolve_instruction(instruction or default_instruction)
 
     return cast(
         "Callable[[AgentCallable[P, R]], DecoratedChainProtocol[P, R]]",
@@ -463,7 +613,7 @@ def chain(
             self,
             AgentType.CHAIN,
             name=name,
-            instruction=instruction or default_instruction,
+            instruction=resolved_instruction,
             sequence=sequence,
             cumulative=cumulative,
             default=default,
@@ -477,7 +627,7 @@ def parallel(
     *,
     fan_out: List[str],
     fan_in: str | None = None,
-    instruction: Optional[str] = None,
+    instruction: Optional[str | Path | AnyUrl] = None,
     include_request: bool = True,
     default: bool = False,
 ) -> Callable[[AgentCallable[P, R]], DecoratedParallelProtocol[P, R]]:
@@ -499,6 +649,7 @@ def parallel(
     You are a parallel processor that executes multiple agents simultaneously
     and aggregates their results.
     """
+    resolved_instruction = _resolve_instruction(instruction or default_instruction)
 
     return cast(
         "Callable[[AgentCallable[P, R]], DecoratedParallelProtocol[P, R]]",
@@ -506,7 +657,7 @@ def parallel(
             self,
             AgentType.PARALLEL,
             name=name,
-            instruction=instruction or default_instruction,
+            instruction=resolved_instruction,
             servers=[],  # Parallel agents don't connect to servers directly
             fan_in=fan_in,
             fan_out=fan_out,
@@ -522,7 +673,7 @@ def evaluator_optimizer(
     *,
     generator: str,
     evaluator: str,
-    instruction: Optional[str] = None,
+    instruction: Optional[str | Path | AnyUrl] = None,
     min_rating: str = "GOOD",
     max_refinements: int = 3,
     default: bool = False,
@@ -547,6 +698,7 @@ def evaluator_optimizer(
     evaluated for quality, and then refined based on specific feedback until
     it reaches an acceptable quality standard.
     """
+    resolved_instruction = _resolve_instruction(instruction or default_instruction)
 
     return cast(
         "Callable[[AgentCallable[P, R]], DecoratedEvaluatorOptimizerProtocol[P, R]]",
@@ -554,7 +706,7 @@ def evaluator_optimizer(
             self,
             AgentType.EVALUATOR_OPTIMIZER,
             name=name,
-            instruction=instruction or default_instruction,
+            instruction=resolved_instruction,
             servers=[],  # Evaluator-optimizer doesn't connect to servers directly
             generator=generator,
             evaluator=evaluator,

mcp_agent/core/direct_factory.py

@@ -10,6 +10,7 @@ from mcp_agent.agents.workflow.evaluator_optimizer import (
     EvaluatorOptimizerAgent,
     QualityRating,
 )
+from mcp_agent.agents.workflow.iterative_planner import IterativePlanner
 from mcp_agent.agents.workflow.orchestrator_agent import OrchestratorAgent
 from mcp_agent.agents.workflow.parallel_agent import ParallelAgent
 from mcp_agent.agents.workflow.router_agent import RouterAgent
@@ -21,9 +22,10 @@ from mcp_agent.event_progress import ProgressAction
 from mcp_agent.llm.augmented_llm import RequestParams
 from mcp_agent.llm.model_factory import ModelFactory
 from mcp_agent.logging.logger import get_logger
+from mcp_agent.mcp.interfaces import AgentProtocol
 
 # Type aliases for improved readability and IDE support
-AgentDict = Dict[str, Agent]
+AgentDict = Dict[str, AgentProtocol]
 AgentConfigDict = Dict[str, Dict[str, Any]]
 T = TypeVar("T")  # For generic types
 
@@ -153,7 +155,7 @@ async def create_agents_by_type(
                 await agent.attach_llm(
                     llm_factory,
                     request_params=config.default_request_params,
-                    api_key=config.api_key
+                    api_key=config.api_key,
                 )
                 result_agents[name] = agent
 
@@ -172,11 +174,11 @@ async def create_agents_by_type(
                 await agent.attach_llm(
                     llm_factory,
                     request_params=config.default_request_params,
-                    api_key=config.api_key
+                    api_key=config.api_key,
                 )
                 result_agents[name] = agent
 
-            elif agent_type == AgentType.ORCHESTRATOR:
+            elif agent_type == AgentType.ORCHESTRATOR or agent_type == AgentType.ITERATIVE_PLANNER:
                 # Get base params configured with model settings
                 base_params = (
                     config.default_request_params.model_copy()
@@ -193,24 +195,35 @@ async def create_agents_by_type(
                     agent = active_agents[agent_name]
                     child_agents.append(agent)
 
-                # Create the orchestrator
-                orchestrator = OrchestratorAgent(
-                    config=config,
-                    context=app_instance.context,
-                    agents=child_agents,
-                    plan_iterations=agent_data.get("plan_iterations", 5),
-                    plan_type=agent_data.get("plan_type", "full"),
-                )
+                if AgentType.ORCHESTRATOR == agent_type:
+                    # Create the orchestrator
+                    orchestrator = OrchestratorAgent(
+                        config=config,
+                        context=app_instance.context,
+                        agents=child_agents,
+                        plan_iterations=agent_data.get("plan_iterations", 5),
+                        plan_type=agent_data.get("plan_type", "full"),
+                    )
+                else:
+                    orchestrator = IterativePlanner(
+                        config=config,
+                        context=app_instance.context,
+                        agents=child_agents,
+                        plan_iterations=agent_data.get("plan_iterations", 5),
+                        plan_type=agent_data.get("plan_type", "full"),
+                    )
 
                 # Initialize the orchestrator
                 await orchestrator.initialize()
 
                 # Attach LLM to the orchestrator
                 llm_factory = model_factory_func(model=config.model)
+
+                #                print("************", config.default_request_params.instruction)
                 await orchestrator.attach_llm(
                     llm_factory,
                     request_params=config.default_request_params,
-                    api_key=config.api_key
+                    api_key=config.api_key,
                 )
 
                 result_agents[name] = orchestrator
@@ -274,7 +287,7 @@ async def create_agents_by_type(
                 await router.attach_llm(
                     llm_factory,
                     request_params=config.default_request_params,
-                    api_key=config.api_key
+                    api_key=config.api_key,
                 )
                 result_agents[name] = router
 
@@ -461,7 +474,6 @@ async def create_agents_in_dependency_order(
             )
             active_agents.update(evaluator_agents)
 
-        # Create orchestrator agents last since they might depend on other agents
         if AgentType.ORCHESTRATOR.value in [agents_dict[name]["type"] for name in group]:
             orchestrator_agents = await create_agents_by_type(
                 app_instance,
@@ -476,6 +488,21 @@ async def create_agents_in_dependency_order(
             )
             active_agents.update(orchestrator_agents)
 
+        # Create orchestrator2 agents last since they might depend on other agents
+        if AgentType.ITERATIVE_PLANNER.value in [agents_dict[name]["type"] for name in group]:
+            orchestrator2_agents = await create_agents_by_type(
+                app_instance,
+                {
+                    name: agents_dict[name]
+                    for name in group
+                    if agents_dict[name]["type"] == AgentType.ITERATIVE_PLANNER.value
+                },
+                AgentType.ITERATIVE_PLANNER,
+                active_agents,
+                model_factory_func,
+            )
+            active_agents.update(orchestrator2_agents)
+
     return active_agents
 
 

mcp_agent/core/fastagent.py

@@ -31,6 +31,9 @@ from mcp_agent.core.direct_decorators import (
 from mcp_agent.core.direct_decorators import (
     evaluator_optimizer as evaluator_optimizer_decorator,
 )
+from mcp_agent.core.direct_decorators import (
+    iterative_planner as orchestrator2_decorator,
+)
 from mcp_agent.core.direct_decorators import (
     orchestrator as orchestrator_decorator,
 )
@@ -249,6 +252,7 @@ class FastAgent:
     agent = agent_decorator
     custom = custom_decorator
     orchestrator = orchestrator_decorator
+    iterative_planner = orchestrator2_decorator
     router = router_decorator
     chain = chain_decorator
     parallel = parallel_decorator

mcp_agent/core/mermaid_utils.py

@@ -0,0 +1,170 @@
+"""Utilities for detecting and processing Mermaid diagrams in text content."""
+
+import base64
+import re
+import zlib
+from dataclasses import dataclass
+from typing import List, Optional
+
+# Mermaid chart viewer URL prefix
+MERMAID_VIEWER_URL = "https://www.mermaidchart.com/play#"
+# mermaid.live#pako= also works but the playground has better ux
+
+
+@dataclass
+class MermaidDiagram:
+    """Represents a detected Mermaid diagram."""
+
+    content: str
+    title: Optional[str] = None
+    start_pos: int = 0
+    end_pos: int = 0
+
+
+def extract_mermaid_diagrams(text: str) -> List[MermaidDiagram]:
+    """
+    Extract all Mermaid diagram blocks from text content.
+
+    Handles both simple mermaid blocks and blocks with titles:
+    - ```mermaid
+    - ```mermaid title={Some Title}
+
+    Also extracts titles from within the diagram content.
+
+    Args:
+        text: The text content to search for Mermaid diagrams
+
+    Returns:
+        List of MermaidDiagram objects found in the text
+    """
+    diagrams = []
+
+    # Pattern to match mermaid code blocks with optional title
+    # Matches: ```mermaid or ```mermaid title={...}
+    pattern = r"```mermaid(?:\s+title=\{([^}]+)\})?\s*\n(.*?)```"
+
+    for match in re.finditer(pattern, text, re.DOTALL):
+        title = match.group(1)  # May be None if no title
+        content = match.group(2).strip()
+
+        if content:  # Only add if there's actual diagram content
+            # If no title from code fence, look for title in the content
+            if not title:
+                # Look for various title patterns in mermaid diagrams
+                # pie title, graph title, etc.
+                title_patterns = [
+                    r"^\s*title\s+(.+?)(?:\n|$)",  # Generic title
+                    r"^\s*pie\s+title\s+(.+?)(?:\n|$)",  # Pie chart title
+                    r"^\s*gantt\s+title\s+(.+?)(?:\n|$)",  # Gantt chart title
+                ]
+
+                for title_pattern in title_patterns:
+                    title_match = re.search(title_pattern, content, re.MULTILINE)
+                    if title_match:
+                        title = title_match.group(1).strip()
+                        break
+
+            diagrams.append(
+                MermaidDiagram(
+                    content=content, title=title, start_pos=match.start(), end_pos=match.end()
+                )
+            )
+
+    return diagrams
+
+
+def create_mermaid_live_link(diagram_content: str) -> str:
+    """
+    Create a Mermaid Live Editor link from diagram content.
+
+    The link uses pako compression (zlib) and base64 encoding.
+
+    Args:
+        diagram_content: The Mermaid diagram source code
+
+    Returns:
+        Complete URL to Mermaid Live Editor
+    """
+    # Create the JSON structure expected by Mermaid Live
+    # Escape newlines and quotes in the diagram content
+    escaped_content = diagram_content.replace('"', '\\"').replace("\n", "\\n")
+    json_str = f'{{"code":"{escaped_content}","mermaid":{{"theme":"default"}},"updateEditor":false,"autoSync":true,"updateDiagram":false}}'
+
+    # Compress using zlib (pako compatible)
+    compressed = zlib.compress(json_str.encode("utf-8"))
+
+    # Base64 encode
+    encoded = base64.urlsafe_b64encode(compressed).decode("utf-8")
+
+    # Remove padding characters as Mermaid Live doesn't use them
+    encoded = encoded.rstrip("=")
+
+    return f"{MERMAID_VIEWER_URL}pako:{encoded}"
+
+
+def format_mermaid_links(diagrams: List[MermaidDiagram]) -> List[str]:
+    """
+    Format Mermaid diagrams as markdown links.
+
+    Args:
+        diagrams: List of MermaidDiagram objects
+
+    Returns:
+        List of formatted markdown strings
+    """
+    links = []
+
+    for i, diagram in enumerate(diagrams, 1):
+        link = create_mermaid_live_link(diagram.content)
+
+        if diagram.title:
+            # Use the title from the diagram with number
+            markdown = f"Diagram {i} - {diagram.title}: [Open Diagram]({link})"
+        else:
+            # Use generic numbering
+            markdown = f"Diagram {i}: [Open Diagram]({link})"
+
+        links.append(markdown)
+
+    return links
+
+
+def detect_diagram_type(content: str) -> str:
+    """
+    Detect the type of mermaid diagram from content.
+
+    Args:
+        content: The mermaid diagram source code
+
+    Returns:
+        Human-readable diagram type name
+    """
+    content_lower = content.strip().lower()
+
+    # Check for common diagram types
+    if content_lower.startswith(("graph ", "flowchart ")):
+        return "Flowchart"
+    elif content_lower.startswith("sequencediagram"):
+        return "Sequence"
+    elif content_lower.startswith("pie"):
+        return "Pie Chart"
+    elif content_lower.startswith("gantt"):
+        return "Gantt Chart"
+    elif content_lower.startswith("classdiagram"):
+        return "Class Diagram"
+    elif content_lower.startswith("statediagram"):
+        return "State Diagram"
+    elif content_lower.startswith("erdiagram"):
+        return "ER Diagram"
+    elif content_lower.startswith("journey"):
+        return "User Journey"
+    elif content_lower.startswith("gitgraph"):
+        return "Git Graph"
+    elif content_lower.startswith("c4context"):
+        return "C4 Context"
+    elif content_lower.startswith("mindmap"):
+        return "Mind Map"
+    elif content_lower.startswith("timeline"):
+        return "Timeline"
+    else:
+        return "Diagram"