fast-agent-mcp 0.3.10__py3-none-any.whl → 0.3.12__py3-none-any.whl

fast_agent/agents/llm_decorator.py

@@ -314,6 +314,13 @@ class LlmDecorator(AgentProtocol):
         # Otherwise treat the string as plain content (ignore arguments here)
         return await self.send(prompt)
 
+    def clear(self, *, clear_prompts: bool = False) -> None:
+        """Reset conversation state while optionally retaining applied prompt templates."""
+
+        if not self._llm:
+            return
+        self._llm.clear(clear_prompts=clear_prompts)
+
     async def structured(
         self,
         messages: Union[

fast_agent/agents/tool_agent.py

@@ -1,4 +1,4 @@
-from typing import Any, Callable, Dict, List
+from typing import Any, Callable, Dict, List, Sequence
 
 from mcp.server.fastmcp.tools.base import Tool as FastMCPTool
 from mcp.types import CallToolResult, ListToolsResult, Tool
@@ -35,7 +35,7 @@ class ToolAgent(LlmAgent):
     def __init__(
         self,
         config: AgentConfig,
-        tools: list[FastMCPTool | Callable] = [],
+        tools: Sequence[FastMCPTool | Callable] = [],
         context: Context | None = None,
     ) -> None:
         super().__init__(config=config, context=context)

fast_agent/cli/commands/quickstart.py

@@ -1,6 +1,8 @@
 """Bootstrap command to create example applications."""
 
 import shutil
+from dataclasses import dataclass
+from importlib.resources import files
 from pathlib import Path
 
 import typer
@@ -16,12 +18,27 @@ app = typer.Typer(
 )
 console = shared_console
 
-EXAMPLE_TYPES = {
-    "workflow": {
-        "description": "Example workflows, demonstrating each of the patterns in Anthropic's\n"
-        "'Building Effective Agents' paper. Some agents use the 'fetch'\n"
-        "and filesystem MCP Servers.",
-        "files": [
+
+BASE_EXAMPLES_DIR = files("fast_agent").joinpath("resources").joinpath("examples")
+
+
+@dataclass
+class ExampleConfig:
+    description: str
+    files: list[str]
+    create_subdir: bool
+    path_in_examples: list[str]
+    mount_point_files: list[str] | None = None
+
+
+_EXAMPLE_CONFIGS = {
+    "workflow": ExampleConfig(
+        description=(
+            "Example workflows, demonstrating each of the patterns in Anthropic's\n"
+            "'Building Effective Agents' paper. Some agents use the 'fetch'\n"
+            "and filesystem MCP Servers."
+        ),
+        files=[
             "chaining.py",
             "evaluator.py",
             "human_input.py",
@@ -31,41 +48,53 @@ EXAMPLE_TYPES = {
             "short_story.txt",
             "fastagent.config.yaml",
         ],
-        "create_subdir": True,
-    },
-    "researcher": {
-        "description": "Research agent example with additional evaluation/optimization\n"
-        "example. Uses Brave Search and Docker MCP Servers.\n"
-        "Creates examples in a 'researcher' subdirectory.",
-        "files": ["researcher.py", "researcher-eval.py", "fastagent.config.yaml"],
-        "create_subdir": True,
-    },
-    "data-analysis": {
-        "description": "Data analysis agent examples that demonstrate working with\n"
-        "datasets, performing statistical analysis, and generating visualizations.\n"
-        "Creates examples in a 'data-analysis' subdirectory with mount-point for data.\n"
-        "Uses MCP 'roots' feature for mapping",
-        "files": ["analysis.py", "fastagent.config.yaml"],
-        "mount_point_files": ["WA_Fn-UseC_-HR-Employee-Attrition.csv"],
-        "create_subdir": True,
-    },
-    "state-transfer": {
-        "description": "Example demonstrating state transfer between multiple agents.\n"
-        "Shows how state can be passed between agent runs to maintain context.\n"
-        "Creates examples in a 'state-transfer' subdirectory.",
-        "files": [
+        create_subdir=True,
+        path_in_examples=["workflows"],
+    ),
+    "researcher": ExampleConfig(
+        description=(
+            "Research agent example with additional evaluation/optimization\n"
+            "example. Uses Brave Search and Docker MCP Servers.\n"
+            "Creates examples in a 'researcher' subdirectory."
+        ),
+        files=["researcher.py", "researcher-eval.py", "fastagent.config.yaml"],
+        create_subdir=True,
+        path_in_examples=["researcher"],
+    ),
+    "data-analysis": ExampleConfig(
+        description=(
+            "Data analysis agent examples that demonstrate working with\n"
+            "datasets, performing statistical analysis, and generating visualizations.\n"
+            "Creates examples in a 'data-analysis' subdirectory with mount-point for data.\n"
+            "Uses MCP 'roots' feature for mapping"
+        ),
+        files=["analysis.py", "fastagent.config.yaml"],
+        mount_point_files=["WA_Fn-UseC_-HR-Employee-Attrition.csv"],
+        create_subdir=True,
+        path_in_examples=["data-analysis"],
+    ),
+    "state-transfer": ExampleConfig(
+        description=(
+            "Example demonstrating state transfer between multiple agents.\n"
+            "Shows how state can be passed between agent runs to maintain context.\n"
+            "Creates examples in a 'state-transfer' subdirectory."
+        ),
+        files=[
             "agent_one.py",
             "agent_two.py",
             "fastagent.config.yaml",
             "fastagent.secrets.yaml.example",
         ],
-        "create_subdir": True,
-    },
-    "elicitations": {
-        "description": "Interactive form examples using MCP elicitations feature.\n"
-        "Demonstrates collecting structured data with forms, AI-guided workflows,\n"
-        "and custom handlers. Creates examples in an 'elicitations' subdirectory.",
-        "files": [
+        create_subdir=True,
+        path_in_examples=["mcp", "state-transfer"],
+    ),
+    "elicitations": ExampleConfig(
+        description=(
+            "Interactive form examples using MCP elicitations feature.\n"
+            "Demonstrates collecting structured data with forms, AI-guided workflows,\n"
+            "and custom handlers. Creates examples in an 'elicitations' subdirectory."
+        ),
+        files=[
             "elicitation_account_server.py",
             "elicitation_forms_server.py",
             "elicitation_game_server.py",
@@ -76,13 +105,16 @@ EXAMPLE_TYPES = {
             "game_character_handler.py",
             "tool_call.py",
         ],
-        "create_subdir": True,
-    },
-    "tensorzero": {
-        "description": "A complete example showcasing the TensorZero integration.\n"
-        "Includes the T0 Gateway, an MCP server, an interactive agent, and \n"
-        "multi-modal functionality.",
-        "files": [
+        create_subdir=True,
+        path_in_examples=["mcp", "elicitations"],
+    ),
+    "tensorzero": ExampleConfig(
+        description=(
+            "A complete example showcasing the TensorZero integration.\n"
+            "Includes the T0 Gateway, an MCP server, an interactive agent, and \n"
+            "multi-modal functionality."
+        ),
+        files=[
             ".env.sample",
             "Makefile",
             "README.md",
@@ -93,105 +125,64 @@ EXAMPLE_TYPES = {
             "simple_agent.py",
             "mcp_server/",
             "demo_images/",
-            "tensorzero_config/"
+            "tensorzero_config/",
         ],
-        "create_subdir": True,
-    },
+        create_subdir=True,
+        path_in_examples=["elicitations"],
+    ),
 }
 
 
+def _development_mode_fallback(example_info: ExampleConfig) -> Path:
+    """Fallback function for development mode."""
+    package_dir = Path(__file__).parent.parent.parent.parent.parent
+    for dir in example_info.path_in_examples:
+        package_dir = package_dir / dir
+    console.print(f"[blue]Using development directory: {package_dir}[/blue]")
+    return package_dir
+
+
 def copy_example_files(example_type: str, target_dir: Path, force: bool = False) -> list[str]:
     """Copy example files from resources to target directory."""
-    created = []
-
     # Determine if we should create a subdirectory for this example type
-    example_info = EXAMPLE_TYPES[example_type]
-    if example_info["create_subdir"]:
+    example_info = _EXAMPLE_CONFIGS.get(example_type, None)
+    if example_info is None:
+        console.print(f"Example type '{example_type}' not found.")
+        return []
+
+    if example_info.create_subdir:
         target_dir = target_dir / example_type
         if not target_dir.exists():
             target_dir.mkdir(parents=True)
             console.print(f"Created subdirectory: {target_dir}")
 
-    # Create mount-point directory if needed
-    mount_point_files = example_info.get("mount_point_files", [])
-    if mount_point_files:
-        mount_point_dir = target_dir / "mount-point"
-        if not mount_point_dir.exists():
-            mount_point_dir.mkdir(parents=True)
-            console.print(f"Created mount-point directory: {mount_point_dir}")
-
     # Try to use examples from the installed package first, or fall back to the top-level directory
-    from importlib.resources import files
-
     try:
         # First try to find examples in the package resources
-        if example_type == "state-transfer":
-            # The state-transfer example is in the mcp subdirectory
-            source_dir = (
-                files("fast_agent")
-                .joinpath("resources")
-                .joinpath("examples")
-                .joinpath("mcp")
-                .joinpath("state-transfer")
-            )
-        elif example_type == "elicitations":
-            # The elicitations example is in the mcp subdirectory
-            source_dir = (
-                files("fast_agent")
-                .joinpath("resources")
-                .joinpath("examples")
-                .joinpath("mcp")
-                .joinpath("elicitations")
-            )
-        else:
-            # Other examples are at the top level of examples
-            source_dir = (
-                files("fast_agent")
-                .joinpath("resources")
-                .joinpath("examples")
-                .joinpath("workflows" if example_type == "workflow" else f"{example_type}")
-            )
+        source_dir = BASE_EXAMPLES_DIR
+        for dir in example_info.path_in_examples:
+            source_dir = source_dir.joinpath(dir)
 
         # Check if we found a valid directory
         if not source_dir.is_dir():
             console.print(
-                f"[yellow]Resource directory not found: {source_dir}. Falling back to development mode.[/yellow]"
+                f"[yellow]Resource directory not found: {source_dir}. "
+                "Falling back to development mode.[/yellow]"
             )
             # Fall back to the top-level directory for development mode
-            package_dir = Path(__file__).parent.parent.parent.parent.parent
-            if example_type == "state-transfer":
-                source_dir = package_dir / "examples" / "mcp" / "state-transfer"
-            elif example_type == "elicitations":
-                source_dir = package_dir / "examples" / "mcp" / "elicitations"
-            else:
-                source_dir = (
-                    package_dir
-                    / "examples"
-                    / ("workflows" if example_type == "workflow" else f"{example_type}")
-                )
-            console.print(f"[blue]Using development directory: {source_dir}[/blue]")
+            source_dir = _development_mode_fallback(example_info)
     except (ImportError, ModuleNotFoundError, ValueError) as e:
         console.print(
             f"[yellow]Error accessing resources: {e}. Falling back to development mode.[/yellow]"
         )
-        # Fall back to the top-level directory if the resource finding fails
-        package_dir = Path(__file__).parent.parent.parent.parent.parent
-        if example_type == "state-transfer":
-            source_dir = package_dir / "examples" / "mcp" / "state-transfer"
-        elif example_type == "elicitations":
-            source_dir = package_dir / "examples" / "mcp" / "elicitations"
-        else:
-            source_dir = (
-                package_dir
-                / "examples"
-                / ("workflows" if example_type == "workflow" else f"{example_type}")
-            )
+        source_dir = _development_mode_fallback(example_info)
 
     if not source_dir.exists():
         console.print(f"[red]Error: Source directory not found: {source_dir}[/red]")
-        return created
+        return []
 
-    for filename in example_info["files"]:
+    created = []
+    for filename in example_info.files:
         source = source_dir / filename
         target = target_dir / filename
 
@@ -213,16 +204,23 @@ def copy_example_files(example_type: str, target_dir: Path, force: bool = False)
                 rel_path = f"{example_type}/{filename}"
 
             created.append(rel_path)
-            console.print(f"[green]Created[/green] {created[-1]}")
+            console.print(f"[green]Created[/green] {rel_path}")
 
         except Exception as e:
             console.print(f"[red]Error copying {filename}: {str(e)}[/red]")
 
     # Copy mount-point files if any
+    mount_point_files = example_info.mount_point_files or []
     if mount_point_files:
-        source_mount_point = source_dir / "mount-point"
+        mount_point_dir = target_dir / "mount-point"
+
+        # Create mount-point directory if needed
+        if not mount_point_dir.exists():
+            mount_point_dir.mkdir(parents=True)
+            console.print(f"Created mount-point directory: {mount_point_dir}")
+
         for filename in mount_point_files:
-            source = source_mount_point / filename
+            source = source_dir / "mount-point" / filename
             target = mount_point_dir / filename
 
             try:
@@ -253,10 +251,14 @@ def copy_project_template(source_dir: Path, dest_dir: Path, console: Console, fo
     """
     if dest_dir.exists():
         if force:
-            console.print(f"[yellow]--force specified. Removing existing directory: {dest_dir}[/yellow]")
+            console.print(
+                f"[yellow]--force specified. Removing existing directory: {dest_dir}[/yellow]"
+            )
             shutil.rmtree(dest_dir)
         else:
-            console.print(f"[bold yellow]Directory '{dest_dir.name}' already exists.[/bold yellow] Use --force to overwrite.")
+            console.print(
+                f"[bold yellow]Directory '{dest_dir.name}' already exists.[/bold yellow] Use --force to overwrite."
+            )
             return False
 
     try:
@@ -278,14 +280,14 @@ def show_overview() -> None:
     table.add_column("Description")
     table.add_column("Files")
 
-    for name, info in EXAMPLE_TYPES.items():
+    for name, info in _EXAMPLE_CONFIGS.items():
         # Just show file count instead of listing all files
-        file_count = len(info["files"])
+        file_count = len(info.files)
         files_summary = f"{file_count} files"
-        if "mount_point_files" in info:
-            mount_count = len(info["mount_point_files"])
-            files_summary += f"\n+ {mount_count} data files"
-        table.add_row(f"[green]{name}[/green]", info["description"], files_summary)
+        mount_files = info.mount_point_files
+        if mount_files:
+            files_summary += f"\n+ {len(mount_files)} data files"
+        table.add_row(f"[green]{name}[/green]", info.description, files_summary)
 
     console.print(table)
 
@@ -445,7 +447,9 @@ def tensorzero(
         Path("."),
         help="Directory where the 'tensorzero' project folder will be created.",
     ),
-    force: bool = typer.Option(False, "--force", "-f", help="Force overwrite if project directory exists"),
+    force: bool = typer.Option(
+        False, "--force", "-f", help="Force overwrite if project directory exists"
+    ),
 ):
     """Create the TensorZero project example."""
     console.print("[bold green]Setting up the TensorZero quickstart example...[/bold green]")
@@ -454,13 +458,18 @@ def tensorzero(
 
     # --- Find Source Directory ---
     from importlib.resources import files
+
     try:
         # This path MUST match the "to" path from hatch_build.py
-        source_dir = files("fast_agent").joinpath("resources").joinpath("examples").joinpath("tensorzero")
+        source_dir = (
+            files("fast_agent").joinpath("resources").joinpath("examples").joinpath("tensorzero")
+        )
         if not source_dir.is_dir():
             raise FileNotFoundError  # Fallback to dev mode if resource isn't a dir
     except (ImportError, ModuleNotFoundError, FileNotFoundError):
-        console.print("[yellow]Package resources not found. Falling back to development mode.[/yellow]")
+        console.print(
+            "[yellow]Package resources not found. Falling back to development mode.[/yellow]"
+        )
         # This path is relative to the project root in a development environment
         source_dir = Path(__file__).parent.parent.parent.parent / "examples" / "tensorzero"
 
@@ -486,7 +495,9 @@ def tensorzero(
             "   [dim]Then, open the new '.env' file and add your OpenAI or Anthropic API key.[/dim]"
         )
 
-        console.print("\n3. [bold]Start the required services (TensorZero Gateway & MCP Server):[/bold]")
+        console.print(
+            "\n3. [bold]Start the required services (TensorZero Gateway & MCP Server):[/bold]"
+        )
         console.print("   [cyan]docker compose up --build -d[/cyan]")
         console.print(
             "   [dim](This builds and starts the necessary containers in the background)[/dim]"
@@ -499,7 +510,9 @@ def tensorzero(
 
 @app.command(name="t0", help="Alias for the TensorZero quickstart.", hidden=True)
 def t0_alias(
-    directory: Path = typer.Argument(Path("."), help="Directory for the 'tensorzero' project folder."),
+    directory: Path = typer.Argument(
+        Path("."), help="Directory for the 'tensorzero' project folder."
+    ),
     force: bool = typer.Option(False, "--force", "-f", help="Force overwrite"),
 ):
     """Alias for the `tensorzero` command."""

fast_agent/config.py

@@ -43,8 +43,8 @@ class MCPSamplingSettings(BaseModel):
 
 
 class MCPElicitationSettings(BaseModel):
-    mode: Literal["forms", "auto_cancel", "none"] = "none"
-    """Elicitation mode: 'forms' (default UI), 'auto_cancel', 'none' (no capability)"""
+    mode: Literal["forms", "auto-cancel", "none"] = "none"
+    """Elicitation mode: 'forms' (default UI), 'auto-cancel', 'none' (no capability)"""
 
     model_config = ConfigDict(extra="allow", arbitrary_types_allowed=True)
 

fast_agent/core/direct_decorators.py

@@ -4,9 +4,10 @@ These decorators provide type-safe function signatures and IDE support
 for creating agents in the DirectFastAgent framework.
 """
 
-from functools import wraps
+from collections.abc import Coroutine
 from pathlib import Path
 from typing import (
+    Any,
     Awaitable,
     Callable,
     Dict,
@@ -16,7 +17,6 @@ from typing import (
     ParamSpec,
     Protocol,
     TypeVar,
-    cast,
 )
 
 from mcp.client.session import ElicitationFnT
@@ -33,9 +33,6 @@ from fast_agent.types import RequestParams
 P = ParamSpec("P")  # Parameters
 R = TypeVar("R", covariant=True)  # Return type
 
-# Type for agent functions - can be either async or sync
-AgentCallable = Callable[P, Awaitable[R]]
-
 
 # Protocol for decorated agent functions
 class DecoratedAgentProtocol(Protocol[P, R]):
@@ -186,7 +183,7 @@ def _decorator_impl(
     resources: Optional[Dict[str, List[str]]] = None,
     prompts: Optional[Dict[str, List[str]]] = None,
     **extra_kwargs,
-) -> Callable[[AgentCallable[P, R]], AgentCallable[P, R]]:
+) -> Callable[[Callable[P, Coroutine[Any, Any, R]]], Callable[P, Coroutine[Any, Any, R]]]:
     """
     Core implementation for agent decorators with common behavior and type safety.
 
@@ -203,12 +200,7 @@ def _decorator_impl(
         **extra_kwargs: Additional agent/workflow-specific parameters
     """
 
-    def decorator(func: AgentCallable[P, R]) -> AgentCallable[P, R]:
-        @wraps(func)
-        def wrapper(*args: P.args, **kwargs: P.kwargs) -> Awaitable[R]:
-            # Call the original function
-            return func(*args, **kwargs)
-
+    def decorator(func: Callable[P, Coroutine[Any, Any, R]]) -> Callable[P, Coroutine[Any, Any, R]]:
         # Create agent configuration
         config = AgentConfig(
             name=name,
@@ -229,7 +221,7 @@ def _decorator_impl(
         if request_params:
             config.default_request_params = request_params
 
-        # Store metadata on the wrapper function
+        # Store metadata in the registry
         agent_data = {
             "config": config,
             "type": agent_type.value,
@@ -243,13 +235,13 @@ def _decorator_impl(
         # Store the configuration in the FastAgent instance
         self.agents[name] = agent_data
 
-        # Store type information for IDE support
-        setattr(wrapper, "_agent_type", agent_type)
-        setattr(wrapper, "_agent_config", config)
+        # Store type information on the function for IDE support
+        setattr(func, "_agent_type", agent_type)
+        setattr(func, "_agent_config", config)
         for key, value in extra_kwargs.items():
-            setattr(wrapper, f"_{key}", value)
+            setattr(func, f"_{key}", value)
 
-        return cast("AgentCallable[P, R]", wrapper)
+        return func
 
     return decorator
 
@@ -271,7 +263,7 @@ def agent(
     default: bool = False,
     elicitation_handler: Optional[ElicitationFnT] = None,
     api_key: str | None = None,
-) -> Callable[[AgentCallable[P, R]], AgentCallable[P, R]]:
+) -> Callable[[Callable[P, Coroutine[Any, Any, R]]], Callable[P, Coroutine[Any, Any, R]]]:
     """
     Decorator to create and register a standard agent with type-safe signature.
 
@@ -336,7 +328,7 @@ def custom(
     default: bool = False,
     elicitation_handler: Optional[ElicitationFnT] = None,
     api_key: str | None = None,
-) -> Callable[[AgentCallable[P, R]], AgentCallable[P, R]]:
+) -> Callable[[Callable[P, Coroutine[Any, Any, R]]], Callable[P, Coroutine[Any, Any, R]]]:
     """
     Decorator to create and register a standard agent with type-safe signature.
 
@@ -400,7 +392,7 @@ def orchestrator(
     plan_iterations: int = 5,
     default: bool = False,
     api_key: str | None = None,
-) -> Callable[[AgentCallable[P, R]], AgentCallable[P, R]]:
+) -> Callable[[Callable[P, Coroutine[Any, Any, R]]], Callable[P, Coroutine[Any, Any, R]]]:
     """
     Decorator to create and register an orchestrator agent with type-safe signature.
 
@@ -452,7 +444,7 @@ def iterative_planner(
     plan_iterations: int = -1,
     default: bool = False,
     api_key: str | None = None,
-) -> Callable[[AgentCallable[P, R]], AgentCallable[P, R]]:
+) -> Callable[[Callable[P, Coroutine[Any, Any, R]]], Callable[P, Coroutine[Any, Any, R]]]:
     """
     Decorator to create and register an orchestrator agent with type-safe signature.
 
@@ -510,7 +502,7 @@ def router(
         ElicitationFnT
     ] = None,  ## exclude from docs, decide whether allowable
     api_key: str | None = None,
-) -> Callable[[AgentCallable[P, R]], AgentCallable[P, R]]:
+) -> Callable[[Callable[P, Coroutine[Any, Any, R]]], Callable[P, Coroutine[Any, Any, R]]]:
     """
     Decorator to create and register a router agent with type-safe signature.
 
@@ -558,7 +550,7 @@ def chain(
     instruction: Optional[str | Path | AnyUrl] = None,
     cumulative: bool = False,
     default: bool = False,
-) -> Callable[[AgentCallable[P, R]], AgentCallable[P, R]]:
+) -> Callable[[Callable[P, Coroutine[Any, Any, R]]], Callable[P, Coroutine[Any, Any, R]]]:
     """
     Decorator to create and register a chain agent with type-safe signature.
 
@@ -604,7 +596,7 @@ def parallel(
     instruction: Optional[str | Path | AnyUrl] = None,
     include_request: bool = True,
     default: bool = False,
-) -> Callable[[AgentCallable[P, R]], AgentCallable[P, R]]:
+) -> Callable[[Callable[P, Coroutine[Any, Any, R]]], Callable[P, Coroutine[Any, Any, R]]]:
     """
     Decorator to create and register a parallel agent with type-safe signature.
 
@@ -648,7 +640,7 @@ def evaluator_optimizer(
     min_rating: str = "GOOD",
     max_refinements: int = 3,
     default: bool = False,
-) -> Callable[[AgentCallable[P, R]], AgentCallable[P, R]]:
+) -> Callable[[Callable[P, Coroutine[Any, Any, R]]], Callable[P, Coroutine[Any, Any, R]]]:
     """
     Decorator to create and register an evaluator-optimizer agent with type-safe signature.
 

fast_agent/core/fastagent.py

@@ -268,6 +268,7 @@ class FastAgent:
     # Decorator methods with precise signatures for IDE completion
     # Provide annotations so IDEs can discover these attributes on instances
     if TYPE_CHECKING:  # pragma: no cover - typing aid only
+        from collections.abc import Coroutine
         from pathlib import Path
 
         from fast_agent.types import RequestParams
@@ -292,7 +293,7 @@ class FastAgent:
             default: bool = False,
             elicitation_handler: Optional[ElicitationFnT] = None,
             api_key: str | None = None,
-        ) -> Callable[[Callable[P, Awaitable[R]]], Callable[P, Awaitable[R]]]: ...
+        ) -> Callable[[Callable[P, Coroutine[Any, Any, R]]], Callable[P, Coroutine[Any, Any, R]]]: ...
 
         def custom(
             self,