fast-agent-mcp 0.2.44__py3-none-any.whl → 0.2.46__py3-none-any.whl

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,12 @@ 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.router_agent import (
+    ROUTING_SYSTEM_INSTRUCTION,
+)
 from mcp_agent.core.agent_types import AgentType
 from mcp_agent.core.request_params import RequestParams
 
@@ -82,6 +87,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,
@@ -180,9 +270,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,
@@ -217,7 +307,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,
@@ -242,9 +335,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,
@@ -274,7 +367,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,
@@ -308,7 +404,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,
@@ -338,6 +434,7 @@ def orchestrator(
     """
 
     # Create final request params with plan_iterations
+    resolved_instruction = _resolve_instruction(instruction)
 
     return cast(
         "Callable[[AgentCallable[P, R]], DecoratedOrchestratorProtocol[P, R]]",
@@ -345,7 +442,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,
@@ -365,7 +462,7 @@ def router(
     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,
@@ -397,10 +494,7 @@ def router(
     Returns:
         A decorator that registers the router with proper type annotations
     """
-    default_instruction = """
-    You are a router that determines which specialized agent should handle a given query.
-    Analyze the query and select the most appropriate agent to handle it.
-    """
+    resolved_instruction = _resolve_instruction(instruction or ROUTING_SYSTEM_INSTRUCTION)
 
     return cast(
         "Callable[[AgentCallable[P, R]], DecoratedRouterProtocol[P, R]]",
@@ -408,7 +502,7 @@ def router(
             self,
             AgentType.ROUTER,
             name=name,
-            instruction=instruction or default_instruction,
+            instruction=resolved_instruction,
             servers=servers,
             model=model,
             use_history=use_history,
@@ -430,7 +524,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]]:
@@ -457,6 +551,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]]",
@@ -464,7 +559,7 @@ def chain(
             self,
             AgentType.CHAIN,
             name=name,
-            instruction=instruction or default_instruction,
+            instruction=resolved_instruction,
             sequence=sequence,
             cumulative=cumulative,
             default=default,
@@ -478,7 +573,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]]:
@@ -500,6 +595,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]]",
@@ -507,7 +603,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,
@@ -523,7 +619,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,
@@ -548,6 +644,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]]",
@@ -555,7 +652,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/enhanced_prompt.py

@@ -511,13 +511,12 @@ def create_keybindings(on_toggle_multiline=None, app=None, agent_provider=None,
                             rich_print("\n[green]✓ Copied to clipboard[/green]")
                             return
 
-                    rich_print("\n[yellow]No assistant messages found[/yellow]")
                 else:
-                    rich_print("\n[yellow]No message history available[/yellow]")
-            except Exception as e:
-                rich_print(f"\n[red]Error copying: {e}[/red]")
+                    pass
+            except Exception:
+                pass
         else:
-            rich_print("[yellow]Clipboard copy not available in this context[/yellow]")
+            pass
 
     return kb
 

mcp_agent/human_input/__init__.py

@@ -0,0 +1,50 @@
+"""Human input modules for forms and elicitation."""
+
+# Export the simple form API
+# Export field types and schema builder
+from mcp_agent.human_input.form_fields import (
+    BooleanField,
+    EnumField,
+    FormSchema,
+    IntegerField,
+    NumberField,
+    # Field classes
+    StringField,
+    boolean,
+    choice,
+    date,
+    datetime,
+    email,
+    integer,
+    number,
+    # Convenience functions
+    string,
+    url,
+)
+from mcp_agent.human_input.simple_form import ask, ask_sync, form, form_sync
+
+__all__ = [
+    # Form functions
+    "form",
+    "form_sync",
+    "ask",
+    "ask_sync",
+    # Schema builder
+    "FormSchema",
+    # Field classes
+    "StringField",
+    "IntegerField",
+    "NumberField",
+    "BooleanField",
+    "EnumField",
+    # Field convenience functions
+    "string",
+    "email",
+    "url",
+    "date",
+    "datetime",
+    "integer",
+    "number",
+    "boolean",
+    "choice",
+]

mcp_agent/human_input/elicitation_form.py

@@ -5,6 +5,7 @@ from typing import Any, Dict, Optional
 
 from mcp.types import ElicitRequestedSchema
 from prompt_toolkit import Application
+from prompt_toolkit.application.current import get_app
 from prompt_toolkit.buffer import Buffer
 from prompt_toolkit.filters import Condition
 from prompt_toolkit.formatted_text import FormattedText
@@ -272,29 +273,32 @@ class ElicitationForm:
             keep_focused_window_visible=True,
         )
 
