fast-agent-mcp 0.1.11__py3-none-any.whl → 0.1.13__py3-none-any.whl

mcp_agent/core/fastagent.py

@@ -3,61 +3,59 @@ Decorator-based interface for MCP Agent applications.
 Provides a simplified way to create and manage agents using decorators.
 """
 
+import argparse
 import asyncio
+from contextlib import asynccontextmanager
+from functools import partial
 from typing import (
-    Optional,
+    Any,
     Dict,
+    Optional,
     TypeVar,
-    Any,
 )
+
 import yaml
-import argparse
-from contextlib import asynccontextmanager
-from functools import partial
+
+# TODO -- reinstate once Windows&Python 3.13 platform issues are fixed
+# import readline  # noqa: F401
+from rich import print
 
 from mcp_agent.app import MCPApp
 from mcp_agent.config import Settings
-
 from mcp_agent.core.agent_app import AgentApp
 from mcp_agent.core.agent_types import AgentType
+from mcp_agent.core.decorators import (
+    _create_decorator,
+    agent,
+    chain,
+    evaluator_optimizer,
+    orchestrator,
+    parallel,
+    passthrough,
+    router,
+)
 from mcp_agent.core.error_handling import handle_error
-from mcp_agent.core.proxies import LLMAgentProxy
-from mcp_agent.core.types import ProxyDict
 from mcp_agent.core.exceptions import (
     AgentConfigError,
     CircularDependencyError,
     ModelConfigError,
     PromptExitError,
-    ServerConfigError,
     ProviderKeyError,
+    ServerConfigError,
     ServerInitializationError,
 )
-from mcp_agent.core.decorators import (
-    _create_decorator,
-    agent,
-    orchestrator,
-    parallel,
-    evaluator_optimizer,
-    router,
-    chain,
-    passthrough,
+from mcp_agent.core.factory import (
+    create_agents_by_type,
+    create_agents_in_dependency_order,
+    create_basic_agents,
+    get_model_factory,
 )
+from mcp_agent.core.proxies import LLMAgentProxy
+from mcp_agent.core.types import ProxyDict
 from mcp_agent.core.validation import (
     validate_server_references,
     validate_workflow_references,
 )
-from mcp_agent.core.factory import (
-    get_model_factory,
-    create_basic_agents,
-    create_agents_in_dependency_order,
-    create_agents_by_type,
-)
-
-# TODO -- reinstate once Windows&Python 3.13 platform issues are fixed
-# import readline  # noqa: F401
-
-from rich import print
-
 from mcp_agent.mcp_server import AgentMCPServer
 
 T = TypeVar("T")  # For the wrapper classes
@@ -74,7 +72,7 @@ class FastAgent:
         name: str,
         config_path: Optional[str] = None,
         ignore_unknown_args: bool = False,
-    ):
+    ) -> None:
         """
         Initialize the decorator interface.
 
@@ -218,9 +216,7 @@ class FastAgent:
         model_factory_func = partial(self._get_model_factory)
         return await create_basic_agents(agent_app, self.agents, model_factory_func)
 
-    async def _create_orchestrators(
-        self, agent_app: MCPApp, active_agents: ProxyDict
-    ) -> ProxyDict:
+    async def _create_orchestrators(self, agent_app: MCPApp, active_agents: ProxyDict) -> ProxyDict:
         """
         Create orchestrator agents.
 
@@ -231,13 +227,9 @@ class FastAgent:
         Returns:
             Dictionary of initialized orchestrator agents wrapped in appropriate proxies
         """
-        return await self._create_agents_by_type(
-            agent_app, AgentType.ORCHESTRATOR, active_agents
-        )
+        return await self._create_agents_by_type(agent_app, AgentType.ORCHESTRATOR, active_agents)
 
-    async def _create_evaluator_optimizers(
-        self, agent_app: MCPApp, active_agents: ProxyDict
-    ) -> ProxyDict:
+    async def _create_evaluator_optimizers(self, agent_app: MCPApp, active_agents: ProxyDict) -> ProxyDict:
         """
         Create evaluator-optimizer workflows.
 
@@ -248,13 +240,9 @@ class FastAgent:
         Returns:
             Dictionary of initialized evaluator-optimizer workflows
         """
