fast-agent-mcp 0.3.5__py3-none-any.whl → 0.3.7__py3-none-any.whl

fast_agent/mcp/prompt_serialization.py

@@ -23,6 +23,7 @@ from mcp.types import (
     EmbeddedResource,
     GetPromptResult,
     ImageContent,
+    PromptMessage,
     TextContent,
     TextResourceContents,
 )
@@ -34,12 +35,30 @@ from fast_agent.mcp.prompts.prompt_constants import (
 )
 from fast_agent.types import PromptMessageExtended
 
+# -------------------------------------------------------------------------
+# Serialization Helpers
+# -------------------------------------------------------------------------
+
+
+def serialize_to_dict(obj, exclude_none: bool = True):
+    """Standardized Pydantic serialization to dictionary.
+
+    Args:
+        obj: Pydantic model object to serialize
+        exclude_none: Whether to exclude None values (default: True)
+
+    Returns:
+        Dictionary representation suitable for JSON serialization
+    """
+    return obj.model_dump(by_alias=True, mode="json", exclude_none=exclude_none)
+
+
 # -------------------------------------------------------------------------
 # JSON Serialization Functions
 # -------------------------------------------------------------------------
 
 
-def multipart_messages_to_get_prompt_result(
+def to_get_prompt_result(
     messages: List[PromptMessageExtended],
 ) -> GetPromptResult:
     """
@@ -60,35 +79,58 @@ def multipart_messages_to_get_prompt_result(
     return GetPromptResult(messages=flat_messages)
 
 
-def multipart_messages_to_json(messages: List[PromptMessageExtended]) -> str:
+
+def to_get_prompt_result_json(messages: List[PromptMessageExtended]) -> str:
+    """
+    Convert PromptMessageExtended objects to MCP-compatible GetPromptResult JSON.
+
+    This is a lossy conversion that flattens multipart messages and loses extended fields
+    like tool_calls, channels, and stop_reason. Use for MCP server compatibility.
+
+    Args:
+        messages: List of PromptMessageExtended objects
+
+    Returns:
+        JSON string in GetPromptResult format
+    """
+    result = to_get_prompt_result(messages)
+    result_dict = serialize_to_dict(result)
+    return json.dumps(result_dict, indent=2)
+
+
+def to_json(messages: List[PromptMessageExtended]) -> str:
     """
-    Convert PromptMessageExtended objects to a pure JSON string in GetPromptResult format.
+    Convert PromptMessageExtended objects directly to JSON, preserving all extended fields.
 
-    This approach preserves all data and structure exactly as is, compatible with
-    the MCP GetPromptResult type.
+    This preserves tool_calls, tool_results, channels, and stop_reason that would be lost
+    in the standard GetPromptResult conversion.
 
     Args:
         messages: List of PromptMessageExtended objects
 
     Returns:
-        JSON string representation with GetPromptResult container
+        JSON string representation preserving all PromptMessageExtended data
     """
-    # First convert to GetPromptResult
-    result = multipart_messages_to_get_prompt_result(messages)
+    # Convert each message to dict using standardized serialization
+    messages_dicts = [serialize_to_dict(msg) for msg in messages]
 
-    # Convert to dictionary using model_dump with proper JSON mode
-    result_dict = result.model_dump(by_alias=True, mode="json", exclude_none=True)
+    # Wrap in a container similar to GetPromptResult for consistency
+    result_dict = {"messages": messages_dicts}
 
     # Convert to JSON string
     return json.dumps(result_dict, indent=2)
 
 
-def json_to_extended_messages(json_str: str) -> List[PromptMessageExtended]:
+def from_json(json_str: str) -> List[PromptMessageExtended]:
     """
-    Parse a JSON string in GetPromptResult format into PromptMessageExtended objects.
+    Parse a JSON string into PromptMessageExtended objects.
+
+    Handles both:
+    - Enhanced format with full PromptMessageExtended data
+    - Legacy GetPromptResult format (missing extended fields default to None)
 
     Args:
-        json_str: JSON string representation of GetPromptResult
+        json_str: JSON string representation
 
     Returns:
         List of PromptMessageExtended objects
@@ -96,31 +138,66 @@ def json_to_extended_messages(json_str: str) -> List[PromptMessageExtended]:
     # Parse JSON to dictionary
     result_dict = json.loads(json_str)
 
-    # Parse as GetPromptResult
-    result = GetPromptResult.model_validate(result_dict)
+    # Extract messages array
+    messages_data = result_dict.get("messages", [])
+
+    extended_messages: List[PromptMessageExtended] = []
+    basic_buffer: List[PromptMessage] = []
+
+    def flush_basic_buffer() -> None:
+        nonlocal basic_buffer
+        if not basic_buffer:
+            return
+        extended_messages.extend(PromptMessageExtended.to_extended(basic_buffer))
+        basic_buffer = []
+
+    for msg_data in messages_data:
+        content = msg_data.get("content")
+        is_enhanced = isinstance(content, list)
+        if is_enhanced:
+            try:
+                msg = PromptMessageExtended.model_validate(msg_data)
+            except Exception:
+                is_enhanced = False
+            else:
+                flush_basic_buffer()
+                extended_messages.append(msg)
+                continue
+
+        try:
+            basic_msg = PromptMessage.model_validate(msg_data)
+        except Exception:
+            continue
+        basic_buffer.append(basic_msg)
 
-    # Convert to multipart messages
-    return PromptMessageExtended.to_extended(result.messages)
+    flush_basic_buffer()
 
+    return extended_messages
 
-def save_messages_to_json_file(messages: List[PromptMessageExtended], file_path: str) -> None:
+
+def save_json(messages: List[PromptMessageExtended], file_path: str) -> None:
     """
-    Save PromptMessageExtended objects to a JSON file.
+    Save PromptMessageExtended objects to a JSON file using enhanced format.
+
+    Uses the enhanced format that preserves tool_calls, tool_results, channels,
+    and stop_reason data.
 
     Args:
         messages: List of PromptMessageExtended objects
         file_path: Path to save the JSON file
     """
-    json_str = multipart_messages_to_json(messages)
+    json_str = to_json(messages)
 
     with open(file_path, "w", encoding="utf-8") as f:
         f.write(json_str)
 
 
-def load_messages_from_json_file(file_path: str) -> List[PromptMessageExtended]:
+def load_json(file_path: str) -> List[PromptMessageExtended]:
     """
     Load PromptMessageExtended objects from a JSON file.
 
+    Handles both enhanced format and legacy GetPromptResult format.
+
     Args:
         file_path: Path to the JSON file
 
@@ -130,14 +207,14 @@ def load_messages_from_json_file(file_path: str) -> List[PromptMessageExtended]:
     with open(file_path, "r", encoding="utf-8") as f:
         json_str = f.read()
 
-    return json_to_extended_messages(json_str)
+    return from_json(json_str)
 
 
-def save_messages_to_file(messages: List[PromptMessageExtended], file_path: str) -> None:
+def save_messages(messages: List[PromptMessageExtended], file_path: str) -> None:
     """
     Save PromptMessageExtended objects to a file, with format determined by file extension.
 
-    Uses GetPromptResult JSON format for .json files (fully MCP compatible) and
+    Uses enhanced JSON format for .json files (preserves all fields) and
     delimited text format for other extensions.
 
     Args:
@@ -147,19 +224,16 @@ def save_messages_to_file(messages: List[PromptMessageExtended], file_path: str)
     path_str = str(file_path).lower()
 
     if path_str.endswith(".json"):
-        # Use GetPromptResult JSON format for .json files (fully MCP compatible)
-        save_messages_to_json_file(messages, file_path)
+        save_json(messages, file_path)
     else:
-        # Use delimited text format for other extensions
-        save_messages_to_delimited_file(messages, file_path)
+        save_delimited(messages, file_path)
 
 
-def load_messages_from_file(file_path: str) -> List[PromptMessageExtended]:
+def load_messages(file_path: str) -> List[PromptMessageExtended]:
     """
     Load PromptMessageExtended objects from a file, with format determined by file extension.
 
-    Uses GetPromptResult JSON format for .json files (fully MCP compatible) and
-    delimited text format for other extensions.
+    Uses JSON format for .json files and delimited text format for other extensions.
 
     Args:
         file_path: Path to the file
@@ -170,11 +244,9 @@ def load_messages_from_file(file_path: str) -> List[PromptMessageExtended]:
     path_str = str(file_path).lower()
 
     if path_str.endswith(".json"):
-        # Use GetPromptResult JSON format for .json files (fully MCP compatible)
-        return load_messages_from_json_file(file_path)
+        return load_json(file_path)
     else:
-        # Use delimited text format for other extensions
-        return load_messages_from_delimited_file(file_path)
+        return load_delimited(file_path)
 
 
 # -------------------------------------------------------------------------
@@ -238,7 +310,7 @@ def multipart_messages_to_delimited_format(
                     delimited_content.append(resource_delimiter)
 
                     # Convert to dictionary using proper JSON mode
-                    content_dict = content.model_dump(by_alias=True, mode="json", exclude_none=True)
+                    content_dict = serialize_to_dict(content)
 
                     # Add to delimited content as JSON
                     delimited_content.append(json.dumps(content_dict, indent=2))
@@ -253,7 +325,7 @@ def multipart_messages_to_delimited_format(
                     delimited_content.append(resource_delimiter)
 
                     # Convert to dictionary using proper JSON mode
-                    content_dict = content.model_dump(by_alias=True, mode="json", exclude_none=True)
+                    content_dict = serialize_to_dict(content)
 
                     # Add to delimited content as JSON
                     delimited_content.append(json.dumps(content_dict, indent=2))
@@ -281,6 +353,17 @@ def delimited_format_to_extended_messages(
     Returns:
         List of PromptMessageExtended objects
     """
+    if user_delimiter not in content and assistant_delimiter not in content:
+        stripped = content.strip()
+        if not stripped:
+            return []
+        return [
+            PromptMessageExtended(
+                role="user",
+                content=[TextContent(type="text", text=stripped)],
+            )
+        ]
+
     lines = content.split("\n")
     messages = []
 
@@ -365,11 +448,13 @@ def delimited_format_to_extended_messages(
                         resource_uri = f"resource://fast-agent/{resource_uri}"
 
                     # Create a simple resource with just the URI
+                    # For legacy format, we don't have the actual content, just the reference
                     resource = EmbeddedResource(
                         type="resource",
                         resource=TextResourceContents(
                             uri=resource_uri,
                             mimeType="text/plain",
+                            text="",  # Legacy format doesn't include content
                         ),
                     )
                     resource_contents.append(resource)
@@ -436,7 +521,7 @@ def delimited_format_to_extended_messages(
     return messages
 
 
-def save_messages_to_delimited_file(
+def save_delimited(
     messages: List[PromptMessageExtended],
     file_path: str,
     user_delimiter: str = USER_DELIMITER,
@@ -467,7 +552,7 @@ def save_messages_to_delimited_file(
         f.write("\n".join(delimited_content))
 
 
-def load_messages_from_delimited_file(
+def load_delimited(
     file_path: str,
     user_delimiter: str = USER_DELIMITER,
     assistant_delimiter: str = ASSISTANT_DELIMITER,

fast_agent/mcp/prompts/prompt_load.py

@@ -12,8 +12,6 @@ from fast_agent.core.logging.logger import get_logger
 from fast_agent.mcp import mime_utils, resource_utils
 from fast_agent.mcp.prompts.prompt_template import (
     PromptContent,
-    PromptTemplate,
-    PromptTemplateLoader,
 )
 from fast_agent.types import PromptMessageExtended
 
@@ -100,58 +98,62 @@ def create_resource_message(
         return message_class(content=embedded_resource)
 
 
-def load_prompt(file: Path) -> List[PromptMessage]:
+def load_prompt(file: Path) -> List[PromptMessageExtended]:
     """
-    Load a prompt from a file and return as PromptMessage objects.
+    Load a prompt from a file and return as PromptMessageExtended objects.
 
     The loader uses file extension to determine the format:
-    - .json files are loaded as MCP SDK compatible GetPromptResult JSON format
-    - All other files are loaded using the template-based delimited format
+    - .json files are loaded using enhanced format that preserves tool_calls, channels, etc.
+    - All other files are loaded using the template-based delimited format with resource loading
 
     Args:
         file: Path to the prompt file
 
     Returns:
-        List of PromptMessage objects
+        List of PromptMessageExtended objects with full conversation state
     """
-    file_str = str(file).lower()
+    path_str = str(file).lower()
 
-    if file_str.endswith(".json"):
-        # Handle JSON format as GetPromptResult
-        import json
+    if path_str.endswith(".json"):
+        # JSON files use the serialization module directly
+        from fast_agent.mcp.prompt_serialization import load_messages
+        return load_messages(str(file))
+    else:
+        # Non-JSON files need template processing for resource loading
+        from fast_agent.mcp.prompts.prompt_template import PromptTemplateLoader
 
-        from mcp.types import GetPromptResult
+        loader = PromptTemplateLoader()
+        template = loader.load_from_file(file)
 
-        # Load JSON directly into GetPromptResult
-        with open(file, "r", encoding="utf-8") as f:
-            json_data = json.load(f)
+        # Render the template without arguments to get the messages
+        messages = create_messages_with_resources(
+            template.content_sections,
+            [file]  # Pass the file path for resource resolution
+        )
+
+        # Convert to PromptMessageExtended
+        return PromptMessageExtended.to_extended(messages)
 
-        # Parse as GetPromptResult object
-        result = GetPromptResult.model_validate(json_data)
 
-        # Return the messages directly
-        return result.messages
-    else:
-        # Template-based format (delimited text)
-        template: PromptTemplate = PromptTemplateLoader().load_from_file(file)
-        return create_messages_with_resources(template.content_sections, [file])
 
 
-def load_prompt_multipart(file: Path) -> List[PromptMessageExtended]:
+def load_prompt_as_get_prompt_result(file: Path):
     """
-    Load a prompt from a file and return as PromptMessageExtended objects.
+    Load a prompt from a file and convert to GetPromptResult format for MCP compatibility.
 
-    The loader uses file extension to determine the format:
-    - .json files are loaded as MCP SDK compatible GetPromptResult JSON format
-    - All other files are loaded using the template-based delimited format
+    This loses extended fields (tool_calls, channels, etc.) but provides
+    compatibility with MCP prompt servers.
 
     Args:
         file: Path to the prompt file
 
     Returns:
-        List of PromptMessageExtended objects
+        GetPromptResult object for MCP compatibility
     """
-    # First load as regular PromptMessage objects
+    from fast_agent.mcp.prompt_serialization import to_get_prompt_result
+
+    # Load with full data
     messages = load_prompt(file)
-    # Then convert to multipart messages
-    return PromptMessageExtended.to_extended(messages)
+
+    # Convert to GetPromptResult (loses extended fields)
+    return to_get_prompt_result(messages)

fast_agent/mcp/prompts/prompt_server.py

@@ -11,7 +11,7 @@ import base64
 import logging
 import sys
 from pathlib import Path
-from typing import Any, Awaitable, Callable, Dict, List, Optional
+from typing import Any, Awaitable, Callable, Dict, List, Optional, Union
 
 from mcp.server.fastmcp import FastMCP
 from mcp.server.fastmcp.prompts.base import (
@@ -38,6 +38,7 @@ from fast_agent.mcp.prompts.prompt_template import (
     PromptMetadata,
     PromptTemplateLoader,
 )
+from fast_agent.types import PromptMessageExtended
 
 # Configure logging
 logging.basicConfig(level=logging.ERROR)
@@ -47,13 +48,13 @@ logger = logging.getLogger("prompt_server")
 mcp = FastMCP("Prompt Server")
 
 
-def convert_to_fastmcp_messages(prompt_messages: List[PromptMessage]) -> List[Message]:
+def convert_to_fastmcp_messages(prompt_messages: List[Union[PromptMessage, PromptMessageExtended]]) -> List[Message]:
     """
-    Convert PromptMessage objects from prompt_load to FastMCP Message objects.
-    This adapter prevents double-wrapping of messages.
+    Convert PromptMessage or PromptMessageExtended objects to FastMCP Message objects.
+    This adapter prevents double-wrapping of messages and handles both types.
 
     Args:
-        prompt_messages: List of PromptMessage objects from prompt_load
+        prompt_messages: List of PromptMessage or PromptMessageExtended objects
 
     Returns:
         List of FastMCP Message objects
@@ -61,13 +62,27 @@ def convert_to_fastmcp_messages(prompt_messages: List[PromptMessage]) -> List[Me
     result = []
 
     for msg in prompt_messages:
-        if msg.role == "user":
-            result.append(UserMessage(content=msg.content))
-        elif msg.role == "assistant":
-            result.append(AssistantMessage(content=msg.content))
+        # Handle both PromptMessage and PromptMessageExtended
+        if hasattr(msg, 'from_multipart'):
+            # PromptMessageExtended - convert to regular PromptMessage format
+            flat_messages = msg.from_multipart()
+            for flat_msg in flat_messages:
+                if flat_msg.role == "user":
+                    result.append(UserMessage(content=flat_msg.content))
+                elif flat_msg.role == "assistant":
+                    result.append(AssistantMessage(content=flat_msg.content))
+                else:
+                    logger.warning(f"Unknown message role: {flat_msg.role}, defaulting to user")
+                    result.append(UserMessage(content=flat_msg.content))
         else:
-            logger.warning(f"Unknown message role: {msg.role}, defaulting to user")
-            result.append(UserMessage(content=msg.content))
+            # Regular PromptMessage - use directly
+            if msg.role == "user":
+                result.append(UserMessage(content=msg.content))
+            elif msg.role == "assistant":
+                result.append(AssistantMessage(content=msg.content))
+            else:
+                logger.warning(f"Unknown message role: {msg.role}, defaulting to user")
+                result.append(UserMessage(content=msg.content))
 
     return result
 

fast_agent/resources/setup/.gitignore

@@ -22,3 +22,9 @@ fastagent.jsonl
 # Editors (optional)
 .idea/
 .vscode/
+
+# Packaging metadata
+*.dist-info/
+*.egg-info/
+dist/
+build/

fast_agent/resources/setup/agent.py

@@ -6,8 +6,15 @@ from fast_agent import FastAgent
 fast = FastAgent("fast-agent example")
 
 
+default_instruction = """You are a helpful AI Agent.
+
+{{serverInstructions}}
+
+The current date is {{currentDate}}."""
+
+
 # Define the agent
-@fast.agent(instruction="You are a helpful AI Agent")
+@fast.agent(instruction=default_instruction)
 async def main():
     # use the --model command line switch or agent arguments to change model
     async with fast.run() as agent:

fast_agent/resources/setup/fastagent.config.yaml

@@ -7,10 +7,10 @@
 # Accepts aliases for Anthropic Models: haiku, haiku3, sonnet, sonnet35, opus, opus3
 # and OpenAI Models: gpt-4.1, gpt-4.1-mini, o1, o1-mini, o3-mini
 #
-# If not specified, defaults to "haiku".
+# If not specified, defaults to "gpt-5-mini.low".
 # Can be overriden with a command line switch --model=<model>, or within the Agent constructor.
 
-default_model: haiku
+default_model: gpt-5-mini.low
 # mcp-ui support: disabled, enabled or auto. "auto" opens the web browser on the asset automatically
 # mcp_ui_output_dir: ".fast-agent/ui"  # Where to write MCP-UI HTML files (relative to CWD if not absolute)
 # mcp_ui_mode: enabled

fast_agent/resources/setup/pyproject.toml.tmpl

@@ -15,3 +15,9 @@ package = true
 [project.scripts]
 fast-agent-app = "agent:main"
 
+[build-system]
+requires = ["setuptools>=64", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+py-modules = ["agent"]

fast_agent/types/__init__.py

@@ -18,7 +18,9 @@ from fast_agent.mcp.helpers.content_helpers import (
 
 # Public message model used across providers and MCP integration
 from fast_agent.mcp.prompt_message_extended import PromptMessageExtended
-from fast_agent.types.llm_stop_reason import LlmStopReason
+
+# Stop reason enum - imported directly to avoid circular dependency
+from .llm_stop_reason import LlmStopReason
 
 __all__ = [
     # Enums / types