fast-agent-mcp 0.3.2__py3-none-any.whl → 0.3.4__py3-none-any.whl

fast_agent/__init__.py

@@ -1,5 +1,6 @@
 """fast-agent - An MCP native agent application framework"""
-from typing import TYPE_CHECKING as _TYPE_CHECKING
+
+from typing import TYPE_CHECKING
 
 # Configuration and settings (safe - pure Pydantic models)
 from fast_agent.config import (
@@ -73,10 +74,12 @@ def __getattr__(name: str):
 
         return ToolAgent
     elif name == "McpAgent":
+        # Import directly from submodule to avoid package re-import cycles
         from fast_agent.agents.mcp_agent import McpAgent
 
         return McpAgent
     elif name == "FastAgent":
+        # Import from the canonical implementation to avoid recursive imports
         from fast_agent.core.fastagent import FastAgent
 
         return FastAgent
@@ -85,7 +88,8 @@ def __getattr__(name: str):
 
 
 # Help static analyzers/IDEs resolve symbols and signatures without importing at runtime.
-if _TYPE_CHECKING:  # pragma: no cover - typing aid only
+if TYPE_CHECKING:  # pragma: no cover - typing aid only
+    # Provide a concrete import path for type checkers/IDEs
     from fast_agent.core.fastagent import FastAgent as FastAgent  # noqa: F401
 
 
@@ -124,7 +128,6 @@ __all__ = [
     "LlmStopReason",
     "RequestParams",
     # Agents (lazy loaded)
-    "ToolAgentSynchronous",
     "LlmAgent",
     "LlmDecorator",
     "ToolAgent",

fast_agent/agents/__init__.py

@@ -1,23 +1,72 @@
 """
 Fast Agent - Agent implementations and workflow patterns.
 
-This module exports all agent classes from the fast_agent.agents package,
-providing a single import point for both core agents and workflow agents.
+This module re-exports agent classes with lazy imports to avoid circular
+dependencies during package initialization while preserving a clean API:
+
+    from fast_agent.agents import McpAgent, ToolAgent, LlmAgent
 """
 
-# Core agents
+from typing import TYPE_CHECKING
+
 from fast_agent.agents.agent_types import AgentConfig
-from fast_agent.agents.llm_agent import LlmAgent
-from fast_agent.agents.llm_decorator import LlmDecorator
-from fast_agent.agents.mcp_agent import McpAgent
-from fast_agent.agents.tool_agent import ToolAgent
-
-# Workflow agents
-from fast_agent.agents.workflow.chain_agent import ChainAgent
-from fast_agent.agents.workflow.evaluator_optimizer import EvaluatorOptimizerAgent
-from fast_agent.agents.workflow.iterative_planner import IterativePlanner
-from fast_agent.agents.workflow.parallel_agent import ParallelAgent
-from fast_agent.agents.workflow.router_agent import RouterAgent
+
+
+def __getattr__(name: str):
+    """Lazily resolve agent classes to avoid import cycles."""
+    if name == "LlmAgent":
+        from .llm_agent import LlmAgent
+
+        return LlmAgent
+    elif name == "LlmDecorator":
+        from .llm_decorator import LlmDecorator
+
+        return LlmDecorator
+    elif name == "ToolAgent":
+        from .tool_agent import ToolAgent
+
+        return ToolAgent
+    elif name == "McpAgent":
+        from .mcp_agent import McpAgent
+
+        return McpAgent
+    elif name == "ChainAgent":
+        from .workflow.chain_agent import ChainAgent
+
+        return ChainAgent
+    elif name == "EvaluatorOptimizerAgent":
+        from .workflow.evaluator_optimizer import EvaluatorOptimizerAgent
+
+        return EvaluatorOptimizerAgent
+    elif name == "IterativePlanner":
+        from .workflow.iterative_planner import IterativePlanner
+
+        return IterativePlanner
+    elif name == "ParallelAgent":
+        from .workflow.parallel_agent import ParallelAgent
+
+        return ParallelAgent
+    elif name == "RouterAgent":
+        from .workflow.router_agent import RouterAgent
+
+        return RouterAgent
+    else:
+        raise AttributeError(f"module '{__name__}' has no attribute '{name}'")
+
+
+if TYPE_CHECKING:  # pragma: no cover - type checking only
+    from .llm_agent import LlmAgent as LlmAgent  # noqa: F401
+    from .llm_decorator import LlmDecorator as LlmDecorator  # noqa: F401
+    from .mcp_agent import McpAgent as McpAgent  # noqa: F401
+    from .tool_agent import ToolAgent as ToolAgent  # noqa: F401
+    from .workflow.chain_agent import ChainAgent as ChainAgent  # noqa: F401
+    from .workflow.evaluator_optimizer import (
+        EvaluatorOptimizerAgent as EvaluatorOptimizerAgent,
+    )  # noqa: F401
+    from .workflow.iterative_planner import IterativePlanner as IterativePlanner  # noqa: F401
+    from .workflow.parallel_agent import ParallelAgent as ParallelAgent  # noqa: F401
+    from .workflow.router_agent import RouterAgent as RouterAgent  # noqa: F401
+
 
 __all__ = [
     # Core agents

fast_agent/agents/llm_decorator.py

@@ -189,6 +189,7 @@ class LlmDecorator(AgentProtocol):
             Sequence[Union[str, PromptMessage, PromptMessageExtended]],
         ],
         request_params: RequestParams | None = None,
+        tools: List[Tool] | None = None,
     ) -> PromptMessageExtended:
         """
         Create a completion with the LLM using the provided messages.
@@ -212,7 +213,7 @@ class LlmDecorator(AgentProtocol):
         multipart_messages = normalize_to_extended_list(messages)
 
         with self._tracer.start_as_current_span(f"Agent: '{self._name}' generate"):
-            return await self.generate_impl(multipart_messages, request_params, None)
+            return await self.generate_impl(multipart_messages, request_params, tools)
 
     async def generate_impl(
         self,

fast_agent/agents/tool_agent.py

@@ -97,7 +97,10 @@ class ToolAgent(LlmAgent):
             )
 
             if LlmStopReason.TOOL_USE == result.stop_reason:
-                messages = [await self.run_tools(result)]
+                if self.config.use_history:
+                    messages = [await self.run_tools(result)]
+                else:
+                    messages.extend([result, await self.run_tools(result)])
             else:
                 break
 

fast_agent/agents/workflow/orchestrator_models.py

@@ -72,7 +72,7 @@ class TaskWithResult(Task):
 class StepResult(BaseModel):
     """Result of executing a step"""
 
-    step: Step = Field(description="The step that was executed", default_factory=Step)
+    step: Step = Field(description="The step that was executed")
     task_results: List[TaskWithResult] = Field(
         description="Results of executing each task", default_factory=list
     )

fast_agent/cli/commands/go.py

@@ -7,10 +7,10 @@ from typing import Dict, List, Optional
 
 import typer
 
+from fast_agent import FastAgent
 from fast_agent.agents.llm_agent import LlmAgent
 from fast_agent.cli.commands.server_helpers import add_servers_to_config, generate_server_name
 from fast_agent.cli.commands.url_parser import generate_server_configs, parse_server_urls
-from fast_agent.core.fastagent import FastAgent
 from fast_agent.ui.console_display import ConsoleDisplay
 
 app = typer.Typer(

fast_agent/cli/commands/url_parser.py

@@ -104,7 +104,7 @@ def generate_server_name(url: str) -> str:
 
 
 def parse_server_urls(
-    urls_param: str, auth_token: str = None
+    urls_param: str, auth_token: str | None = None
 ) -> List[Tuple[str, Literal["http", "sse"], str, Dict[str, str] | None]]:
     """
     Parse a comma-separated list of URLs into server configurations.
@@ -155,7 +155,7 @@ def generate_server_configs(
     Returns:
         Dictionary of server configurations
     """
-    server_configs = {}
+    server_configs: Dict[str, Dict[str, str | Dict[str, str]]] = {}
     # Keep track of server name occurrences to handle collisions
     name_counts = {}
 
@@ -178,7 +178,7 @@ def generate_server_configs(
                 final_name = f"{server_name}_{suffix}"
                 name_counts[server_name] += 1
 
-        config = {
+        config: Dict[str, str | Dict[str, str]] = {
             "transport": transport_type,
             "url": url,
         }

fast_agent/cli/main.py

@@ -85,7 +85,13 @@ def main(
     Use --help with any command for detailed usage information.
     """
     application.verbosity = 1 if verbose else 0 if not quiet else -1
-    application.console = application.console if color else None
+    if not color:
+        # Recreate consoles without color when --no-color is provided
+        from fast_agent.ui.console import console as base_console
+        from fast_agent.ui.console import error_console as base_error_console
+
+        application.console = base_console.__class__(color_system=None)
+        application.error_console = base_error_console.__class__(color_system=None, stderr=True)
 
     # Handle version flag
     if version:

fast_agent/config.py

@@ -470,6 +470,10 @@ class Settings(BaseSettings):
     - "auto": Extract and automatically open ui:// resources.
     """
 
+    # Output directory for MCP-UI generated HTML files (relative to CWD if not absolute)
+    mcp_ui_output_dir: str = ".fast-agent/ui"
+    """Directory where MCP-UI HTML files are written. Relative paths are resolved from CWD."""
+
     @classmethod
     def find_config(cls) -> Path | None:
         """Find the config file in the current directory or parent directories."""
@@ -547,6 +551,8 @@ def get_settings(config_path: str | None = None) -> Settings:
         return _settings
 
     # Handle config path - convert string to Path if needed
+    config_file: Path | None
+    secrets_file: Path | None
     if config_path:
         config_file = Path(config_path)
         # If it's a relative path and doesn't exist, try finding it

fast_agent/core/__init__.py

@@ -2,40 +2,32 @@
 Core interfaces and decorators for fast-agent.
 
 Public API:
-- `Core`: The core application container (lazy-loaded)
-- `FastAgent`: High-level, decorator-driven application class (lazy-loaded)
+- `Core`: The core application container
+- `AgentApp`: Container for interacting with agents
+- `FastAgent`: High-level, decorator-driven application class
 - Decorators: `agent`, `custom`, `orchestrator`, `iterative_planner`,
-  `router`, `chain`, `parallel`, `evaluator_optimizer` (lazy-loaded)
+  `router`, `chain`, `parallel`, `evaluator_optimizer`
+
+Exports are resolved lazily to avoid circular imports during package init.
 """
 
-__all__ = [
-    "Core",
-    "FastAgent",
-    # Decorators
-    "agent",
-    "custom",
-    "orchestrator",
-    "iterative_planner",
-    "router",
-    "chain",
-    "parallel",
-    "evaluator_optimizer",
-]
+from typing import TYPE_CHECKING
 
 
 def __getattr__(name: str):
-    # Lazy imports to avoid heavy dependencies and circular imports at init time
-    if name == "Core":
+    if name == "AgentApp":
+        from .agent_app import AgentApp
+
+        return AgentApp
+    elif name == "Core":
         from .core_app import Core
 
         return Core
-    if name == "FastAgent":
+    elif name == "FastAgent":
         from .fastagent import FastAgent
 
         return FastAgent
-
-    # Decorators from direct_decorators
-    if name in {
+    elif name in (
         "agent",
         "custom",
         "orchestrator",
@@ -44,9 +36,57 @@ def __getattr__(name: str):
         "chain",
         "parallel",
         "evaluator_optimizer",
-    }:
+    ):
         from . import direct_decorators as _dd
 
-        return getattr(_dd, name)
-
+        return getattr(
+            _dd,
+            name,
+        )
     raise AttributeError(f"module '{__name__}' has no attribute '{name}'")
+
+
+if TYPE_CHECKING:  # pragma: no cover - typing aid only
+    from .agent_app import AgentApp as AgentApp  # noqa: F401
+    from .core_app import Core as Core  # noqa: F401
+    from .direct_decorators import (  # noqa: F401
+        agent as agent,
+    )
+    from .direct_decorators import (
+        chain as chain,
+    )
+    from .direct_decorators import (
+        custom as custom,
+    )
+    from .direct_decorators import (
+        evaluator_optimizer as evaluator_optimizer,
+    )
+    from .direct_decorators import (
+        iterative_planner as iterative_planner,
+    )
+    from .direct_decorators import (
+        orchestrator as orchestrator,
+    )
+    from .direct_decorators import (
+        parallel as parallel,
+    )
+    from .direct_decorators import (
+        router as router,
+    )
+    from .fastagent import FastAgent as FastAgent  # noqa: F401
+
+
+__all__ = [
+    "Core",
+    "AgentApp",
+    "FastAgent",
+    # Decorators
+    "agent",
+    "custom",
+    "orchestrator",
+    "iterative_planner",
+    "router",
+    "chain",
+    "parallel",
+    "evaluator_optimizer",
+]

fast_agent/core/direct_decorators.py

@@ -186,7 +186,7 @@ def _decorator_impl(
     resources: Optional[Dict[str, List[str]]] = None,
     prompts: Optional[Dict[str, List[str]]] = None,
     **extra_kwargs,
-) -> Callable[[AgentCallable[P, R]], DecoratedAgentProtocol[P, R]]:
+) -> Callable[[AgentCallable[P, R]], AgentCallable[P, R]]:
     """
     Core implementation for agent decorators with common behavior and type safety.
 
@@ -203,7 +203,7 @@ def _decorator_impl(
         **extra_kwargs: Additional agent/workflow-specific parameters
     """
 
-    def decorator(func: AgentCallable[P, R]) -> DecoratedAgentProtocol[P, R]:
+    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
@@ -249,7 +249,7 @@ def _decorator_impl(
         for key, value in extra_kwargs.items():
             setattr(wrapper, f"_{key}", value)
 
-        return cast("DecoratedAgentProtocol[P, R]", wrapper)
+        return cast("AgentCallable[P, R]", wrapper)
 
     return decorator
 
@@ -271,7 +271,7 @@ def agent(
     default: bool = False,
     elicitation_handler: Optional[ElicitationFnT] = None,
     api_key: str | None = None,
-) -> Callable[[AgentCallable[P, R]], DecoratedAgentProtocol[P, R]]:
+) -> Callable[[AgentCallable[P, R]], AgentCallable[P, R]]:
     """
     Decorator to create and register a standard agent with type-safe signature.
 
@@ -336,7 +336,7 @@ def custom(
     default: bool = False,
     elicitation_handler: Optional[ElicitationFnT] = None,
     api_key: str | None = None,
-) -> Callable[[AgentCallable[P, R]], DecoratedAgentProtocol[P, R]]:
+) -> Callable[[AgentCallable[P, R]], AgentCallable[P, R]]:
     """
     Decorator to create and register a standard agent with type-safe signature.
 
@@ -400,7 +400,7 @@ def orchestrator(
     plan_iterations: int = 5,
     default: bool = False,
     api_key: str | None = None,
-) -> Callable[[AgentCallable[P, R]], DecoratedOrchestratorProtocol[P, R]]:
+) -> Callable[[AgentCallable[P, R]], AgentCallable[P, R]]:
     """
     Decorator to create and register an orchestrator agent with type-safe signature.
 
@@ -423,24 +423,21 @@ def orchestrator(
     # 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.ORCHESTRATOR,
-            name=name,
-            instruction=resolved_instruction,
-            servers=[],  # Orchestrators don't connect to servers directly
-            model=model,
-            use_history=use_history,
-            request_params=request_params,
-            human_input=human_input,
-            child_agents=agents,
-            plan_type=plan_type,
-            plan_iterations=plan_iterations,
-            default=default,
-            api_key=api_key,
-        ),
+    return _decorator_impl(
+        self,
+        AgentType.ORCHESTRATOR,
+        name=name,
+        instruction=resolved_instruction,
+        servers=[],  # Orchestrators don't connect to servers directly
+        model=model,
+        use_history=use_history,
+        request_params=request_params,
+        human_input=human_input,
+        child_agents=agents,
+        plan_type=plan_type,
+        plan_iterations=plan_iterations,
+        default=default,
+        api_key=api_key,
     )
 
 
@@ -455,7 +452,7 @@ def iterative_planner(
     plan_iterations: int = -1,
     default: bool = False,
     api_key: str | None = None,
-) -> Callable[[AgentCallable[P, R]], DecoratedOrchestratorProtocol[P, R]]:
+) -> Callable[[AgentCallable[P, R]], AgentCallable[P, R]]:
     """
     Decorator to create and register an orchestrator agent with type-safe signature.
 
