open-swarm 0.1.1743070217__py3-none-any.whl → 0.1.1743362777__py3-none-any.whl

swarm/blueprints/family_ties/urls.py

@@ -0,0 +1,10 @@
+from django.urls import path, include
+from rest_framework.routers import DefaultRouter
+from .views import AgentInstructionViewSet
+
+router = DefaultRouter()
+router.register(r'instructions', AgentInstructionViewSet, basename='instructions')
+
+urlpatterns = [
+    path('', include(router.urls)),
+]

swarm/blueprints/family_ties/views.py

@@ -0,0 +1,26 @@
+from rest_framework.viewsets import ModelViewSet
+from rest_framework.permissions import AllowAny
+import os
+from swarm.auth import EnvOrTokenAuthentication
+from blueprints.chc.models import AgentInstruction
+from blueprints.chc.serializers import AgentInstructionSerializer
+
+class AgentInstructionViewSet(ModelViewSet):
+    authentication_classes = [EnvOrTokenAuthentication]
+    permission_classes = [AllowAny]
+    queryset = AgentInstruction.objects.all()
+    serializer_class = AgentInstructionSerializer
+
+    def get_permissions(self):
+        if os.getenv("ENABLE_API_AUTH", "false").lower() in ("true", "1", "t"):
+            from rest_framework.permissions import IsAuthenticated
+            return [IsAuthenticated()]
+        return [AllowAny()]
+
+    def perform_authentication(self, request):
+        super().perform_authentication(request)
+        if not request.user or not request.user.is_authenticated:
+            from rest_framework.exceptions import AuthenticationFailed
+            raise AuthenticationFailed("Invalid token.")
+
+__all__ = ["AgentInstructionViewSet"]

swarm/blueprints/gaggle/blueprint_gaggle.py

