fast-agent-mcp 0.1.12__py3-none-any.whl → 0.2.0__py3-none-any.whl

mcp_agent/human_input/handler.py

@@ -1,13 +1,14 @@
 import asyncio
+
 from rich.panel import Panel
 
 from mcp_agent.console import console
+from mcp_agent.core.enhanced_prompt import get_enhanced_input, handle_special_commands
 from mcp_agent.human_input.types import (
     HumanInputRequest,
     HumanInputResponse,
 )
 from mcp_agent.progress_display import progress_display
-from mcp_agent.core.enhanced_prompt import get_enhanced_input, handle_special_commands
 
 
 async def console_input_callback(request: HumanInputRequest) -> HumanInputResponse:
@@ -30,9 +31,7 @@ async def console_input_callback(request: HumanInputRequest) -> HumanInputRespon
 
     # Extract agent name from metadata dictionary
     agent_name = (
-        request.metadata.get("agent_name", "Unknown Agent")
-        if request.metadata
-        else "Unknown Agent"
+        request.metadata.get("agent_name", "Unknown Agent") if request.metadata else "Unknown Agent"
     )
 
     # Use the context manager to pause the progress display while getting input
@@ -70,9 +69,7 @@ async def console_input_callback(request: HumanInputRequest) -> HumanInputRespon
             if isinstance(command_result, dict) and "list_prompts" in command_result:
                 from rich import print as rich_print
 
-                rich_print(
-                    "[yellow]Prompt listing not available in human input context[/yellow]"
-                )
+                rich_print("[yellow]Prompt listing not available in human input context[/yellow]")
 
         except KeyboardInterrupt:
             console.print("\n[yellow]Input interrupted[/yellow]")

mcp_agent/human_input/types.py

@@ -1,4 +1,5 @@
 from typing import Any, AsyncIterator, Protocol
+
 from pydantic import BaseModel
 
 HUMAN_INPUT_SIGNAL_NAME = "__human_input__"
@@ -42,9 +43,7 @@ class HumanInputResponse(BaseModel):
 class HumanInputCallback(Protocol):
     """Protocol for callbacks that handle human input requests."""
 