@@ -478,22 +475,19 @@ def iterative_planner(
     # 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,
-        ),
+    return _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,
     )
 
 
@@ -516,7 +510,7 @@ def router(
         ElicitationFnT
     ] = None,  ## exclude from docs, decide whether allowable
     api_key: str | None = None,
-) -> Callable[[AgentCallable[P, R]], DecoratedRouterProtocol[P, R]]:
+) -> Callable[[AgentCallable[P, R]], AgentCallable[P, R]]:
     """
     Decorator to create and register a router agent with type-safe signature.
 
@@ -536,26 +530,23 @@ def router(
     """
     resolved_instruction = _resolve_instruction(instruction or ROUTING_SYSTEM_INSTRUCTION)
 
-    return cast(
-        "Callable[[AgentCallable[P, R]], DecoratedRouterProtocol[P, R]]",
-        _decorator_impl(
-            self,
-            AgentType.ROUTER,
-            name=name,
-            instruction=resolved_instruction,
-            servers=servers,
-            model=model,
-            use_history=use_history,
-            request_params=request_params,
-            human_input=human_input,
-            default=default,
-            router_agents=agents,
-            elicitation_handler=elicitation_handler,
-            api_key=api_key,
-            tools=tools,
-            prompts=prompts,
-            resources=resources,
-        ),
+    return _decorator_impl(
+        self,
+        AgentType.ROUTER,
+        name=name,
+        instruction=resolved_instruction,
+        servers=servers,
+        model=model,
+        use_history=use_history,
+        request_params=request_params,
+        human_input=human_input,
+        default=default,
+        router_agents=agents,
+        elicitation_handler=elicitation_handler,
+        api_key=api_key,
+        tools=tools,
+        prompts=prompts,
+        resources=resources,
     )
 
 
@@ -567,7 +558,7 @@ def chain(
     instruction: Optional[str | Path | AnyUrl] = None,
     cumulative: bool = False,
     default: bool = False,
-) -> Callable[[AgentCallable[P, R]], DecoratedChainProtocol[P, R]]:
+) -> Callable[[AgentCallable[P, R]], AgentCallable[P, R]]:
     """
     Decorator to create and register a chain agent with type-safe signature.
 
@@ -593,17 +584,14 @@ def chain(
     """
     resolved_instruction = _resolve_instruction(instruction or default_instruction)
 