@@ -0,0 +1,184 @@
+import logging
+import os # Added os import
+import sys
+from typing import List, Dict, Any, Optional, ClassVar
+
+# Ensure src is in path for BlueprintBase import (if needed, adjust path)
+project_root = os.path.abspath(os.path.join(os.path.dirname(__file__), '..', '..'))
+src_path = os.path.join(project_root, 'src')
+if src_path not in sys.path: sys.path.insert(0, src_path)
+
+try:
+    from agents import Agent, Tool, function_tool, Runner
+    from agents.mcp import MCPServer
+    from agents.models.interface import Model
+    from agents.models.openai_chatcompletions import OpenAIChatCompletionsModel
+    from openai import AsyncOpenAI
+    # Corrected Import: Relative path within the package
+    from swarm.extensions.blueprint.blueprint_base import BlueprintBase
+except ImportError as e:
+    print(f"ERROR: Import failed in blueprint_gaggle: {e}. Check 'openai-agents' install and project structure.")
+    print(f"sys.path: {sys.path}")
+    sys.exit(1)
+
+logger = logging.getLogger(__name__)
+
+# --- Tools ---
+@function_tool
+def create_story_outline(topic: str) -> str:
+    """Generates a basic story outline based on a topic."""
+    logger.info(f"Tool: Generating outline for: {topic}") # Keep INFO for tool exec start
+    # In a real scenario, this might involve more logic or an LLM call.
+    # Adding slight variation for clarity
+    outline = f"Story Outline for '{topic}':\n1. Beginning: Introduce characters and setting.\n2. Middle: Develop conflict and rising action.\n3. Climax: The peak of the conflict.\n4. End: Resolution and aftermath."
+    logger.debug(f"Generated outline: {outline}")
+    return outline
+
+@function_tool
+def write_story_part(part_name: str, outline: str, previous_parts: str) -> str:
+    """Writes a specific part of the story using the outline and previous context."""
+    logger.info(f"Tool: Writing story part: {part_name}") # Keep INFO for tool exec start
+    # Simple placeholder implementation
+    content = f"## {part_name}\n\nThis is the draft content for the '{part_name}' section. It follows:\n'{previous_parts[:100]}...' \nIt should align with the outline:\n'{outline}'"
+    logger.debug(f"Generated content for {part_name}: {content[:100]}...")
+    return content
+
+@function_tool
+def edit_story(full_story: str, edit_instructions: str) -> str:
+    """Edits the complete story based on instructions."""
+    logger.info(f"Tool: Editing story with instructions: {edit_instructions}") # Keep INFO for tool exec start
+    # Simple placeholder for editing
+    edited_content = f"*** Edited Story Draft ***\n(Based on instructions: '{edit_instructions}')\n\n{full_story}\n\n[Editor's Notes: Minor tweaks applied for flow.]"
+    logger.debug("Editing complete.")
+    return edited_content
+
+# --- Blueprint Definition ---
+class GaggleBlueprint(BlueprintBase):
+    """A multi-agent blueprint using a Coordinator, Planner, Writer, and Editor for collaborative story writing."""
+    metadata: ClassVar[Dict[str, Any]] = {
+        "name": "GaggleBlueprint",
+        "title": "Gaggle Story Writing Team",
+        "description": "A multi-agent blueprint for collaborative story writing using Planner, Writer, and Editor roles coordinated by a central agent.",
+        "version": "1.2.0", # Updated version
+        "author": "Open Swarm Team (Refactored)",
+        "tags": ["writing", "collaboration", "multi-agent", "storytelling"],
+        "required_mcp_servers": [],
+        "env_vars": [],
+    }
+
+    # Caches
+    _openai_client_cache: Dict[str, AsyncOpenAI] = {}
+    _model_instance_cache: Dict[str, Model] = {}
+
+    # --- Model Instantiation Helper --- (Standard helper)
+    def _get_model_instance(self, profile_name: str) -> Model:
+        """Retrieves or creates an LLM Model instance."""
+        # ... (Implementation is the same as in previous refactors, e.g., Dilbot's) ...
+        if profile_name in self._model_instance_cache:
+            logger.debug(f"Using cached Model instance for profile '{profile_name}'.")
+            return self._model_instance_cache[profile_name]
+        logger.debug(f"Creating new Model instance for profile '{profile_name}'.")
+        profile_data = self.get_llm_profile(profile_name)
+        if not profile_data:
+             logger.critical(f"LLM profile '{profile_name}' (or 'default') not found.")
+             raise ValueError(f"Missing LLM profile configuration for '{profile_name}' or 'default'.")
+        provider = profile_data.get("provider", "openai").lower()
+        model_name = profile_data.get("model")
+        if not model_name:
+             logger.critical(f"LLM profile '{profile_name}' missing 'model' key.")
+             raise ValueError(f"Missing 'model' key in LLM profile '{profile_name}'.")
+        if provider != "openai":
+            logger.error(f"Unsupported LLM provider '{provider}'.")
+            raise ValueError(f"Unsupported LLM provider: {provider}")
+        client_cache_key = f"{provider}_{profile_data.get('base_url')}"
+        if client_cache_key not in self._openai_client_cache:
+             client_kwargs = { "api_key": profile_data.get("api_key"), "base_url": profile_data.get("base_url") }
+             filtered_kwargs = {k: v for k, v in client_kwargs.items() if v is not None}
+             log_kwargs = {k:v for k,v in filtered_kwargs.items() if k != 'api_key'}
+             logger.debug(f"Creating new AsyncOpenAI client for '{profile_name}': {log_kwargs}")
+             try: self._openai_client_cache[client_cache_key] = AsyncOpenAI(**filtered_kwargs)
+             except Exception as e: raise ValueError(f"Failed to init OpenAI client: {e}") from e
+        client = self._openai_client_cache[client_cache_key]
+        logger.debug(f"Instantiating OpenAIChatCompletionsModel(model='{model_name}') for '{profile_name}'.")
+        try:
+            model_instance = OpenAIChatCompletionsModel(model=model_name, openai_client=client)
+            self._model_instance_cache[profile_name] = model_instance
+            return model_instance
+        except Exception as e: raise ValueError(f"Failed to init LLM provider: {e}") from e
+
+
+    def create_starting_agent(self, mcp_servers: List[MCPServer]) -> Agent:
+        """Creates the story writing team and returns the Coordinator."""
+        logger.debug("Creating Gaggle Story Writing Team...")
+        self._model_instance_cache = {}
+        self._openai_client_cache = {}
+
+        default_profile_name = self.config.get("llm_profile", "default")
+        logger.debug(f"Using LLM profile '{default_profile_name}' for Gaggle agents.")
+        model_instance = self._get_model_instance(default_profile_name)
+
+        # --- Define Agent Instructions ---
+        planner_instructions = "You are the Planner. Your goal is to take a user's story topic and create a coherent outline using the 'create_story_outline' tool. Respond ONLY with the generated outline string."
+        writer_instructions = "You are a Writer. You receive a story part name (e.g., 'Introduction', 'Climax'), the full outline, and any previously written parts. Write the content for ONLY your assigned part using the 'write_story_part' tool, ensuring it flows logically from previous parts and fits the outline. Respond ONLY with the text generated for your part."
+        editor_instructions = "You are the Editor. You receive the complete draft of the story and editing instructions (e.g., 'make it funnier', 'check for consistency'). Use the 'edit_story' tool to revise the text. Respond ONLY with the final, edited story string."
+        coordinator_instructions = (
+            "You are the Coordinator for a team of writing agents (Planner, Writer, Editor).\n"
+            "1. Receive the user's story topic.\n"
+            "2. Delegate to the Planner tool to get a story outline.\n"
+            "3. Identify the story parts from the outline (e.g., Beginning, Middle, Climax, End).\n"
+            "4. Sequentially delegate writing each part to the Writer tool. Provide the part name, the full outline, and all previously written parts as context for the Writer.\n"
+            "5. Accumulate the written parts into a full draft.\n"
+            "6. Delegate the complete draft to the Editor tool with simple instructions like 'Ensure coherence and flow'.\n"
+            "7. Return the final, edited story as the result."
+        )
+
+        # Instantiate agents, passing their specific function tools
+        planner_agent = Agent(
+            name="Planner",
+            instructions=planner_instructions,
+            model=model_instance,
+            tools=[create_story_outline],
+            mcp_servers=mcp_servers
+         )
+        writer_agent = Agent(
+            name="Writer",
+            instructions=writer_instructions,
+            model=model_instance,
+            tools=[write_story_part],
+            mcp_servers=mcp_servers
+        )
+        editor_agent = Agent(
+            name="Editor",
+            instructions=editor_instructions,
+            model=model_instance,
+            tools=[edit_story],
+            mcp_servers=mcp_servers
+        )
+
+        # Instantiate Coordinator, giving it the other agents as tools
+        coordinator_agent = Agent(
+            name="Coordinator",
+            instructions=coordinator_instructions,
+            model=model_instance, # Coordinator also needs a model
+            tools=[
+                planner_agent.as_tool(
+                    tool_name="Planner",
+                    tool_description="Delegate creating a story outline based on a topic."
+                ),
+                writer_agent.as_tool(
+                    tool_name="Writer",
+                    tool_description="Delegate writing a specific part of the story. Requires part_name, outline, and previous_parts."
+                ),
+                editor_agent.as_tool(
+                    tool_name="Editor",
+                    tool_description="Delegate editing the full story draft. Requires full_story and edit_instructions."
+                ),
+            ],
+            mcp_servers=mcp_servers
+        )
+
+        logger.debug("Gaggle Story Writing Team created. Coordinator is the starting agent.")
+        return coordinator_agent
+
+if __name__ == "__main__":
+    GaggleBlueprint.main()

