fast-agent-mcp 0.3.1__tar.gz → 0.3.3__tar.gz

{fast_agent_mcp-0.3.1 → fast_agent_mcp-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fast-agent-mcp
-Version: 0.3.1
+Version: 0.3.3
 Summary: Define, Prompt and Test MCP enabled Agents and Workflows
 Author-email: Shaun Smith <fastagent@llmindset.co.uk>
 License:                                  Apache License

fast_agent_mcp-0.3.3/examples/fastapi/fastapi-advanced.py

@@ -0,0 +1,51 @@
+from contextlib import asynccontextmanager
+
+from fastapi import Body, FastAPI, HTTPException
+
+from fast_agent.agents.agent_types import AgentConfig
+from fast_agent.agents.mcp_agent import McpAgent
+from fast_agent.core import Core
+from fast_agent.core.direct_factory import get_model_factory
+from fast_agent.mcp import PromptMessageExtended
+
+core = Core(name="fast-agent core")
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    # Manual lifecycle control: initialize Core and Agent explicitly
+    await core.initialize()
+
+    cfg = AgentConfig(
+        name="core_agent",
+        instruction="You are a helpful AI Agent.",
+    )
+
+    agent = McpAgent(config=cfg, context=core.context)
+    await agent.initialize()
+
+    llm_factory = get_model_factory(core.context, model=cfg.model)
+    await agent.attach_llm(llm_factory)
+
+    app.state.agent = agent
+    try:
+        yield
+    finally:
+        # Manual shutdown/cleanup
+        try:
+            await agent.shutdown()
+        finally:
+            await core.cleanup()
+
+
+app = FastAPI(lifespan=lifespan)
+
+
+@app.post("/ask", response_model=PromptMessageExtended)
+async def ask(body: str = Body(..., media_type="text/plain")) -> PromptMessageExtended:
+    try:
+        # Call generate() to return the full multipart message (BaseModel)
+        result = await app.state.agent.generate(body)
+        return result
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))

fast_agent_mcp-0.3.3/examples/fastapi/fastapi-simple.py

@@ -0,0 +1,43 @@
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI, HTTPException
+from pydantic import BaseModel
+
+from fast_agent.core.fastagent import FastAgent
+
+# Create FastAgent without parsing CLI args (plays nice with uvicorn)
+fast = FastAgent("fast-agent demo", parse_cli_args=False, quiet=True)
+
+
+# Register a simple default agent via decorator
+@fast.agent(name="helper", instruction="You are a helpful AI Agent.", default=True)
+async def decorator():
+    pass
+
+
+# Keep FastAgent running for the app lifetime
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    async with fast.run() as agents:
+        app.state.agents = agents
+        yield
+
+
+app = FastAPI(lifespan=lifespan)
+
+
+class AskRequest(BaseModel):
+    message: str
+
+
+class AskResponse(BaseModel):
+    response: str
+
+
+@app.post("/ask", response_model=AskResponse)
+async def ask(req: AskRequest) -> AskResponse:
+    try:
+        result = await app.state.agents.send(req.message)
+        return AskResponse(response=result)
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))

fast_agent_mcp-0.3.3/examples/fastapi/pyproject.toml

@@ -0,0 +1,17 @@
+[project]
+name = "fast-agent-app"
+version = "0.1.0"
+description = "a simple fast-agent application"
+readme = "README.md"
+requires-python = ">=3.13.7"
+dependencies = [
+  "fast-agent-mcp",
+  "fastapi>=0.116.1",
+]
+
+[tool.uv]
+package = true
+
+# Optional convenience entry point if you later package this app:
+[project.scripts]
+fast-agent-app = "agent:main"

fast_agent_mcp-0.3.3/examples/fastapi/readme.md

@@ -0,0 +1,6 @@
+# fastapi demo applications
+
+Be sure to `uv pip install fastapi[standard]` to run these examples.
+
+- fastapi-simply.py -- uses simple `fast-agent` decorators to integrate with fastapi. run with `fastapi dev fastapi-simple.py`.
+- fastapi-advanced.py -- uses `fast-agent` core library for developer managed lifecycle. run with `fastapi dev fastapi-advanced.py`.