-    return cast(
-        "Callable[[AgentCallable[P, R]], DecoratedChainProtocol[P, R]]",
-        _decorator_impl(
-            self,
-            AgentType.CHAIN,
-            name=name,
-            instruction=resolved_instruction,
-            sequence=sequence,
-            cumulative=cumulative,
-            default=default,
-        ),
+    return _decorator_impl(
+        self,
+        AgentType.CHAIN,
+        name=name,
+        instruction=resolved_instruction,
+        sequence=sequence,
+        cumulative=cumulative,
+        default=default,
     )
 
 
@@ -616,7 +604,7 @@ def parallel(
     instruction: Optional[str | Path | AnyUrl] = None,
     include_request: bool = True,
     default: bool = False,
-) -> Callable[[AgentCallable[P, R]], DecoratedParallelProtocol[P, R]]:
+) -> Callable[[AgentCallable[P, R]], AgentCallable[P, R]]:
     """
     Decorator to create and register a parallel agent with type-safe signature.
 
@@ -637,19 +625,16 @@ def parallel(
     """
     resolved_instruction = _resolve_instruction(instruction or default_instruction)
 
-    return cast(
-        "Callable[[AgentCallable[P, R]], DecoratedParallelProtocol[P, R]]",
-        _decorator_impl(
-            self,
-            AgentType.PARALLEL,
-            name=name,
-            instruction=resolved_instruction,
-            servers=[],  # Parallel agents don't connect to servers directly
-            fan_in=fan_in,
-            fan_out=fan_out,
-            include_request=include_request,
-            default=default,
-        ),
+    return _decorator_impl(
+        self,
+        AgentType.PARALLEL,
+        name=name,
+        instruction=resolved_instruction,
+        servers=[],  # Parallel agents don't connect to servers directly
+        fan_in=fan_in,
+        fan_out=fan_out,
+        include_request=include_request,
+        default=default,
     )
 
 
@@ -663,7 +648,7 @@ def evaluator_optimizer(
     min_rating: str = "GOOD",
     max_refinements: int = 3,
     default: bool = False,
-) -> Callable[[AgentCallable[P, R]], DecoratedEvaluatorOptimizerProtocol[P, R]]:
+) -> Callable[[AgentCallable[P, R]], AgentCallable[P, R]]:
     """
     Decorator to create and register an evaluator-optimizer agent with type-safe signature.
 
@@ -686,18 +671,15 @@ def evaluator_optimizer(
     """
     resolved_instruction = _resolve_instruction(instruction or default_instruction)
 