swarm/blueprints/gotchaman/blueprint_gotchaman.py

@@ -0,0 +1,232 @@
+"""
+Gotchaman: CLI Automation Blueprint
+
+This blueprint provides CLI automation capabilities using a team of agents:
+- Ken (Coordinator)
+- Joe (Runner - executes commands/file ops)
+- Jun (Logger - hypothetical monitoring via MCP)
+- Jinpei (Advisor - hypothetical suggestion via MCP)
+- Ryu (Reviewer - hypothetical insights via MCP)
+
+Uses BlueprintBase, @function_tool for local commands, and agent-as-tool delegation.
+"""
+
+import os
+import sys
+import logging
+import subprocess
+import shlex # For safe command splitting
+from pathlib import Path # Use pathlib
+from typing import Dict, Any, List, ClassVar, Optional
+
+# Ensure src is in path for BlueprintBase import
+project_root = os.path.abspath(os.path.join(os.path.dirname(__file__), '..', '..'))
+src_path = os.path.join(project_root, 'src')
+if src_path not in sys.path: sys.path.insert(0, src_path)
+
+try:
+    from agents import Agent, Tool, function_tool, Runner
+    from agents.mcp import MCPServer
+    from agents.models.interface import Model
+    from agents.models.openai_chatcompletions import OpenAIChatCompletionsModel
+    from openai import AsyncOpenAI
+    from swarm.extensions.blueprint.blueprint_base import BlueprintBase
+except ImportError as e:
+    print(f"ERROR: Import failed in GotchamanBlueprint: {e}. Check dependencies.")
+    print(f"sys.path: {sys.path}")
+    sys.exit(1)
+
+logger = logging.getLogger(__name__)
+
+# --- Function Tools ---
+@function_tool
+def execute_command(command: str) -> str:
+    """Executes a shell command and returns its stdout and stderr."""
+    if not command: return "Error: No command provided."
+    logger.info(f"Tool: Executing command: {command}")
+    try:
+        # Use shell=True cautiously, consider splitting if possible for safer execution
+        result = subprocess.run(
+            command,
+            shell=True, # Be cautious with shell=True
+            check=False, # Capture output even on error
+            capture_output=True,
+            text=True,
+            timeout=120
+        )
+        output = f"Exit Code: {result.returncode}\nSTDOUT:\n{result.stdout.strip()}\nSTDERR:\n{result.stderr.strip()}"
+        if result.returncode == 0:
+            logger.debug(f"Command successful:\n{output}")
+            return f"OK: Command executed.\n{output}"
+        else:
+            logger.error(f"Command failed:\n{output}")
+            return f"Error: Command failed.\n{output}"
+    except FileNotFoundError:
+         # This error is less likely with shell=True unless the shell itself is missing
+         logger.error(f"Error executing command '{command}': Shell or command not found.")
+         return f"Error: Shell or command '{command.split()[0]}' not found."
+    except subprocess.TimeoutExpired:
+        logger.error(f"Command '{command}' timed out.")
+        return f"Error: Command '{command}' timed out."
+    except Exception as e:
+        logger.error(f"Unexpected error executing command '{command}': {e}", exc_info=logger.level <= logging.DEBUG)
+        return f"Error: Unexpected error during command execution: {e}"
+
+@function_tool
+def read_file(path: str) -> str:
+    """Reads the content of a file at the specified path."""
+    if not path: return "Error: No file path provided."
+    logger.info(f"Tool: Reading file at: {path}")
+    try:
+        file_path = Path(path).resolve()
+        # Optional: Add security check to ensure path is within allowed bounds if needed
+        # cwd = Path.cwd()
+        # if not str(file_path).startswith(str(cwd)):
+        #     logger.warning(f"Attempt to read file outside current working directory: {path}")
+        #     return f"Error: Access denied to path: {path}"
+        if not file_path.is_file():
+             logger.error(f"File not found at: {file_path}")
+             return f"Error: File not found at path: {path}"
+        content = file_path.read_text(encoding="utf-8")
+        logger.debug(f"Read {len(content)} characters from {file_path}.")
+        return f"OK: Content of {path}:\n{content}"
+    except Exception as e:
+        logger.error(f"Error reading file at {path}: {e}", exc_info=logger.level <= logging.DEBUG)
+        return f"Error reading file '{path}': {e}"
+
+@function_tool
+def write_file(path: str, content: str) -> str:
+    """Writes content to a file at the specified path, overwriting if it exists."""
+    if not path: return "Error: No file path provided."
+    logger.info(f"Tool: Writing {len(content)} characters to file at: {path}")
+    try:
+        file_path = Path(path).resolve()
+        # Optional: Add security check
+        # cwd = Path.cwd()
+        # if not str(file_path).startswith(str(cwd)):
+        #     logger.warning(f"Attempt to write file outside current working directory: {path}")
+        #     return f"Error: Access denied to path: {path}"
+
+        file_path.parent.mkdir(parents=True, exist_ok=True) # Ensure directory exists
+        file_path.write_text(content, encoding="utf-8")
+        logger.debug(f"Successfully wrote to {file_path}.")
+        return f"OK: Successfully wrote to {path}."
+    except Exception as e:
+        logger.error(f"Error writing file at {path}: {e}", exc_info=logger.level <= logging.DEBUG)
+        return f"Error writing file '{path}': {e}"
+
+# --- Define the Blueprint ---
+class GotchamanBlueprint(BlueprintBase):
+    """Gotchaman: CLI Automation Blueprint using BlueprintBase."""
+
+    metadata: ClassVar[Dict[str, Any]] = {
+        "name": "GotchamanBlueprint",
+        "title": "Gotchaman: CLI Automation",
+        "description": (
+            "A blueprint for automating CLI tasks using a team of agents (Ken, Joe, Jun, Jinpei, Ryu) "
+            "with specific roles and MCP/tool access."
+        ),
+        "version": "1.1.0", # Refactored version
+        "author": "Open Swarm Team (Refactored)",
+        "tags": ["cli", "automation", "multi-agent", "mcp", "slack", "monday"],
+        # List only servers directly used by refactored agents
+        "required_mcp_servers": ["slack", "mondayDotCom", "basic-memory", "mcp-npx-fetch"],
+        "env_vars": ["SLACK_API_KEY", "MONDAY_API_KEY"]
+    }
+
+     # Caches
+    _openai_client_cache: Dict[str, AsyncOpenAI] = {}
+    _model_instance_cache: Dict[str, Model] = {}
+
+    # --- Model Instantiation Helper --- (Standard helper)
+    def _get_model_instance(self, profile_name: str) -> Model:
+        """Retrieves or creates an LLM Model instance."""
+        # ... (Implementation is the same as previous refactors) ...
+        if profile_name in self._model_instance_cache:
+            logger.debug(f"Using cached Model instance for profile '{profile_name}'.")
+            return self._model_instance_cache[profile_name]
+        logger.debug(f"Creating new Model instance for profile '{profile_name}'.")
+        profile_data = self.get_llm_profile(profile_name)
+        if not profile_data: raise ValueError(f"Missing LLM profile '{profile_name}'.")
+        provider = profile_data.get("provider", "openai").lower()
+        model_name = profile_data.get("model")
+        if not model_name: raise ValueError(f"Missing 'model' in profile '{profile_name}'.")
+        if provider != "openai": raise ValueError(f"Unsupported provider: {provider}")
+        client_cache_key = f"{provider}_{profile_data.get('base_url')}"
+        if client_cache_key not in self._openai_client_cache:
+             client_kwargs = { "api_key": profile_data.get("api_key"), "base_url": profile_data.get("base_url") }
+             filtered_kwargs = {k: v for k, v in client_kwargs.items() if v is not None}
+             log_kwargs = {k:v for k,v in filtered_kwargs.items() if k != 'api_key'}
+             logger.debug(f"Creating new AsyncOpenAI client for '{profile_name}': {log_kwargs}")
+             try: self._openai_client_cache[client_cache_key] = AsyncOpenAI(**filtered_kwargs)
+             except Exception as e: raise ValueError(f"Failed to init client: {e}") from e
+        client = self._openai_client_cache[client_cache_key]
+        logger.debug(f"Instantiating OpenAIChatCompletionsModel(model='{model_name}') for '{profile_name}'.")
+        try:
+            model_instance = OpenAIChatCompletionsModel(model=model_name, openai_client=client)
+            self._model_instance_cache[profile_name] = model_instance
+            return model_instance
+        except Exception as e: raise ValueError(f"Failed to init LLM: {e}") from e
+
+
+    def create_starting_agent(self, mcp_servers: List[MCPServer]) -> Agent:
+        """Creates the Gotchaman agent team and returns Ken (Coordinator)."""
+        logger.debug("Creating Gotchaman agent team...")
+        self._model_instance_cache = {}
+        self._openai_client_cache = {}
+
+        default_profile_name = self.config.get("llm_profile", "default")
+        logger.debug(f"Using LLM profile '{default_profile_name}' for Gotchaman agents.")
+        model_instance = self._get_model_instance(default_profile_name)
+
+        # Helper to filter MCP servers
+        def get_agent_mcps(names: List[str]) -> List[MCPServer]:
+            return [s for s in mcp_servers if s.name in names]
+
+        # --- Agent Instructions ---
+        ken_instructions = "You are Ken, the Coordinator for Gotchaman team. Your team: Joe (Runner), Jun (Logger), Jinpei (Advisor), and Ryu (Reviewer). Analyze the user request and delegate tasks to the appropriate agent using their Agent Tool. Synthesize their responses for the final output."
+        joe_instructions = "You are Joe, the Runner. Execute shell commands, read files, or write files using your function tools (`execute_command`, `read_file`, `write_file`) as requested by Ken. Report the outcome."
+        jun_instructions = "You are Jun, the Logger. Receive information or instructions from Ken. Use the `slack` MCP tool to log messages or feedback to a designated channel (details provided by Ken or pre-configured). Report success/failure of logging back to Ken."
+        jinpei_instructions = "You are Jinpei, the Advisor. Receive context from Ken. Use the `mcp-npx-fetch` MCP tool to fetch relevant documentation or examples based on the context. Provide concise suggestions or relevant snippets back to Ken."
+        ryu_instructions = "You are Ryu, the Reviewer. Receive outputs or code snippets from Ken. Use the `basic-memory` MCP tool to recall previous related outputs or guidelines if necessary. Provide insightful review comments or quality checks back to Ken."
+
+        # Instantiate agents
+        joe_agent = Agent(
+            name="Joe", model=model_instance, instructions=joe_instructions,
+            tools=[execute_command, read_file, write_file], # Joe has the function tools
+            mcp_servers=[] # Joe doesn't directly use MCPs listed
+        )
+        jun_agent = Agent(
+            name="Jun", model=model_instance, instructions=jun_instructions,
+            tools=[], # Jun uses MCP
+            mcp_servers=get_agent_mcps(["slack"])
+        )
+        jinpei_agent = Agent(
+            name="Jinpei", model=model_instance, instructions=jinpei_instructions,
+            tools=[], # Jinpei uses MCP
+            mcp_servers=get_agent_mcps(["mcp-npx-fetch"])
+        )
+        ryu_agent = Agent(
+            name="Ryu", model=model_instance, instructions=ryu_instructions,
+            tools=[], # Ryu uses MCP
+            mcp_servers=get_agent_mcps(["basic-memory"])
+        )
+        # Coordinator - Ken
+        ken_agent = Agent(
+            name="Ken", model=model_instance, instructions=ken_instructions,
+            tools=[ # Ken delegates to others via agent tools
+                joe_agent.as_tool(tool_name="Joe", tool_description="Delegate command execution or file operations to Joe."),
+                jun_agent.as_tool(tool_name="Jun", tool_description="Delegate logging tasks via Slack to Jun."),
+                jinpei_agent.as_tool(tool_name="Jinpei", tool_description="Delegate fetching docs/examples to Jinpei."),
+                ryu_agent.as_tool(tool_name="Ryu", tool_description="Delegate review tasks or recall past info via Ryu."),
+            ],
+             # Ken might use memory directly, or coordinate access via Ryu? Assigning for potential direct use.
+            mcp_servers=get_agent_mcps(["basic-memory"])
+        )
+
+        logger.debug("Gotchaman agents created. Starting with Ken.")
+        return ken_agent
+
+# Standard Python entry point
+if __name__ == "__main__":
+    GotchamanBlueprint.main()

