fast-agent-mcp 0.0.7__py3-none-any.whl

mcp_agent/agents/agent.py

@@ -0,0 +1,277 @@
+import asyncio
+import uuid
+from dataclasses import dataclass
+from typing import Callable, Dict, List, Optional, TypeVar, Union, TYPE_CHECKING
+
+from mcp.server.fastmcp.tools import Tool as FastTool
+from mcp.types import (
+    CallToolResult,
+    ListToolsResult,
+    TextContent,
+    Tool,
+)
+
+from mcp_agent.mcp.mcp_aggregator import MCPAggregator
+from mcp_agent.workflows.llm.augmented_llm import RequestParams
+from mcp_agent.human_input.types import (
+    HumanInputCallback,
+    HumanInputRequest,
+    HumanInputResponse,
+    HUMAN_INPUT_SIGNAL_NAME,
+)
+from mcp_agent.workflows.llm.augmented_llm import AugmentedLLM
+from mcp_agent.logging.logger import get_logger
+
+if TYPE_CHECKING:
+    from mcp_agent.context import Context
+
+logger = get_logger(__name__)
+
+# Define a TypeVar for AugmentedLLM and its subclasses
+LLM = TypeVar("LLM", bound=AugmentedLLM)
+
+HUMAN_INPUT_TOOL_NAME = "__human_input__"
+
+
+@dataclass
+class AgentConfig:
+    """Configuration for an Agent instance"""
+
+    name: str
+    instruction: Union[str, Callable[[Dict], str]]
+    servers: List[str]
+    model: Optional[str] = None
+    use_history: bool = True
+    default_request_params: Optional[RequestParams] = None
+
+    def __post_init__(self):
+        """Ensure default_request_params exists with proper history setting"""
+
+        if self.default_request_params is None:
+            self.default_request_params = RequestParams(use_history=self.use_history)
+        else:
+            # Override the request params history setting if explicitly configured
+            self.default_request_params.use_history = self.use_history
+
+
+class Agent(MCPAggregator):
+    """
+    An Agent is an entity that has access to a set of MCP servers and can interact with them.
+    Each agent should have a purpose defined by its instruction.
+    """
+
+    def __init__(
+        self,
+        config: Union[
+            AgentConfig, str
+        ],  # Can be AgentConfig or backward compatible str name
+        instruction: Optional[Union[str, Callable[[Dict], str]]] = None,
+        server_names: Optional[List[str]] = None,
+        functions: Optional[List[Callable]] = None,
+        connection_persistence: bool = True,
+        human_input_callback: Optional[HumanInputCallback] = None,
+        context: Optional["Context"] = None,
+        **kwargs,
+    ):
+        # Handle backward compatibility where first arg was name
+        if isinstance(config, str):
+            self.config = AgentConfig(
+                name=config,
+                instruction=instruction or "You are a helpful agent.",
+                servers=server_names or [],
+            )
+        else:
+            self.config = config
+
+        super().__init__(
+            context=context,
+            server_names=self.config.servers,
+            connection_persistence=connection_persistence,
+            name=self.config.name,
+            **kwargs,
+        )
+
+        self.name = self.config.name
+        self.instruction = self.config.instruction
+        self.functions = functions or []
+        self.executor = self.context.executor
+        self.logger = get_logger(f"{__name__}.{self.name}")
+
+        # Store the default request params from config
+        self._default_request_params = self.config.default_request_params
+
+        # Map function names to tools
+        self._function_tool_map: Dict[str, FastTool] = {}
+
+        self.human_input_callback: HumanInputCallback | None = human_input_callback
+        if not human_input_callback:
+            if self.context.human_input_handler:
+                self.human_input_callback = self.context.human_input_handler
+
+    async def initialize(self):
+        """
+        Initialize the agent and connect to the MCP servers.
+        NOTE: This method is called automatically when the agent is used as an async context manager.
+        """
+        await (
+            self.__aenter__()
+        )  # This initializes the connection manager and loads the servers
+
+        for function in self.functions:
+            tool: FastTool = FastTool.from_function(function)
+            self._function_tool_map[tool.name] = tool
+
+    async def attach_llm(self, llm_factory: Callable[..., LLM]) -> LLM:
+        """
+        Create an LLM instance for the agent.
+
+        Args:
+            llm_factory: A callable that constructs an AugmentedLLM or its subclass.
+                        The factory should accept keyword arguments matching the
+                        AugmentedLLM constructor parameters.
+
+        Returns:
+            An instance of AugmentedLLM or one of its subclasses.
+        """
+        return llm_factory(
+            agent=self, default_request_params=self._default_request_params
+        )
+
+    async def shutdown(self):
+        """
+        Shutdown the agent and close all MCP server connections.
+        NOTE: This method is called automatically when the agent is used as an async context manager.
+        """
+        await super().close()
+
+    async def request_human_input(
+        self,
+        request: HumanInputRequest,
+    ) -> str:
+        """
+        Request input from a human user. Pauses the workflow until input is received.
+
+        Args:
+            request: The human input request
+
+        Returns:
+            The input provided by the human
+
+        Raises:
+            TimeoutError: If the timeout is exceeded
+        """
+        if not self.human_input_callback:
+            raise ValueError("Human input callback not set")
+
+        # Generate a unique ID for this request to avoid signal collisions
+        request_id = f"{HUMAN_INPUT_SIGNAL_NAME}_{self.name}_{uuid.uuid4()}"
+        request.request_id = request_id
+
+        self.logger.debug("Requesting human input:", data=request)
+
+        async def call_callback_and_signal():
+            try:
+                user_input = await self.human_input_callback(request)
+                self.logger.debug("Received human input:", data=user_input)
+                await self.executor.signal(signal_name=request_id, payload=user_input)
+            except Exception as e:
+                await self.executor.signal(
+                    request_id, payload=f"Error getting human input: {str(e)}"
+                )
+
+        asyncio.create_task(call_callback_and_signal())
+
+        self.logger.debug("Waiting for human input signal")
+
+        # Wait for signal (workflow is paused here)
+        result = await self.executor.wait_for_signal(
+            signal_name=request_id,
+            request_id=request_id,
+            workflow_id=request.workflow_id,
+            signal_description=request.description or request.prompt,
+            timeout_seconds=request.timeout_seconds,
+            signal_type=HumanInputResponse,  # TODO: saqadri - should this be HumanInputResponse?
+        )
+
+        self.logger.debug("Received human input signal", data=result)
+        return result
+
+    async def list_tools(self) -> ListToolsResult:
+        if not self.initialized:
+            await self.initialize()
+
+        result = await super().list_tools()
+
+        # Add function tools
+        for tool in self._function_tool_map.values():
+            result.tools.append(
+                Tool(
+                    name=tool.name,
+                    description=tool.description,
+                    inputSchema=tool.parameters,
+                )
+            )
+
+        # Add a human_input_callback as a tool
+        if not self.human_input_callback:
+            self.logger.debug("Human input callback not set")
+            return result
+
+        # Add a human_input_callback as a tool
+        human_input_tool: FastTool = FastTool.from_function(self.request_human_input)
+        result.tools.append(
+            Tool(
+                name=HUMAN_INPUT_TOOL_NAME,
+                description=human_input_tool.description,
+                inputSchema=human_input_tool.parameters,
+            )
+        )
+
+        return result
+
+    # todo would prefer to use tool_name to disambiguate agent name
+    async def call_tool(
+        self, name: str, arguments: dict | None = None
+    ) -> CallToolResult:
+        if name == HUMAN_INPUT_TOOL_NAME:
+            # Call the human input tool
+            return await self._call_human_input_tool(arguments)
+        elif name in self._function_tool_map:
+            # Call local function and return the result as a text response
+            tool = self._function_tool_map[name]
+            result = await tool.run(arguments)
+            return CallToolResult(content=[TextContent(type="text", text=str(result))])
+        else:
+            return await super().call_tool(name, arguments)
+
+    async def _call_human_input_tool(
+        self, arguments: dict | None = None
+    ) -> CallToolResult:
+        # Handle human input request
+        try:
+            request = HumanInputRequest(**arguments.get("request"))
+            result: HumanInputResponse = await self.request_human_input(request=request)
+            return CallToolResult(
+                content=[
+                    TextContent(type="text", text=f"Human response: {result.response}")
+                ]
+            )
+        except TimeoutError as e:
+            return CallToolResult(
+                isError=True,
+                content=[
+                    TextContent(
+                        type="text",
+                        text=f"Error: Human input request timed out: {str(e)}",
+                    )
+                ],
+            )
+        except Exception as e:
+            return CallToolResult(
+                isError=True,
+                content=[
+                    TextContent(
+                        type="text", text=f"Error requesting human input: {str(e)}"
+                    )
+                ],
+            )