-        return await self._create_agents_by_type(
-            agent_app, AgentType.EVALUATOR_OPTIMIZER, active_agents
-        )
+        return await self._create_agents_by_type(agent_app, AgentType.EVALUATOR_OPTIMIZER, active_agents)
 
-    async def _create_parallel_agents(
-        self, agent_app: MCPApp, active_agents: ProxyDict
-    ) -> ProxyDict:
+    async def _create_parallel_agents(self, agent_app: MCPApp, active_agents: ProxyDict) -> ProxyDict:
         """
         Create parallel execution agents in dependency order.
 
@@ -274,9 +262,7 @@ class FastAgent:
             model_factory_func,
         )
 
-    async def _create_agents_in_dependency_order(
-        self, agent_app: MCPApp, active_agents: ProxyDict, agent_type: AgentType
-    ) -> ProxyDict:
+    async def _create_agents_in_dependency_order(self, agent_app: MCPApp, active_agents: ProxyDict, agent_type: AgentType) -> ProxyDict:
         """
         Create agents in dependency order to avoid circular references.
         Works for both Parallel and Chain workflows.
@@ -290,13 +276,9 @@ class FastAgent:
             Dictionary of initialized agents
         """
         model_factory_func = partial(self._get_model_factory)
-        return await create_agents_in_dependency_order(
-            agent_app, self.agents, active_agents, agent_type, model_factory_func
-        )
+        return await create_agents_in_dependency_order(agent_app, self.agents, active_agents, agent_type, model_factory_func)
 
-    async def _create_routers(
-        self, agent_app: MCPApp, active_agents: ProxyDict
-    ) -> ProxyDict:
+    async def _create_routers(self, agent_app: MCPApp, active_agents: ProxyDict) -> ProxyDict:
         """
         Create router agents.
 
@@ -307,9 +289,7 @@ class FastAgent:
         Returns:
             Dictionary of initialized router agents
         """
-        return await self._create_agents_by_type(
-            agent_app, AgentType.ROUTER, active_agents
-        )
+        return await self._create_agents_by_type(agent_app, AgentType.ROUTER, active_agents)
 
     @asynccontextmanager
     async def run(self):
@@ -327,11 +307,7 @@ class FastAgent:
         try:
             async with self.app.run() as agent_app:
                 # Apply quiet mode directly to the context's config if needed
-                if (
-                    quiet_mode
-                    and hasattr(agent_app.context, "config")
-                    and hasattr(agent_app.context.config, "logger")
-                ):
+                if quiet_mode and hasattr(agent_app.context, "config") and hasattr(agent_app.context.config, "logger"):
                     # Apply after initialization but before agents are created
                     agent_app.context.config.logger.progress_display = False
                     agent_app.context.config.logger.show_chat = False
@@ -351,9 +327,7 @@ class FastAgent:
                 active_agents = await self._create_basic_agents(agent_app)
 
                 # Create parallel agents next as they might be dependencies
-                parallel_agents = await self._create_parallel_agents(
-                    agent_app, active_agents
-                )
+                parallel_agents = await self._create_parallel_agents(agent_app, active_agents)
                 active_agents.update(parallel_agents)
 
                 # Create routers next
@@ -361,21 +335,15 @@ class FastAgent:
                 active_agents.update(routers)
 
                 # Create chains next - MOVED UP because evaluator-optimizers might depend on chains
-                chains = await self._create_agents_in_dependency_order(
-                    agent_app, active_agents, AgentType.CHAIN
-                )
+                chains = await self._create_agents_in_dependency_order(agent_app, active_agents, AgentType.CHAIN)
                 active_agents.update(chains)
 
                 # Now create evaluator-optimizers AFTER chains are available
-                evaluator_optimizers = await self._create_evaluator_optimizers(
-                    agent_app, active_agents
-                )
+                evaluator_optimizers = await self._create_evaluator_optimizers(agent_app, active_agents)
                 active_agents.update(evaluator_optimizers)
 
                 # Create orchestrators last as they might depend on any other agent type
-                orchestrators = await self._create_orchestrators(
-                    agent_app, active_agents
-                )
+                orchestrators = await self._create_orchestrators(agent_app, active_agents)
 
                 # Add orchestrators to active_agents (other types were already added)
                 active_agents.update(orchestrators)
@@ -393,9 +361,7 @@ class FastAgent:
 
                     if agent_name not in active_agents:
                         available_agents = ", ".join(active_agents.keys())
-                        print(
-                            f"\n\nError: Agent '{agent_name}' not found. Available agents: {available_agents}"
-                        )
+                        print(f"\n\nError: Agent '{agent_name}' not found. Available agents: {available_agents}")
                         raise SystemExit(1)
 
                     try:
@@ -408,9 +374,7 @@ class FastAgent:
 
                         raise SystemExit(0)
                     except Exception as e:
-                        print(
-                            f"\n\nError sending message to agent '{agent_name}': {str(e)}"
-                        )
+                        print(f"\n\nError sending message to agent '{agent_name}': {str(e)}")
                         raise SystemExit(1)
 
                 yield wrapper
@@ -488,9 +452,7 @@ class FastAgent:
                             print(f"DEBUG {e.message}")
                             pass  # Ignore cleanup errors
 
-    def _handle_error(
-        self, e: Exception, error_type: str, suggestion: str = None
-    ) -> None:
+    def _handle_error(self, e: Exception, error_type: str, suggestion: str = None) -> None:
         """
         Handle errors with consistent formatting and messaging.
 