swarm/blueprints/mcp_demo/blueprint_mcp_demo.py

@@ -0,0 +1,133 @@
+import logging
+import os
+import sys
+from typing import Dict, Any, List, ClassVar, Optional
+
+# Ensure src is in path for BlueprintBase import
+project_root = os.path.abspath(os.path.join(os.path.dirname(__file__), '..', '..'))
+src_path = os.path.join(project_root, 'src')
+if src_path not in sys.path: sys.path.insert(0, src_path)
+
+try:
+    from agents import Agent, Tool, function_tool, Runner
+    from agents.mcp import MCPServer
+    from agents.models.interface import Model
+    from agents.models.openai_chatcompletions import OpenAIChatCompletionsModel
+    from openai import AsyncOpenAI
+    from swarm.extensions.blueprint.blueprint_base import BlueprintBase
+except ImportError as e:
+    print(f"ERROR: Import failed in MCPDemoBlueprint: {e}. Check dependencies.")
+    print(f"sys.path: {sys.path}")
+    sys.exit(1)
+
+logger = logging.getLogger(__name__)
+
+# --- Agent Instructions ---
+
+sage_instructions_template = """
+You are Sage, an agent demonstrating capabilities provided by MCP servers.
+You have access to the following external capabilities via implicitly available MCP tools:
+{mcp_tool_descriptions}
+
+Your goal is to understand the user's request and utilize the appropriate MCP tool to fulfill it.
+For example:
+- To write to a file, use the 'filesystem' tool's 'write' function.
+- To read from memory, use the 'memory' tool's 'get' function.
+- To store in memory, use the 'memory' tool's 'set' function.
+Explain what action you are taking via which tool and report the result.
+"""
+
+# --- Define the Blueprint ---
+class MCPDemoBlueprint(BlueprintBase):
+    """Demonstrates using filesystem and memory MCP servers."""
+    metadata: ClassVar[Dict[str, Any]] = {
+        "name": "MCPDemoBlueprint",
+        "title": "MCP Demo (Filesystem & Memory)",
+        "description": "A simple agent (Sage) demonstrating interaction with filesystem and memory MCP servers.",
+        "version": "1.1.0", # Refactored version
+        "author": "Open Swarm Team (Refactored)",
+        "tags": ["mcp", "filesystem", "memory", "demo"],
+        "required_mcp_servers": ["filesystem", "memory"],
+        "env_vars": ["ALLOWED_PATH"], # For filesystem MCP
+    }
+
+    # Caches
+    _openai_client_cache: Dict[str, AsyncOpenAI] = {}
+    _model_instance_cache: Dict[str, Model] = {}
+
+    # --- Model Instantiation Helper --- (Standard helper)
+    def _get_model_instance(self, profile_name: str) -> Model:
+        """Retrieves or creates an LLM Model instance."""
+        # ... (Implementation is the same as in previous refactors) ...
+        if profile_name in self._model_instance_cache:
+            logger.debug(f"Using cached Model instance for profile '{profile_name}'.")
+            return self._model_instance_cache[profile_name]
+        logger.debug(f"Creating new Model instance for profile '{profile_name}'.")
+        profile_data = self.get_llm_profile(profile_name)
+        if not profile_data: raise ValueError(f"Missing LLM profile '{profile_name}'.")
+        provider = profile_data.get("provider", "openai").lower()
+        model_name = profile_data.get("model")
+        if not model_name: raise ValueError(f"Missing 'model' in profile '{profile_name}'.")
+        if provider != "openai": raise ValueError(f"Unsupported provider: {provider}")
+        client_cache_key = f"{provider}_{profile_data.get('base_url')}"
+        if client_cache_key not in self._openai_client_cache:
+             client_kwargs = { "api_key": profile_data.get("api_key"), "base_url": profile_data.get("base_url") }
+             filtered_kwargs = {k: v for k, v in client_kwargs.items() if v is not None}
+             log_kwargs = {k:v for k,v in filtered_kwargs.items() if k != 'api_key'}
+             logger.debug(f"Creating new AsyncOpenAI client for '{profile_name}': {log_kwargs}")
+             try: self._openai_client_cache[client_cache_key] = AsyncOpenAI(**filtered_kwargs)
+             except Exception as e: raise ValueError(f"Failed to init client: {e}") from e
+        client = self._openai_client_cache[client_cache_key]
+        logger.debug(f"Instantiating OpenAIChatCompletionsModel(model='{model_name}') for '{profile_name}'.")
+        try:
+            model_instance = OpenAIChatCompletionsModel(model=model_name, openai_client=client)
+            self._model_instance_cache[profile_name] = model_instance
+            return model_instance
+        except Exception as e: raise ValueError(f"Failed to init LLM: {e}") from e
+
+    # --- Agent Creation ---
+    def create_starting_agent(self, mcp_servers: List[MCPServer]) -> Agent:
+        """Creates the Sage agent, dynamically adding MCP server descriptions to its prompt."""
+        logger.debug("Creating MCP Demo agent (Sage)...")
+        self._model_instance_cache = {}
+        self._openai_client_cache = {}
+
+        default_profile_name = self.config.get("llm_profile", "default")
+        logger.debug(f"Using LLM profile '{default_profile_name}' for Sage.")
+        model_instance = self._get_model_instance(default_profile_name)
+
+        # Filter for required MCPs and get descriptions
+        required_names = self.metadata["required_mcp_servers"]
+        agent_mcps: List[MCPServer] = []
+        mcp_descriptions = []
+        for server in mcp_servers:
+            if server.name in required_names:
+                agent_mcps.append(server)
+                description = self.get_mcp_server_description(server.name)
+                mcp_descriptions.append(f"- {server.name}: {description or 'No description available.'}")
+
+        if len(agent_mcps) != len(required_names):
+            missing = set(required_names) - {s.name for s in agent_mcps}
+            logger.warning(f"Sage agent created, but missing required MCP server(s): {', '.join(missing)}. Functionality will be limited.")
+            # Continue with available servers
+
+        # Format descriptions for the prompt
+        mcp_tool_desc_str = "\n".join(mcp_descriptions) if mcp_descriptions else "No external tools available."
+        sage_instructions = sage_instructions_template.format(mcp_tool_descriptions=mcp_tool_desc_str)
+        logger.debug(f"Sage instructions generated:\n{sage_instructions}")
+
+        # Instantiate Sage
+        sage_agent = Agent(
+            name="Sage",
+            model=model_instance,
+            instructions=sage_instructions,
+            tools=[], # Tools come implicitly from assigned MCP servers
+            mcp_servers=agent_mcps # Pass the list of *started* server objects
+        )
+
+        logger.debug("Sage agent created.")
+        return sage_agent
+
+# Standard Python entry point
+if __name__ == "__main__":
+    MCPDemoBlueprint.main()