-        # Create title bar manually
-        title_bar = Window(
-            FormattedTextControl(FormattedText([("class:title", "Elicitation Request")])),
-            height=1,
-            style="class:dialog.title",
-        )
-
-        # Combine title, sticky headers, and scrollable content
+        # Combine sticky headers and scrollable content (no separate title bar needed)
         full_content = HSplit(
             [
-                title_bar,
-                Window(height=1),  # Spacing after title
+                Window(height=1),  # Top spacing
                 sticky_headers,  # Headers stay fixed at top
                 scrollable_content,  # Form fields can scroll
             ]
         )
 
-        # Create dialog frame manually to avoid Dialog's internal scrolling
+        # Create dialog frame with title
         dialog = Frame(
             body=full_content,
+            title="Elicitation Request",
             style="class:dialog",
         )
 
+        # Apply width constraints by putting Frame in VSplit with flexible spacers
+        # This prevents console display interference and constrains the Frame border
+        constrained_dialog = VSplit(
+            [
+                Window(width=10),  # Smaller left spacer
+                dialog,
+                Window(width=10),  # Smaller right spacer
+            ]
+        )
+
         # Key bindings
         kb = KeyBindings()
 
@@ -370,7 +374,7 @@ class ElicitationForm:
         # Add toolbar to the layout
         root_layout = HSplit(
             [
-                dialog,  # The main dialog
+                constrained_dialog,  # The width-constrained dialog
                 self._toolbar_window,
             ]
         )
@@ -588,7 +592,6 @@ class ElicitationForm:
 
     def _is_in_multiline_field(self) -> bool:
         """Check if currently focused field is a multiline field."""
-        from prompt_toolkit.application.current import get_app
 
         focused = get_app().layout.current_control
 

mcp_agent/human_input/form_fields.py