-    return cast(
-        "Callable[[AgentCallable[P, R]], DecoratedEvaluatorOptimizerProtocol[P, R]]",
-        _decorator_impl(
-            self,
-            AgentType.EVALUATOR_OPTIMIZER,
-            name=name,
-            instruction=resolved_instruction,
-            servers=[],  # Evaluator-optimizer doesn't connect to servers directly
-            generator=generator,
-            evaluator=evaluator,
-            min_rating=min_rating,
-            max_refinements=max_refinements,
-            default=default,
-        ),
+    return _decorator_impl(
+        self,
+        AgentType.EVALUATOR_OPTIMIZER,
+        name=name,
+        instruction=resolved_instruction,
+        servers=[],  # Evaluator-optimizer doesn't connect to servers directly
+        generator=generator,
+        evaluator=evaluator,
+        min_rating=min_rating,
+        max_refinements=max_refinements,
+        default=default,
     )

fast_agent/core/direct_factory.py

@@ -5,9 +5,9 @@ Implements type-safe factories with improved error handling.
 
 from typing import Any, Dict, Optional, Protocol, TypeVar
 
+from fast_agent.agents import McpAgent
 from fast_agent.agents.agent_types import AgentConfig, AgentType
 from fast_agent.agents.llm_agent import LlmAgent
-from fast_agent.agents.mcp_agent import McpAgent
 from fast_agent.agents.workflow.evaluator_optimizer import (
     EvaluatorOptimizerAgent,
     QualityRating,