swarm/blueprints/messenger/templates/messenger/messenger.html

@@ -0,0 +1,46 @@
+{% load static %}
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    {% include 'rest_mode/components/header.html' %}
+    <link rel="stylesheet" href="{% static 'rest_mode/css/messenger.css' %}">
+    <script>
+        window.STATIC_URLS = {
+            layoutSidebarLeftExpand: "{% static 'contrib/tabler-icons/layout-sidebar-left-expand.svg' %}",
+            layoutSidebarLeftCollapse: "{% static 'contrib/tabler-icons/layout-sidebar-left-collapse.svg' %}"
+        };
+    </script>
+</head>
+<body>
+    {% include 'rest_mode/components/top_bar.html' %}
+    {% include 'rest_mode/components/settings_dialog.html' %}
+    <div class="container" data-theme-color="corporate" data-theme-dark="false" data-theme-layout="messenger-layout">
+        <div class="side-panes chat-history-pane" id="channelPane">
+            <div class="chat-history-header">
+                <button class="input-button chat-history-button" id="toggleSidebar" aria-label="Toggle Sidebar">
+                    <img src="{% static 'contrib/tabler-icons/layout-sidebar-left-collapse.svg' %}" alt="Collapse Sidebar">
+                </button>
+                <button class="input-button upload-button" id="settingsToggleButton" aria-label="Toggle Settings">
+                    <img src="{% static 'contrib/tabler-icons/settings.svg' %}" alt="Settings">
+                </button>
+                <button class="input-button search-button" title="Search" aria-label="Search Channels">
+                    <img src="{% static 'contrib/tabler-icons/search.svg' %}" alt="Search">
+                </button>
+            </div>
+            <h3>Channels</h3>
+            <ul id="channelList" class="chat-history-list">
+                <li data-blueprint-id="welcome">#Welcome to Open-Swarm</li>
+            </ul>
+        </div>
+        <div class="vertical-divider" id="divider-left"></div>
+        <div class="main-pane">
+            {% include 'rest_mode/components/main_chat_pane.html' %}
+        </div>
+        <div id="toastContainer"></div>
+    </div>
+    <div class="settings-overlay"></div>
+    <script type="module" src="{% static 'contrib/markedjs/marked.min.js' %}"></script>
+    <script type="module" src="{% static 'rest_mode/js/settings.js' %}"></script>
+    <script type="module" src="{% static 'rest_mode/js/messengerLogic.js' %}"></script>
+</body>
+</html>