@@ -0,0 +1,252 @@
+"""High-level field types for elicitation forms with default support."""
+
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional, Union
+
+
+@dataclass
+class StringField:
+    """String field with validation and default support."""
+
+    title: Optional[str] = None
+    description: Optional[str] = None
+    default: Optional[str] = None
+    min_length: Optional[int] = None
+    max_length: Optional[int] = None
+    format: Optional[str] = None  # email, uri, date, date-time
+
+    def to_schema(self) -> Dict[str, Any]:
+        """Convert to MCP elicitation schema format."""
+        schema: Dict[str, Any] = {"type": "string"}
+
+        if self.title:
+            schema["title"] = self.title
+        if self.description:
+            schema["description"] = self.description
+        if self.default is not None:
+            schema["default"] = self.default
+        if self.min_length is not None:
+            schema["minLength"] = self.min_length
+        if self.max_length is not None:
+            schema["maxLength"] = self.max_length
+        if self.format:
+            schema["format"] = self.format
+
+        return schema
+
+
+@dataclass
+class IntegerField:
+    """Integer field with validation and default support."""
+
+    title: Optional[str] = None
+    description: Optional[str] = None
+    default: Optional[int] = None
+    minimum: Optional[int] = None
+    maximum: Optional[int] = None
+
+    def to_schema(self) -> Dict[str, Any]:
+        """Convert to MCP elicitation schema format."""
+        schema: Dict[str, Any] = {"type": "integer"}
+
+        if self.title:
+            schema["title"] = self.title
+        if self.description:
+            schema["description"] = self.description
+        if self.default is not None:
+            schema["default"] = self.default
+        if self.minimum is not None:
+            schema["minimum"] = self.minimum
+        if self.maximum is not None:
+            schema["maximum"] = self.maximum
+
+        return schema
+
+
+@dataclass
+class NumberField:
+    """Number (float) field with validation and default support."""
+
+    title: Optional[str] = None
+    description: Optional[str] = None
+    default: Optional[float] = None
+    minimum: Optional[float] = None
+    maximum: Optional[float] = None
+
+    def to_schema(self) -> Dict[str, Any]:
+        """Convert to MCP elicitation schema format."""
+        schema: Dict[str, Any] = {"type": "number"}
+
+        if self.title:
+            schema["title"] = self.title
+        if self.description:
+            schema["description"] = self.description
+        if self.default is not None:
+            schema["default"] = self.default
+        if self.minimum is not None:
+            schema["minimum"] = self.minimum
+        if self.maximum is not None:
+            schema["maximum"] = self.maximum
+
+        return schema
+
+
+@dataclass
+class BooleanField:
+    """Boolean field with default support."""
+
+    title: Optional[str] = None
+    description: Optional[str] = None
+    default: Optional[bool] = None
+
+    def to_schema(self) -> Dict[str, Any]:
+        """Convert to MCP elicitation schema format."""
+        schema: Dict[str, Any] = {"type": "boolean"}
+
+        if self.title:
+            schema["title"] = self.title
+        if self.description:
+            schema["description"] = self.description
+        if self.default is not None:
+            schema["default"] = self.default
+
+        return schema
+
+
+@dataclass
+class EnumField:
+    """Enum/choice field with default support."""
+
+    choices: List[str]
+    choice_names: Optional[List[str]] = None  # Human-readable names
+    title: Optional[str] = None
+    description: Optional[str] = None
+    default: Optional[str] = None
+
+    def to_schema(self) -> Dict[str, Any]:
+        """Convert to MCP elicitation schema format."""
+        schema: Dict[str, Any] = {"type": "string", "enum": self.choices}
+
+        if self.title:
+            schema["title"] = self.title
+        if self.description:
+            schema["description"] = self.description
+        if self.default is not None:
+            schema["default"] = self.default
+        if self.choice_names:
+            schema["enumNames"] = self.choice_names
+
+        return schema
+
+
+# Field type union
+FieldType = Union[StringField, IntegerField, NumberField, BooleanField, EnumField]
+
+
+class FormSchema:
+    """High-level form schema builder."""
+
+    def __init__(self, **fields: FieldType):
+        """Create a form schema with named fields."""
+        self.fields = fields
+        self._required_fields: List[str] = []
+
+    def required(self, *field_names: str) -> "FormSchema":
+        """Mark fields as required."""
+        self._required_fields.extend(field_names)
+        return self
+
+    def to_schema(self) -> Dict[str, Any]:
+        """Convert to MCP ElicitRequestedSchema format."""
+        properties = {}
+
+        for field_name, field in self.fields.items():
+            properties[field_name] = field.to_schema()
+
+        schema: Dict[str, Any] = {"type": "object", "properties": properties}
+
+        if self._required_fields:
+            schema["required"] = self._required_fields
+
+        return schema
+
+
+# Convenience functions for creating fields
+def string(
+    title: Optional[str] = None,
+    description: Optional[str] = None,
+    default: Optional[str] = None,
+    min_length: Optional[int] = None,
+    max_length: Optional[int] = None,
+    format: Optional[str] = None,
+) -> StringField:
+    """Create a string field."""
+    return StringField(title, description, default, min_length, max_length, format)
+
+
+def email(
+    title: Optional[str] = None, description: Optional[str] = None, default: Optional[str] = None
+) -> StringField:
+    """Create an email field."""
+    return StringField(title, description, default, format="email")
+
+
+def url(
+    title: Optional[str] = None, description: Optional[str] = None, default: Optional[str] = None
+) -> StringField:
+    """Create a URL field."""
+    return StringField(title, description, default, format="uri")
+
+
+def date(
+    title: Optional[str] = None, description: Optional[str] = None, default: Optional[str] = None
+) -> StringField:
+    """Create a date field."""
+    return StringField(title, description, default, format="date")
+
+
+def datetime(
+    title: Optional[str] = None, description: Optional[str] = None, default: Optional[str] = None
+) -> StringField:
+    """Create a datetime field."""
+    return StringField(title, description, default, format="date-time")
+
+
+def integer(
+    title: Optional[str] = None,
+    description: Optional[str] = None,
+    default: Optional[int] = None,
+    minimum: Optional[int] = None,
+    maximum: Optional[int] = None,
+) -> IntegerField:
+    """Create an integer field."""
+    return IntegerField(title, description, default, minimum, maximum)
+
+
+def number(
+    title: Optional[str] = None,
+    description: Optional[str] = None,
+    default: Optional[float] = None,
+    minimum: Optional[float] = None,
+    maximum: Optional[float] = None,
+) -> NumberField:
+    """Create a number field."""
+    return NumberField(title, description, default, minimum, maximum)
+
+
+def boolean(
+    title: Optional[str] = None, description: Optional[str] = None, default: Optional[bool] = None
+) -> BooleanField:
+    """Create a boolean field."""
+    return BooleanField(title, description, default)
+
+
+def choice(
+    choices: List[str],
+    choice_names: Optional[List[str]] = None,
+    title: Optional[str] = None,
+    description: Optional[str] = None,
+    default: Optional[str] = None,
+) -> EnumField:
+    """Create a choice/enum field."""
+    return EnumField(choices, choice_names, title, description, default)