{fast_agent_mcp-0.3.1 → fast_agent_mcp-0.3.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fast-agent-mcp"
-version = "0.3.1"
+version = "0.3.3"
 description = "Define, Prompt and Test MCP enabled Agents and Workflows"
 readme = "README.md"
 license = { file = "LICENSE" }

{fast_agent_mcp-0.3.1 → fast_agent_mcp-0.3.3}/src/fast_agent/__init__.py

@@ -1,4 +1,5 @@
 """fast-agent - An MCP native agent application framework"""
+from typing import TYPE_CHECKING as _TYPE_CHECKING
 
 # Configuration and settings (safe - pure Pydantic models)
 from fast_agent.config import (
@@ -83,6 +84,11 @@ def __getattr__(name: str):
         raise AttributeError(f"module '{__name__}' has no attribute '{name}'")
 
 
+# Help static analyzers/IDEs resolve symbols and signatures without importing at runtime.
+if _TYPE_CHECKING:  # pragma: no cover - typing aid only
+    from fast_agent.core.fastagent import FastAgent as FastAgent  # noqa: F401
+
+
 __all__ = [
     # Core fast-agent components (lazy loaded)
     "Core",

{fast_agent_mcp-0.3.1 → fast_agent_mcp-0.3.3}/src/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_mcp-0.3.1 → fast_agent_mcp-0.3.3}/src/fast_agent/agents/mcp_agent.py

@@ -43,7 +43,6 @@ from fast_agent.constants import HUMAN_INPUT_TOOL_NAME
 from fast_agent.core.exceptions import PromptExitError
 from fast_agent.core.logging.logger import get_logger
 from fast_agent.interfaces import FastAgentLLMProtocol
-from fast_agent.mcp.helpers.content_helpers import normalize_to_extended_list
 from fast_agent.mcp.mcp_aggregator import MCPAggregator
 from fast_agent.tools.elicitation import (
     get_elicitation_tool,
@@ -624,12 +623,9 @@ class McpAgent(ABC, ToolAgent):
         Returns:
             An instance of the specified model, or None if coercion fails
         """
-        assert self._llm
-        # Normalize all input types to a list of PromptMessageExtended
-        normalized_messages = normalize_to_extended_list(messages)
 
         with self._tracer.start_as_current_span(f"Agent: '{self._name}' structured"):
-            return await self._llm.structured(normalized_messages, model, request_params)
+            return await super().structured(messages, model, request_params)
 
     async def apply_prompt_messages(
         self, prompts: List[PromptMessageExtended], request_params: RequestParams | None = None

{fast_agent_mcp-0.3.1 → fast_agent_mcp-0.3.3}/src/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_mcp-0.3.1 → fast_agent_mcp-0.3.3}/src/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_mcp-0.3.1 → fast_agent_mcp-0.3.3}/src/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_mcp-0.3.1 → fast_agent_mcp-0.3.3}/src/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_mcp-0.3.1 → fast_agent_mcp-0.3.3}/src/fast_agent/config.py

@@ -547,6 +547,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_mcp-0.3.3/src/fast_agent/core/__init__.py

@@ -0,0 +1,91 @@
+"""
+Core interfaces and decorators for fast-agent.
+
+Public API:
+- `Core`: The core application container (eagerly exported)
+- `FastAgent`: High-level, decorator-driven application class (lazy-loaded)
+- Decorators: `agent`, `custom`, `orchestrator`, `iterative_planner`,
+  `router`, `chain`, `parallel`, `evaluator_optimizer` (lazy-loaded)
+"""
+
+from typing import TYPE_CHECKING as _TYPE_CHECKING
+
+from .core_app import Core  # Eager export for external applications
+
+__all__ = [
+    "Core",
+    "AgentApp",
+    "FastAgent",
+    # Decorators
+    "agent",
+    "custom",
+    "orchestrator",
+    "iterative_planner",
+    "router",
+    "chain",
+    "parallel",
+    "evaluator_optimizer",
+]
+
+
+def __getattr__(name: str):
+    # Lazy imports to avoid heavy dependencies and circular imports at init time
+    if name == "FastAgent":
+        from .fastagent import FastAgent
+
+        return FastAgent
+    if name == "AgentApp":
+        from .agent_app import AgentApp
+
+        return AgentApp
+
+    # Decorators from direct_decorators
+    if name in {
+        "agent",
+        "custom",
+        "orchestrator",
+        "iterative_planner",
+        "router",
+        "chain",
+        "parallel",
+        "evaluator_optimizer",
+    }:
+        from . import direct_decorators as _dd
+
+        return getattr(_dd, name)
+
+    raise AttributeError(f"module '{__name__}' has no attribute '{name}'")
+
+
+# Help static analyzers/IDEs resolve symbols and signatures without importing at runtime.
+if _TYPE_CHECKING:  # pragma: no cover - typing aid only
+    from .agent_app import AgentApp as AgentApp  # noqa: F401
+    from .direct_decorators import (
+        agent as agent,
+    )  # noqa: F401
+    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
+
+
+def __dir__():  # pragma: no cover - developer experience aid
+    return sorted(__all__)

{fast_agent_mcp-0.3.1 → fast_agent_mcp-0.3.3}/src/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,
     )