mcp_agent/app.py

@@ -0,0 +1,303 @@
+from typing import Any, Dict, Optional, Type, TypeVar, Callable
+from datetime import timedelta
+import asyncio
+from contextlib import asynccontextmanager
+
+from mcp import ServerSession
+from mcp_agent.context import Context, initialize_context, cleanup_context
+from mcp_agent.config import Settings
+from mcp_agent.event_progress import ProgressAction
+from mcp_agent.logging.logger import get_logger
+from mcp_agent.executor.workflow_signal import SignalWaitCallback
+from mcp_agent.human_input.types import HumanInputCallback
+from mcp_agent.human_input.handler import console_input_callback
+from mcp_agent.workflows.llm.llm_selector import ModelSelector
+
+R = TypeVar("R")
+
+
+class MCPApp:
+    """
+    Main application class that manages global state and can host workflows.
+
+    Example usage:
+        app = MCPApp()
+
+        @app.workflow
+        class MyWorkflow(Workflow[str]):
+            @app.task
+            async def my_task(self):
+                pass
+
+            async def run(self):
+                await self.my_task()
+
+        async with app.run() as running_app:
+            workflow = MyWorkflow()
+            result = await workflow.execute()
+    """
+
+    def __init__(
+        self,
+        name: str = "mcp_application",
+        settings: Optional[Settings] | str = None,
+        human_input_callback: Optional[HumanInputCallback] = console_input_callback,
+        signal_notification: Optional[SignalWaitCallback] = None,
+        upstream_session: Optional["ServerSession"] = None,
+        model_selector: ModelSelector = None,
+    ):
+        """
+        Initialize the application with a name and optional settings.
+        Args:
+            name: Name of the application
+            settings: Application configuration - If unspecified, the settings are loaded from mcp_agent.config.yaml.
+                If this is a string, it is treated as the path to the config file to load.
+            human_input_callback: Callback for handling human input
+            signal_notification: Callback for getting notified on workflow signals/events.
+            upstream_session: Optional upstream session if the MCPApp is running as a server to an MCP client.
+            initialize_model_selector: Initializes the built-in ModelSelector to help with model selection. Defaults to False.
+        """
+        self.name = name
+
+        # We use these to initialize the context in initialize()
+        self._config_or_path = settings
+        self._human_input_callback = human_input_callback
+        self._signal_notification = signal_notification
+        self._upstream_session = upstream_session
+        self._model_selector = model_selector
+
+        self._workflows: Dict[str, Type] = {}  # id to workflow class
+        self._logger = None
+        self._context: Optional[Context] = None
+        self._initialized = False
+
+    @property
+    def context(self) -> Context:
+        if self._context is None:
+            raise RuntimeError(
+                "MCPApp not initialized, please call initialize() first, or use async with app.run()."
+            )
+        return self._context
+
+    @property
+    def config(self):
+        return self._context.config
+
+    @property
+    def server_registry(self):
+        return self._context.server_registry
+
+    @property
+    def executor(self):
+        return self._context.executor
+
+    @property
+    def engine(self):
+        return self.executor.execution_engine
+
+    @property
+    def upstream_session(self):
+        return self._context.upstream_session
+
+    @upstream_session.setter
+    def upstream_session(self, value):
+        self._context.upstream_session = value
+
+    @property
+    def workflows(self):
+        return self._workflows
+
+    @property
+    def tasks(self):
+        return self.context.task_registry.list_activities()
+
+    @property
+    def logger(self):
+        if self._logger is None:
+            self._logger = get_logger(f"mcp_agent.{self.name}")
+        return self._logger
+
+    async def initialize(self):
+        """Initialize the application."""
+        if self._initialized:
+            return
+
+        self._context = await initialize_context(self._config_or_path)
+
+        # Set the properties that were passed in the constructor
+        self._context.human_input_handler = self._human_input_callback
+        self._context.signal_notification = self._signal_notification
+        self._context.upstream_session = self._upstream_session
+        self._context.model_selector = self._model_selector
+
+        self._initialized = True
+        self.logger.info(
+            "MCPAgent initialized",
+            data={
+                "progress_action": "Running",
+                "target": self.name,
+                "agent_name": "mcp_application_loop",
+            },
+        )
+
+    async def cleanup(self):
+        """Cleanup application resources."""
+        if not self._initialized:
+            return
+
+        # Updatre progress display before logging is shut down
+        self.logger.info(
+            "MCPAgent cleanup",
+            data={
+                "progress_action": ProgressAction.FINISHED,
+                "target": self.name,
+                "agent_name": "mcp_application_loop",
+            },
+        )
+        await cleanup_context()
+        self._context = None
+        self._initialized = False
+
+    @asynccontextmanager
+    async def run(self):
+        """
+        Run the application. Use as context manager.
+
+        Example:
+            async with app.run() as running_app:
+                # App is initialized here
+                pass
+        """
+        await self.initialize()
+        try:
+            yield self
+        finally:
+            await self.cleanup()
+
+    def workflow(
+        self, cls: Type, *args, workflow_id: str | None = None, **kwargs
+    ) -> Type:
+        """
+        Decorator for a workflow class. By default it's a no-op,
+        but different executors can use this to customize behavior
+        for workflow registration.
+
+        Example:
+            If Temporal is available & we use a TemporalExecutor,
+            this decorator will wrap with temporal_workflow.defn.
+        """
+        decorator_registry = self.context.decorator_registry
+        execution_engine = self.engine
+        workflow_defn_decorator = decorator_registry.get_workflow_defn_decorator(
+            execution_engine
+        )
+
+        if workflow_defn_decorator:
+            return workflow_defn_decorator(cls, *args, **kwargs)
+
+        cls._app = self
+        self._workflows[workflow_id or cls.__name__] = cls
+
+        # Default no-op
+        return cls
+
+    def workflow_run(self, fn: Callable[..., R]) -> Callable[..., R]:
+        """
+        Decorator for a workflow's main 'run' method.
+        Different executors can use this to customize behavior for workflow execution.
+
+        Example:
+            If Temporal is in use, this gets converted to @workflow.run.
+        """
+
+        decorator_registry = self.context.decorator_registry
+        execution_engine = self.engine
+        workflow_run_decorator = decorator_registry.get_workflow_run_decorator(
+            execution_engine
+        )
+
+        if workflow_run_decorator:
+            return workflow_run_decorator(fn)
+
+        # Default no-op
+        def wrapper(*args, **kwargs):
+            # no-op wrapper
+            return fn(*args, **kwargs)
+
+        return wrapper
+
+    def workflow_task(
+        self,
+        name: str | None = None,
+        schedule_to_close_timeout: timedelta | None = None,
+        retry_policy: Dict[str, Any] | None = None,
+        **kwargs: Any,
+    ) -> Callable[[Callable[..., R]], Callable[..., R]]:
+        """
+        Decorator to mark a function as a workflow task,
+        automatically registering it in the global activity registry.
+
+        Args:
+            name: Optional custom name for the activity
+            schedule_to_close_timeout: Maximum time the task can take to complete
+            retry_policy: Retry policy configuration
+            **kwargs: Additional metadata passed to the activity registration
+
+        Returns:
+            Decorated function that preserves async and typing information
+
+        Raises:
+            TypeError: If the decorated function is not async
+            ValueError: If the retry policy or timeout is invalid
+        """
+
+        def decorator(func: Callable[..., R]) -> Callable[..., R]:
+            if not asyncio.iscoroutinefunction(func):
+                raise TypeError(f"Function {func.__name__} must be async.")
+
+            actual_name = name or f"{func.__module__}.{func.__qualname__}"
+            timeout = schedule_to_close_timeout or timedelta(minutes=10)
+            metadata = {
+                "activity_name": actual_name,
+                "schedule_to_close_timeout": timeout,
+                "retry_policy": retry_policy or {},
+                **kwargs,
+            }
+            activity_registry = self.context.task_registry
+            activity_registry.register(actual_name, func, metadata)
+
+            setattr(func, "is_workflow_task", True)
+            setattr(func, "execution_metadata", metadata)
+
+            # TODO: saqadri - determine if we need this
+            # Preserve metadata through partial application
+            # @functools.wraps(func)
+            # async def wrapper(*args: Any, **kwargs: Any) -> R:
+            #     result = await func(*args, **kwargs)
+            #     return cast(R, result)  # Ensure type checking works
+
+            # # Add metadata that survives partial application
+            # wrapper.is_workflow_task = True  # type: ignore
+            # wrapper.execution_metadata = metadata  # type: ignore
+
+            # # Make metadata accessible through partial
+            # def __getattr__(name: str) -> Any:
+            #     if name == "is_workflow_task":
+            #         return True
+            #     if name == "execution_metadata":
+            #         return metadata
+            #     raise AttributeError(f"'{func.__name__}' has no attribute '{name}'")
+
+            # wrapper.__getattr__ = __getattr__  # type: ignore
+
+            # return wrapper
+
+            return func
+
+        return decorator
+
+    def is_workflow_task(self, func: Callable[..., Any]) -> bool:
+        """
+        Check if a function is marked as a workflow task.
+        This gets set for functions that are decorated with @workflow_task."""
+        return bool(getattr(func, "is_workflow_task", False))

mcp_agent/cli/__main__.py

@@ -0,0 +1,4 @@
+from mcp_agent.cli.main import app
+
+if __name__ == "__main__":
+    app()