-    async def __call__(
-        self, request: HumanInputRequest
-    ) -> AsyncIterator[HumanInputResponse]:
+    async def __call__(self, request: HumanInputRequest) -> AsyncIterator[HumanInputResponse]:
         """
         Handle a human input request.
 

mcp_agent/llm/__init__.py

@@ -0,0 +1,2 @@
+# LLM module
+# Contains code for working with large language models

mcp_agent/llm/augmented_llm.py

@@ -0,0 +1,450 @@
+from abc import abstractmethod
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Generic,
+    List,
+    Optional,
+    Type,
+    TypeVar,
+    cast,
+)
+
+from mcp.types import (
+    CallToolRequest,
+    CallToolResult,
+    GetPromptResult,
+    PromptMessage,
+    TextContent,
+)
+from pydantic_core import from_json
+from rich.text import Text
+
+from mcp_agent.context_dependent import ContextDependent
+from mcp_agent.core.exceptions import PromptExitError
+from mcp_agent.core.prompt import Prompt
+from mcp_agent.core.request_params import RequestParams
+from mcp_agent.event_progress import ProgressAction
+from mcp_agent.llm.memory import Memory, SimpleMemory
+from mcp_agent.llm.sampling_format_converter import (
+    BasicFormatConverter,
+    ProviderFormatConverter,
+)
+from mcp_agent.logging.logger import get_logger
+from mcp_agent.mcp.interfaces import (
+    AugmentedLLMProtocol,
+    ModelT,
+)
+from mcp_agent.mcp.mcp_aggregator import MCPAggregator
+from mcp_agent.mcp.prompt_message_multipart import PromptMessageMultipart
+from mcp_agent.mcp.prompt_render import render_multipart_message
+from mcp_agent.mcp.prompt_serialization import multipart_messages_to_delimited_format
+from mcp_agent.ui.console_display import ConsoleDisplay
+
+# Define type variables locally
+MessageParamT = TypeVar("MessageParamT")
+MessageT = TypeVar("MessageT")
+
+# Forward reference for type annotations
+if TYPE_CHECKING:
+    from mcp_agent.agents.agent import Agent
+    from mcp_agent.context import Context
+
+
+# TODO -- move this to a constant
+HUMAN_INPUT_TOOL_NAME = "__human_input__"
+
+
+class AugmentedLLM(ContextDependent, AugmentedLLMProtocol, Generic[MessageParamT, MessageT]):
+    """
+    The basic building block of agentic systems is an LLM enhanced with augmentations
+    such as retrieval, tools, and memory provided from a collection of MCP servers.
+    Our current models can actively use these capabilities—generating their own search queries,
+    selecting appropriate tools, and determining what information to retain.
+    """
+
+    provider: str | None = None
+
+    def __init__(
+        self,
+        agent: Optional["Agent"] = None,
+        server_names: List[str] | None = None,
+        instruction: str | None = None,
+        name: str | None = None,
+        request_params: RequestParams | None = None,
+        type_converter: Type[
+            ProviderFormatConverter[MessageParamT, MessageT]
+        ] = BasicFormatConverter,
+        context: Optional["Context"] = None,
+        **kwargs: dict[str, Any],
+    ) -> None:
+        """
+        Initialize the LLM with a list of server names and an instruction.
+        If a name is provided, it will be used to identify the LLM.
+        If an agent is provided, all other properties are optional
+        """
+        # Extract request_params before super() call
+        self._init_request_params = request_params
+        super().__init__(context=context, **kwargs)
+        self.logger = get_logger(__name__)
+        self.executor = self.context.executor
+        self.aggregator = agent if agent is not None else MCPAggregator(server_names or [])
+        self.name = agent.name if agent else name
+        self.instruction = agent.instruction if agent else instruction
+
+        # memory contains provider specific API types.
+        self.history: Memory[MessageParamT] = SimpleMemory[MessageParamT]()
+
+        self.message_history: List[PromptMessageMultipart] = []
+
+        # Initialize the display component
+        self.display = ConsoleDisplay(config=self.context.config)
+
+        # Initialize default parameters
+        self.default_request_params = self._initialize_default_params(kwargs)
+
+        # Merge with provided params if any
+        if self._init_request_params:
+            self.default_request_params = self._merge_request_params(
+                self.default_request_params, self._init_request_params
+            )
+
+        self.type_converter = type_converter
+        self.verb = kwargs.get("verb")
+
+    def _initialize_default_params(self, kwargs: dict) -> RequestParams:
+        """Initialize default parameters for the LLM.
+        Should be overridden by provider implementations to set provider-specific defaults."""
+        return RequestParams(
+            systemPrompt=self.instruction,
+            parallel_tool_calls=True,
+            max_iterations=10,
+            use_history=True,
+        )
+
+    async def structured(
+        self,
+        prompt: List[PromptMessageMultipart],
+        model: Type[ModelT],
+        request_params: RequestParams | None = None,
+    ) -> ModelT | None:
+        """Apply the prompt and return the result as a Pydantic model, or None if coercion fails"""
+        try:
+            result: PromptMessageMultipart = await self.generate(prompt, request_params)
+            json_data = from_json(result.first_text(), allow_partial=True)
+            validated_model = model.model_validate(json_data)
+            return cast("ModelT", validated_model)
+        except Exception as e:
+            logger = get_logger(__name__)
+            logger.error(f"Failed to parse structured response: {str(e)}")
+            return None
+
+    async def generate(
+        self,
+        multipart_messages: List[PromptMessageMultipart],
+        request_params: RequestParams | None = None,
+    ) -> PromptMessageMultipart:
+        """
+        Create a completion with the LLM using the provided messages.
+        """
+        if multipart_messages[-1].first_text().startswith("***SAVE_HISTORY"):
+            parts: list[str] = multipart_messages[-1].first_text().split(" ", 1)
+            filename: str = (
+                parts[1].strip() if len(parts) > 1 else f"{self.name or 'assistant'}_prompts.txt"
+            )
+            await self._save_history(filename)
+            self.show_user_message(
+                f"History saved to {filename}", model=self.default_request_params.model, chat_turn=0
+            )
+            return Prompt.assistant(f"History saved to {filename}")
+
+        self.message_history.extend(multipart_messages)
+
+        if multipart_messages[-1].role == "user":
+            self.show_user_message(
+                render_multipart_message(multipart_messages[-1]),
+                model=self.default_request_params.model,
+                chat_turn=self.chat_turn(),
+            )
+
+        assistant_response: PromptMessageMultipart = await self._apply_prompt_provider_specific(
+            multipart_messages, request_params
+        )
+
+        self.message_history.append(assistant_response)
+        return assistant_response
+
+    def chat_turn(self) -> int:
+        """Return the current chat turn number"""
+        return 1 + sum(1 for message in self.message_history if message.role == "assistant")
+
+    def _merge_request_params(
+        self, default_params: RequestParams, provided_params: RequestParams
+    ) -> RequestParams:
+        """Merge default and provided request parameters"""
+
+        merged = default_params.model_dump()
+        merged.update(provided_params.model_dump(exclude_unset=True))
+        final_params = RequestParams(**merged)
+
+        return final_params
+
+    def get_request_params(
+        self,
+        request_params: RequestParams | None = None,
+        default: RequestParams | None = None,
+    ) -> RequestParams:
+        """
+        Get request parameters with merged-in defaults and overrides.
+        Args:
+            request_params: The request parameters to use as overrides.
+            default: The default request parameters to use as the base.
+                If unspecified, self.default_request_params will be used.
+        """
+        # Start with the defaults
+        default_request_params = default or self.default_request_params
+
+        if not default_request_params:
+            default_request_params = self._initialize_default_params({})
+
+        # If user provides overrides, merge them with defaults
+        if request_params:
+            return self._merge_request_params(default_request_params, request_params)
+
+        return default_request_params
+
+    @classmethod
+    def convert_message_to_message_param(
+        cls, message: MessageT, **kwargs: dict[str, Any]
+    ) -> MessageParamT:
+        """Convert a response object to an input parameter object to allow LLM calls to be chained."""
+        # Many LLM implementations will allow the same type for input and output messages
+        return cast("MessageParamT", message)
+
+    def show_tool_result(self, result: CallToolResult) -> None:
+        """Display a tool result in a formatted panel."""
+        self.display.show_tool_result(result)
+
+    def show_oai_tool_result(self, result: str) -> None:
+        """Display a tool result in a formatted panel."""
+        self.display.show_oai_tool_result(result)
+
+    def show_tool_call(self, available_tools, tool_name, tool_args) -> None:
+        """Display a tool call in a formatted panel."""
+        self.display.show_tool_call(available_tools, tool_name, tool_args)
+
+    async def show_assistant_message(
+        self,
+        message_text: str | Text | None,
+        highlight_namespaced_tool: str = "",
+        title: str = "ASSISTANT",
+    ) -> None:
+        if message_text is None:
+            message_text = Text("No content to display", style="dim green italic")
+        """Display an assistant message in a formatted panel."""
+        await self.display.show_assistant_message(
+            message_text,
+            aggregator=self.aggregator,
+            highlight_namespaced_tool=highlight_namespaced_tool,
+            title=title,
+            name=self.name,
+        )
+
+    def show_user_message(self, message, model: str | None, chat_turn: int) -> None:
+        """Display a user message in a formatted panel."""
+        self.display.show_user_message(message, model, chat_turn, name=self.name)
+
+    async def pre_tool_call(
+        self, tool_call_id: str | None, request: CallToolRequest
+    ) -> CallToolRequest | bool:
+        """Called before a tool is executed. Return False to prevent execution."""
+        return request
+
+    async def post_tool_call(
+        self, tool_call_id: str | None, request: CallToolRequest, result: CallToolResult
+    ) -> CallToolResult:
+        """Called after a tool execution. Can modify the result before it's returned."""
+        return result
+
+    async def call_tool(
+        self,
+        request: CallToolRequest,
+        tool_call_id: str | None = None,
+    ) -> CallToolResult:
+        """Call a tool with the given parameters and optional ID"""
+
+        try:
+            preprocess = await self.pre_tool_call(
+                tool_call_id=tool_call_id,
+                request=request,
+            )
+
+            if isinstance(preprocess, bool):
+                if not preprocess:
+                    return CallToolResult(
+                        isError=True,
+                        content=[
+                            TextContent(
+                                type="text",
+                                text=f"Error: Tool '{request.params.name}' was not allowed to run.",
+                            )
+                        ],
+                    )
+            else:
+                request = preprocess
+
+            tool_name = request.params.name
+            tool_args = request.params.arguments
+            result = await self.aggregator.call_tool(tool_name, tool_args)
+
+            postprocess = await self.post_tool_call(
+                tool_call_id=tool_call_id, request=request, result=result
+            )
+
+            if isinstance(postprocess, CallToolResult):
+                result = postprocess
+
+            return result
+        except PromptExitError:
+            raise
+        except Exception as e:
+            return CallToolResult(
+                isError=True,
+                content=[
+                    TextContent(
+                        type="text",
+                        text=f"Error executing tool '{request.params.name}': {str(e)}",
+                    )
+                ],
+            )
+
+    def _log_chat_progress(
+        self, chat_turn: Optional[int] = None, model: Optional[str] = None
+    ) -> None:
+        """Log a chat progress event"""
+        # Determine action type based on verb
+        if hasattr(self, "verb") and self.verb:
+            # Use verb directly regardless of type
+            act = self.verb
+        else:
+            act = ProgressAction.CHATTING
+
+        data = {
+            "progress_action": act,
+            "model": model,
+            "agent_name": self.name,
+            "chat_turn": chat_turn if chat_turn is not None else None,
+        }
+        self.logger.debug("Chat in progress", data=data)
+
+    def _log_chat_finished(self, model: Optional[str] = None) -> None:
+        """Log a chat finished event"""
+        data = {
+            "progress_action": ProgressAction.READY,
+            "model": model,
+            "agent_name": self.name,
+        }
+        self.logger.debug("Chat finished", data=data)
+
+    def _convert_prompt_messages(self, prompt_messages: List[PromptMessage]) -> List[MessageParamT]:
+        """
+        Convert prompt messages to this LLM's specific message format.
+        To be implemented by concrete LLM classes.
+        """
+        raise NotImplementedError("Must be implemented by subclass")
+
+    async def show_prompt_loaded(
+        self,
+        prompt_name: str,
+        description: Optional[str] = None,
+        message_count: int = 0,
+        arguments: Optional[dict[str, str]] = None,
+    ) -> None:
+        """
+        Display information about a loaded prompt template.
+
+        Args:
+            prompt_name: The name of the prompt
+            description: Optional description of the prompt
+            message_count: Number of messages in the prompt
+            arguments: Optional dictionary of arguments passed to the prompt
+        """
+        await self.display.show_prompt_loaded(
+            prompt_name=prompt_name,
+            description=description,
+            message_count=message_count,
+            agent_name=self.name,
+            aggregator=self.aggregator,
+            arguments=arguments,
+        )
+
+    async def apply_prompt_template(self, prompt_result: GetPromptResult, prompt_name: str) -> str:
+        """
+        Apply a prompt template by adding it to the conversation history.
+        If the last message in the prompt is from a user, automatically
+        generate an assistant response.
+
+        Args:
+            prompt_result: The GetPromptResult containing prompt messages
+            prompt_name: The name of the prompt being applied
+
+        Returns:
+            String representation of the assistant's response if generated,
+            or the last assistant message in the prompt
+        """
+        from mcp_agent.mcp.prompt_message_multipart import PromptMessageMultipart
+
+        # Check if we have any messages
+        if not prompt_result.messages:
+            return "Prompt contains no messages"
+
+        # Extract arguments if they were stored in the result
+        arguments = getattr(prompt_result, "arguments", None)
+
+        # Display information about the loaded prompt
+        await self.show_prompt_loaded(
+            prompt_name=prompt_name,
+            description=prompt_result.description,
+            message_count=len(prompt_result.messages),
+            arguments=arguments,
+        )
+
+        # Convert to PromptMessageMultipart objects
+        multipart_messages = PromptMessageMultipart.parse_get_prompt_result(prompt_result)
+
+        # Delegate to the provider-specific implementation
+        result = await self._apply_prompt_provider_specific(multipart_messages, None)
+        return result.first_text()
+
+    async def _save_history(self, filename: str) -> None:
+        """
+        Save the Message History to a file in a simple delimeted format.
+        """
+        # Convert to delimited format
+        delimited_content = multipart_messages_to_delimited_format(
+            self.message_history,
+        )
+
+        # Write to file
+        with open(filename, "w", encoding="utf-8") as f:
+            f.write("\n\n".join(delimited_content))
+
+    @abstractmethod
+    async def _apply_prompt_provider_specific(
+        self,
+        multipart_messages: List["PromptMessageMultipart"],
+        request_params: RequestParams | None = None,
+    ) -> PromptMessageMultipart:
+        """
+        Provider-specific implementation of apply_prompt_template.
+        This default implementation handles basic text content for any LLM type.
+        Provider-specific subclasses should override this method to handle
+        multimodal content appropriately.
+
+        Args:
+            multipart_messages: List of PromptMessageMultipart objects parsed from the prompt template
+
+        Returns:
+            String representation of the assistant's response if generated,
+            or the last assistant message in the prompt
+        """