@@ -535,7 +497,7 @@ class FastAgent:
         port: int = 8000,
         server_name: str = None,
         server_description: str = None,
-    ):
+    ) -> None:
         """
         Run the FastAgent application and expose agents through an MCP server.
 
@@ -555,9 +517,7 @@ class FastAgent:
             )
 
             # Run the MCP server in a separate task
-            server_task = asyncio.create_task(
-                mcp_server.run_async(transport=transport, host=host, port=port)
-            )
+            server_task = asyncio.create_task(mcp_server.run_async(transport=transport, host=host, port=port))
 
             try:
                 # Wait for the server task to complete (or be cancelled)

mcp_agent/core/mcp_content.py

@@ -7,14 +7,14 @@ EmbeddedResource, and other MCP content types with minimal boilerplate.
 
 import base64
 from pathlib import Path
-from typing import Literal, Optional, Union, List, Any
+from typing import Any, List, Literal, Optional, Union
 
 from mcp.types import (
-    TextContent,
-    ImageContent,
+    BlobResourceContents,
     EmbeddedResource,
+    ImageContent,
+    TextContent,
     TextResourceContents,
-    BlobResourceContents,
 )
 
 from mcp_agent.mcp.mime_utils import (
@@ -86,9 +86,7 @@ def MCPImage(
 
     return {
         "role": role,
-        "content": ImageContent(
-            type="image", data=b64_data, mimeType=mime_type, annotations=annotations
-        ),
+        "content": ImageContent(type="image", data=b64_data, mimeType=mime_type, annotations=annotations),
     }
 
 
@@ -134,27 +132,20 @@ def MCPFile(
             # Fallback to binary if text read fails
             binary_data = path.read_bytes()
             b64_data = base64.b64encode(binary_data).decode("ascii")
-            resource = BlobResourceContents(
-                uri=uri, blob=b64_data, mimeType=mime_type or "application/octet-stream"
-            )
+            resource = BlobResourceContents(uri=uri, blob=b64_data, mimeType=mime_type or "application/octet-stream")
 
     return {
         "role": role,
-        "content": EmbeddedResource(
-            type="resource", resource=resource, annotations=annotations
-        ),
+        "content": EmbeddedResource(type="resource", resource=resource, annotations=annotations),
     }
 
 
-
-def MCPPrompt(
-    *content_items, role: Literal["user", "assistant"] = "user"
-) -> List[dict]:
+def MCPPrompt(*content_items, role: Literal["user", "assistant"] = "user") -> List[dict]:
     """
     Create one or more prompt messages with various content types.
 
     This function intelligently creates different content types:
-    - Strings become TextContent 
+    - Strings become TextContent
     - File paths with image mime types become ImageContent
     - File paths with text mime types or other mime types become EmbeddedResource
     - Dicts with role and content are passed through unchanged
@@ -180,7 +171,7 @@ def MCPPrompt(
             # File path - determine the content type based on mime type
             path_str = str(item)
             mime_type = guess_mime_type(path_str)
-            
+
             if is_image_mime_type(mime_type):
                 # Image files (except SVG which is handled as text)
                 result.append(MCPImage(path=item, role=role))

mcp_agent/core/prompt.py

@@ -5,10 +5,11 @@ Prompt class for easily creating and working with MCP prompt content.
 from typing import List, Literal
 
 from mcp.types import PromptMessage
+
 from mcp_agent.mcp.prompt_message_multipart import PromptMessageMultipart
 
 # Import our content helper functions
-from .mcp_content import User, Assistant, MCPPrompt
+from .mcp_content import Assistant, MCPPrompt, User
 
 
 class Prompt:
@@ -39,9 +40,7 @@ class Prompt:
             A PromptMessageMultipart with user role and the specified content
         """
         messages = User(*content_items)
-        return PromptMessageMultipart(
-            role="user", content=[msg["content"] for msg in messages]
-        )
+        return PromptMessageMultipart(role="user", content=[msg["content"] for msg in messages])
 
     @classmethod
     def assistant(cls, *content_items) -> PromptMessageMultipart:
@@ -55,14 +54,10 @@ class Prompt:
             A PromptMessageMultipart with assistant role and the specified content
         """
         messages = Assistant(*content_items)
-        return PromptMessageMultipart(
-            role="assistant", content=[msg["content"] for msg in messages]
-        )
+        return PromptMessageMultipart(role="assistant", content=[msg["content"] for msg in messages])
 
     @classmethod
-    def message(
-        cls, *content_items, role: Literal["user", "assistant"] = "user"
-    ) -> PromptMessageMultipart:
+    def message(cls, *content_items, role: Literal["user", "assistant"] = "user") -> PromptMessageMultipart:
         """
         Create a PromptMessageMultipart with the specified role and content items.
 
@@ -100,7 +95,7 @@ class Prompt:
         for item in messages:
             if isinstance(item, PromptMessageMultipart):
                 # Convert PromptMessageMultipart to a list of PromptMessages
-                result.extend(item.to_prompt_messages())
+                result.extend(item.from_multipart())
             elif isinstance(item, dict) and "role" in item and "content" in item:
                 # Convert a single message dict to PromptMessage
                 result.append(PromptMessage(**item))
@@ -114,9 +109,7 @@ class Prompt:
         return result
 
     @classmethod
-    def from_multipart(
-        cls, multipart: List[PromptMessageMultipart]
-    ) -> List[PromptMessage]:
+    def from_multipart(cls, multipart: List[PromptMessageMultipart]) -> List[PromptMessage]:
         """
         Convert a list of PromptMessageMultipart objects to PromptMessages.
 
@@ -128,5 +121,5 @@ class Prompt:
         """
         result = []
         for mp in multipart:
-            result.extend(mp.to_prompt_messages())
+            result.extend(mp.from_multipart())
         return result

mcp_agent/core/proxies.py

@@ -6,16 +6,18 @@ FOR COMPATIBILITY WITH LEGACY MCP-AGENT CODE
 
 """
 
-from typing import List, Optional, Dict, Union, TYPE_CHECKING
+from typing import TYPE_CHECKING, Dict, List, Optional, Union
+
+from mcp.types import EmbeddedResource
 
 from mcp_agent.agents.agent import Agent
 from mcp_agent.app import MCPApp
+from mcp_agent.core.request_params import RequestParams
 from mcp_agent.mcp.prompt_message_multipart import PromptMessageMultipart
-from mcp.types import EmbeddedResource
 
 # Handle circular imports
 if TYPE_CHECKING:
-    from mcp_agent.core.types import WorkflowType, ProxyDict
+    from mcp_agent.core.types import ProxyDict, WorkflowType
 else:
     # Define minimal versions for runtime
     from typing import Any
@@ -28,7 +30,7 @@ else:
 class BaseAgentProxy:
     """Base class for all proxy types"""
 
-    def __init__(self, app: MCPApp, name: str):
+    def __init__(self, app: MCPApp, name: str) -> None:
         self._app = app
         self._name = name
 
@@ -39,9 +41,7 @@ class BaseAgentProxy:
             return await self.prompt()
         return await self.send(message)
 
-    async def send(
-        self, message: Optional[Union[str, PromptMessageMultipart]] = None
-    ) -> str:
+    async def send(self, message: Optional[Union[str, PromptMessageMultipart]] = None) -> str:
         """
         Allow: agent.researcher.send('message') or agent.researcher.send(Prompt.user('message'))
 
@@ -87,9 +87,7 @@ class BaseAgentProxy:
         """Send a message to the agent and return the response"""
         raise NotImplementedError("Subclasses must implement send(prompt)")
 
-    async def apply_prompt(
-        self, prompt_name: str = None, arguments: dict[str, str] = None
-    ) -> str:
+    async def apply_prompt(self, prompt_name: str = None, arguments: dict[str, str] = None) -> str:
         """
         Apply a Prompt from an MCP Server - implemented by subclasses.
         This is the preferred method for applying prompts.
@@ -105,7 +103,7 @@ class BaseAgentProxy:
 class LLMAgentProxy(BaseAgentProxy):
     """Proxy for regular agents that use _llm.generate_str()"""
 
-    def __init__(self, app: MCPApp, name: str, agent: Agent):
+    def __init__(self, app: MCPApp, name: str, agent: Agent) -> None:
         super().__init__(app, name)
         self._agent = agent
 
@@ -117,9 +115,7 @@ class LLMAgentProxy(BaseAgentProxy):
         """Send a message to the agent and return the response"""
         return await self._agent._llm.generate_prompt(prompt, None)
 
-    async def apply_prompt(
-        self, prompt_name: str = None, arguments: dict[str, str] = None
-    ) -> str:
+    async def apply_prompt(self, prompt_name: str = None, arguments: dict[str, str] = None) -> str:
         """
         Apply a prompt from an MCP server.
         This is the preferred method for applying prompts.
@@ -134,9 +130,7 @@ class LLMAgentProxy(BaseAgentProxy):
         return await self._agent.apply_prompt(prompt_name, arguments)
 
     # Add the new methods
-    async def get_embedded_resources(
-        self, server_name: str, resource_name: str
-    ) -> List[EmbeddedResource]:
+    async def get_embedded_resources(self, server_name: str, resource_name: str) -> List[EmbeddedResource]:
         """
         Get a resource from an MCP server and return it as a list of embedded resources ready for use in prompts.
 
@@ -166,15 +160,32 @@ class LLMAgentProxy(BaseAgentProxy):
         Returns:
             The agent's response as a string
         """
-        return await self._agent.with_resource(
-            prompt_content, server_name, resource_name
-        )
+        return await self._agent.with_resource(prompt_content, server_name, resource_name)
+
+    async def apply_prompt_messages(
+        self,
+        multipart_messages: List["PromptMessageMultipart"],
+        request_params: RequestParams | None = None,
+    ) -> str:
+        """
+        Apply a list of PromptMessageMultipart messages directly to the LLM.
+        This is a cleaner interface to _apply_prompt_template_provider_specific.
+
+        Args:
+            multipart_messages: List of PromptMessageMultipart objects
+            request_params: Optional parameters to configure the LLM request
+
+        Returns:
+            String representation of the assistant's response
+        """
+        # Delegate to the provider-specific implementation
+        return await self._agent._llm._apply_prompt_template_provider_specific(multipart_messages, request_params)
 
 
 class WorkflowProxy(BaseAgentProxy):
     """Proxy for workflow types that implement generate_str() directly"""
 
-    def __init__(self, app: MCPApp, name: str, workflow: WorkflowType):
+    def __init__(self, app: MCPApp, name: str, workflow: WorkflowType) -> None:
         super().__init__(app, name)
         self._workflow = workflow
 
@@ -186,7 +197,7 @@ class WorkflowProxy(BaseAgentProxy):
 class RouterProxy(BaseAgentProxy):
     """Proxy for LLM Routers"""
 
-    def __init__(self, app: MCPApp, name: str, workflow: WorkflowType):
+    def __init__(self, app: MCPApp, name: str, workflow: WorkflowType) -> None:
         super().__init__(app, name)
         self._workflow = workflow
 
@@ -215,9 +226,7 @@ class RouterProxy(BaseAgentProxy):
 class ChainProxy(BaseAgentProxy):
     """Proxy for chained agent operations"""
 
-    def __init__(
-        self, app: MCPApp, name: str, sequence: List[str], agent_proxies: ProxyDict
-    ):
+    def __init__(self, app: MCPApp, name: str, sequence: List[str], agent_proxies: ProxyDict) -> None:
         super().__init__(app, name)
         self._sequence = sequence
         self._agent_proxies = agent_proxies

mcp_agent/core/request_params.py

@@ -0,0 +1,46 @@
+"""
+Request parameters definitions for LLM interactions.
+"""
+
+from typing import List
+
+from mcp import SamplingMessage
+from mcp.types import CreateMessageRequestParams
+from pydantic import Field
+
+
+class RequestParams(CreateMessageRequestParams):
+    """
+    Parameters to configure the AugmentedLLM 'generate' requests.
+    """
+
+    messages: List[SamplingMessage] = Field(exclude=True, default=[])
+    """
+    Ignored. 'messages' are removed from CreateMessageRequestParams 
+    to avoid confusion with the 'message' parameter on 'generate' method.
+    """
+
+    maxTokens: int = 2048
+    """The maximum number of tokens to sample, as requested by the server."""
+
+    model: str | None = None
+    """
+    The model to use for the LLM generation.
+    If specified, this overrides the 'modelPreferences' selection criteria.
+    """
+
+    use_history: bool = True
+    """
+    Include the message history in the generate request.
+    """
+
+    max_iterations: int = 10
+    """
+    The maximum number of iterations to run the LLM for.
+    """
+
+    parallel_tool_calls: bool = True
+    """
+    Whether to allow multiple tool calls per iteration.
+    Also known as multi-step tool use.
+    """

mcp_agent/core/types.py

@@ -2,12 +2,14 @@
 Type definitions for fast-agent core module.
 """
 
-from typing import Dict, Union, TypeAlias, TYPE_CHECKING
+from typing import TYPE_CHECKING, Dict, TypeAlias, Union
 
 from mcp_agent.agents.agent import Agent
+from mcp_agent.workflows.evaluator_optimizer.evaluator_optimizer import (
+    EvaluatorOptimizerLLM,
+)
 from mcp_agent.workflows.orchestrator.orchestrator import Orchestrator
 from mcp_agent.workflows.parallel.parallel_llm import ParallelLLM
-from mcp_agent.workflows.evaluator_optimizer.evaluator_optimizer import EvaluatorOptimizerLLM
 from mcp_agent.workflows.router.router_llm import LLMRouter
 
 # Avoid circular imports
@@ -15,8 +17,6 @@ if TYPE_CHECKING:
     from mcp_agent.core.proxies import BaseAgentProxy
 
 # Type aliases for better readability
-WorkflowType: TypeAlias = Union[
-    Orchestrator, ParallelLLM, EvaluatorOptimizerLLM, LLMRouter
-]
+WorkflowType: TypeAlias = Union[Orchestrator, ParallelLLM, EvaluatorOptimizerLLM, LLMRouter]
 AgentOrWorkflow: TypeAlias = Union[Agent, WorkflowType]
-ProxyDict: TypeAlias = Dict[str, "BaseAgentProxy"]  # Forward reference as string
+ProxyDict: TypeAlias = Dict[str, "BaseAgentProxy"]  # Forward reference as string