mcp_agent/llm/augmented_llm_passthrough.py

@@ -0,0 +1,162 @@
+import json  # Import at the module level
+from typing import Any, List, Optional, Union
+
+from mcp.types import PromptMessage
+
+from mcp_agent.core.prompt import Prompt
+from mcp_agent.llm.augmented_llm import (
+    AugmentedLLM,
+    MessageParamT,
+    RequestParams,
+)
+from mcp_agent.logging.logger import get_logger
+from mcp_agent.mcp.prompt_message_multipart import PromptMessageMultipart
+
+CALL_TOOL_INDICATOR = "***CALL_TOOL"
+FIXED_RESPONSE_INDICATOR = "***FIXED_RESPONSE"
+
+
+class PassthroughLLM(AugmentedLLM):
+    """
+    A specialized LLM implementation that simply passes through input messages without modification.
+
+    This is useful for cases where you need an object with the AugmentedLLM interface
+    but want to preserve the original message without any processing, such as in a
+    parallel workflow where no fan-in aggregation is needed.
+    """
+
+    def __init__(self, name: str = "Passthrough", **kwargs: dict[str, Any]) -> None:
+        super().__init__(name=name, **kwargs)
+        self.provider = "fast-agent"
+        self.logger = get_logger(__name__)
+        self._messages = [PromptMessage]
+        self._fixed_response: str | None = None
+
+    async def generate_str(
+        self,
+        message: Union[str, MessageParamT, List[MessageParamT]],
+        request_params: Optional[RequestParams] = None,
+    ) -> str:
+        """Return the input message as a string."""
+        # Check if this is a special command to call a tool
+        if isinstance(message, str) and message.startswith("***CALL_TOOL "):
+            return await self._call_tool_and_return_result(message)
+
+        self.show_user_message(message, model="fastagent-passthrough", chat_turn=0)
+        await self.show_assistant_message(message, title="ASSISTANT/PASSTHROUGH")
+
+        # Handle PromptMessage by concatenating all parts
+        if isinstance(message, PromptMessage):
+            parts_text = []
+            for part in message.content:
+                parts_text.append(str(part))
+            return "\n".join(parts_text)
+
+        return str(message)
+
+    async def initialize(self) -> None:
+        pass
+
+    async def _call_tool_and_return_result(self, command: str) -> str:
+        """
+        Call a tool based on the command and return its result as a string.
+
+        Args:
+            command: The command string, expected format: "***CALL_TOOL <server>-<tool_name> [arguments_json]"
+
+        Returns:
+            Tool result as a string
+        """
+        try:
+            tool_name, arguments = self._parse_tool_command(command)
+            result = await self.aggregator.call_tool(tool_name, arguments)
+            return self._format_tool_result(tool_name, result)
+        except Exception as e:
+            self.logger.error(f"Error calling tool: {str(e)}")
+            return f"Error calling tool: {str(e)}"
+
+    def _parse_tool_command(self, command: str) -> tuple[str, Optional[dict]]:
+        """
+        Parse a tool command string into tool name and arguments.
+
+        Args:
+            command: The command string in format "***CALL_TOOL <tool_name> [arguments_json]"
+
+        Returns:
+            Tuple of (tool_name, arguments_dict)
+
+        Raises:
+            ValueError: If command format is invalid
+        """
+        parts = command.split(" ", 2)
+        if len(parts) < 2:
+            raise ValueError("Invalid format. Expected '***CALL_TOOL <tool_name> [arguments_json]'")
+
+        tool_name = parts[1].strip()
+        arguments = None
+
+        if len(parts) > 2:
+            try:
+                arguments = json.loads(parts[2])
+            except json.JSONDecodeError:
+                raise ValueError(f"Invalid JSON arguments: {parts[2]}")
+
+        self.logger.info(f"Calling tool {tool_name} with arguments {arguments}")
+        return tool_name, arguments
+
+    def _format_tool_result(self, tool_name: str, result) -> str:
+        """
+        Format tool execution result as a string.
+
+        Args:
+            tool_name: The name of the tool that was called
+            result: The result returned from the tool
+
+        Returns:
+            Formatted result as a string
+        """
+        if result.isError:
+            error_text = []
+            for content_item in result.content:
+                if hasattr(content_item, "text"):
+                    error_text.append(content_item.text)
+                else:
+                    error_text.append(str(content_item))
+            error_message = "\n".join(error_text) if error_text else "Unknown error"
+            return f"Error calling tool '{tool_name}': {error_message}"
+
+        result_text = []
+        for content_item in result.content:
+            if hasattr(content_item, "text"):
+                result_text.append(content_item.text)
+            else:
+                result_text.append(str(content_item))
+
+        return "\n".join(result_text)
+
+    async def _apply_prompt_provider_specific(
+        self,
+        multipart_messages: List["PromptMessageMultipart"],
+        request_params: RequestParams | None = None,
+    ) -> PromptMessageMultipart:
+        last_message = multipart_messages[-1]
+
+        # TODO -- improve when we support Audio/Multimodal gen
+        if self.is_tool_call(last_message):
+            return Prompt.assistant(await self.generate_str(last_message.first_text()))
+
+        if last_message.first_text().startswith(FIXED_RESPONSE_INDICATOR):
+            self._fixed_response = (
+                last_message.first_text().split(FIXED_RESPONSE_INDICATOR, 1)[1].strip()
+            )
+
+        if self._fixed_response:
+            await self.show_assistant_message(self._fixed_response)
+            return Prompt.assistant(self._fixed_response)
+        else:
+            concatenated: str = "\n".join(message.all_text() for message in multipart_messages)
+            await self.show_assistant_message(concatenated)
+            return Prompt.assistant(concatenated)
+
+    def is_tool_call(self, message: PromptMessageMultipart) -> bool:
+        return message.first_text().startswith(CALL_TOOL_INDICATOR)