autobyteus 1.1.2__py3-none-any.whl → 1.1.4__py3-none-any.whl

autobyteus/tools/mcp/tool_registrar.py

@@ -0,0 +1,179 @@
+# file: autobyteus/autobyteus/tools/mcp/tool_registrar.py
+import logging
+from typing import Any, Dict, List, Optional, Union
+
+# Consolidated imports from the autobyteus.autobyteus.mcp package public API
+from .config_service import McpConfigService
+from .factory import McpToolFactory
+from .schema_mapper import McpSchemaMapper
+from .server_instance_manager import McpServerInstanceManager
+from .types import BaseMcpConfig
+from .server import BaseManagedMcpServer
+
+from autobyteus.tools.registry import ToolRegistry, ToolDefinition
+from autobyteus.tools.tool_origin import ToolOrigin
+from autobyteus.tools.tool_category import ToolCategory
+from autobyteus.utils.singleton import SingletonMeta
+from mcp import types as mcp_types
+
+
+logger = logging.getLogger(__name__)
+
+class McpToolRegistrar(metaclass=SingletonMeta):
+    """
+    Orchestrates the discovery of remote MCP tools and their registration
+    with the AutoByteUs ToolRegistry.
+    """
+    def __init__(self):
+        """
+        Initializes the McpToolRegistrar singleton.
+        """
+        self._config_service: McpConfigService = McpConfigService()
+        self._tool_registry: ToolRegistry = ToolRegistry()
+        self._instance_manager: McpServerInstanceManager = McpServerInstanceManager()
+        self._registered_tools_by_server: Dict[str, List[ToolDefinition]] = {}
+        logger.info("McpToolRegistrar initialized.")
+
+    async def _fetch_tools_from_server(self, server_config: BaseMcpConfig) -> List[mcp_types.Tool]:
+        """
+        Uses the instance manager to get a temporary, managed session for discovery.
+        """
+        async with self._instance_manager.managed_discovery_session(server_config) as discovery_server:
+            # The context manager guarantees the server is connected and will be closed.
+            remote_tools = await discovery_server.list_remote_tools()
+            return remote_tools
+
+    def _create_tool_definition_from_remote(
+        self,
+        remote_tool: mcp_types.Tool,
+        server_config: BaseMcpConfig,
+        schema_mapper: McpSchemaMapper
+    ) -> ToolDefinition:
+        """
+        Maps a single remote tool from an MCP server to an AutoByteUs ToolDefinition.
+        """
+        actual_arg_schema = schema_mapper.map_to_autobyteus_schema(remote_tool.inputSchema)
+        actual_desc = remote_tool.description
+        
+        registered_name = remote_tool.name
+        if server_config.tool_name_prefix:
+            registered_name = f"{server_config.tool_name_prefix.rstrip('_')}_{remote_tool.name}"
+
+        tool_factory = McpToolFactory(
+            server_id=server_config.server_id,
+            remote_tool_name=remote_tool.name,
+            registered_tool_name=registered_name,
+            tool_description=actual_desc,
+            tool_argument_schema=actual_arg_schema
+        )
+        
+        return ToolDefinition(
+            name=registered_name,
+            description=actual_desc,
+            argument_schema=actual_arg_schema,
+            origin=ToolOrigin.MCP,
+            category=server_config.server_id, # Use server_id as the category
+            metadata={"mcp_server_id": server_config.server_id}, # Store origin in generic metadata
+            custom_factory=tool_factory.create_tool,
+            config_schema=None,
+            tool_class=None
+        )
+
+    async def discover_and_register_tools(self, mcp_config: Optional[Union[BaseMcpConfig, Dict[str, Any]]] = None) -> List[ToolDefinition]:
+        """
+        Discovers tools from MCP servers and registers them.
+        """
+        configs_to_process: List[BaseMcpConfig]
+        
+        if mcp_config:
+            validated_config: BaseMcpConfig
+            if isinstance(mcp_config, dict):
+                try:
+                    validated_config = self._config_service.load_config(mcp_config)
+                except ValueError as e:
+                    logger.error(f"Failed to parse provided MCP config dictionary: {e}")
+                    raise
+            elif isinstance(mcp_config, BaseMcpConfig):
+                validated_config = self._config_service.add_config(mcp_config)
+            else:
+                raise TypeError(f"mcp_config must be a BaseMcpConfig object or a dictionary, not {type(mcp_config)}.")
+            
+            logger.info(f"Starting targeted MCP tool discovery for server: {validated_config.server_id}")
+            self.unregister_tools_from_server(validated_config.server_id)
+            configs_to_process = [validated_config]
+        else:
+            logger.info("Starting full MCP tool discovery. Unregistering all existing MCP tools first.")
+            all_server_ids = list(self._registered_tools_by_server.keys())
+            for server_id in all_server_ids:
+                self.unregister_tools_from_server(server_id)
+            self._registered_tools_by_server.clear()
+            configs_to_process = self._config_service.get_all_configs()
+
+        if not configs_to_process:
+            logger.info("No MCP server configurations to process. Skipping discovery.")
+            return []
+
+        schema_mapper = McpSchemaMapper()
+        registered_tool_definitions: List[ToolDefinition] = []
+        for server_config in configs_to_process:
+            if not server_config.enabled:
+                logger.info(f"MCP server '{server_config.server_id}' is disabled. Skipping.")
+                continue
+
+            logger.info(f"Discovering tools from MCP server: '{server_config.server_id}'")
+            
+            try:
+                remote_tools = await self._fetch_tools_from_server(server_config)
+                logger.info(f"Discovered {len(remote_tools)} tools from server '{server_config.server_id}'.")
+
+                for remote_tool in remote_tools:
+                    try:
+                        tool_def = self._create_tool_definition_from_remote(remote_tool, server_config, schema_mapper)
+                        self._tool_registry.register_tool(tool_def)
+                        self._registered_tools_by_server.setdefault(server_config.server_id, []).append(tool_def)
+                        registered_tool_definitions.append(tool_def)
+                    except Exception as e_tool:
+                        logger.error(f"Failed to process or register remote tool '{remote_tool.name}': {e_tool}", exc_info=True)
+            
+            except Exception as e_server:
+                logger.error(f"Failed to discover tools from MCP server '{server_config.server_id}': {e_server}", exc_info=True)
+        
+        logger.info(f"MCP tool discovery and registration process completed. Total tools registered: {len(registered_tool_definitions)}.")
+        return registered_tool_definitions
+
+    async def list_remote_tools(self, mcp_config: Union[BaseMcpConfig, Dict[str, Any]]) -> List[ToolDefinition]:
+        validated_config: BaseMcpConfig
+        if isinstance(mcp_config, dict):
+            validated_config = McpConfigService.parse_mcp_config_dict(mcp_config)
+        elif isinstance(mcp_config, BaseMcpConfig):
+            validated_config = mcp_config
+        else:
+            raise TypeError(f"mcp_config must be a BaseMcpConfig object or a dictionary, not {type(mcp_config)}.")
+        
+        logger.info(f"Previewing tools from MCP server: '{validated_config.server_id}'")
+        schema_mapper = McpSchemaMapper()
+        tool_definitions: List[ToolDefinition] = []
+
+        try:
+            remote_tools = await self._fetch_tools_from_server(validated_config)
+            logger.info(f"Discovered {len(remote_tools)} tools from server '{validated_config.server_id}' for preview.")
+            for remote_tool in remote_tools:
+                tool_def = self._create_tool_definition_from_remote(remote_tool, validated_config, schema_mapper)
+                tool_definitions.append(tool_def)
+        except Exception as e_server:
+            logger.error(f"Failed to discover tools for preview from MCP server '{validated_config.server_id}': {e_server}", exc_info=True)
+            raise
+            
+        logger.info(f"MCP tool preview completed. Found {len(tool_definitions)} tools.")
+        return tool_definitions
+    
+    def unregister_tools_from_server(self, server_id: str) -> bool:
+        if not self.is_server_registered(server_id):
+            return False
+        tools_to_unregister = self._registered_tools_by_server.pop(server_id, [])
+        for tool_def in tools_to_unregister:
+            self._tool_registry.unregister_tool(tool_def.name)
+        return True
+        
+    def is_server_registered(self, server_id: str) -> bool:
+        return server_id in self._registered_tools_by_server

autobyteus/tools/mcp/types.py

@@ -1,4 +1,4 @@
-# file: autobyteus/autobyteus/mcp/types.py
+# file: autobyteus/autobyteus/tools/mcp/types.py
 import logging
 from typing import List, Dict, Any, Optional, Type
 from dataclasses import dataclass, field, InitVar
@@ -9,9 +9,17 @@ logger = logging.getLogger(__name__)
 class McpTransportType(str, Enum):
     """Enumeration of supported MCP transport types."""
     STDIO = "stdio"
-    SSE = "sse" 
     STREAMABLE_HTTP = "streamable_http"
 
+@dataclass(frozen=True)
+class McpServerInstanceKey:
+    """
+    A dedicated, hashable key for identifying a unique server instance.
+    An instance is unique for a given agent and a specific server configuration.
+    """
+    agent_id: str
+    server_id: str
+
 @dataclass
 class BaseMcpConfig:
     """
@@ -59,25 +67,6 @@ class StdioMcpServerConfig(BaseMcpConfig):
         if self.cwd is not None and not isinstance(self.cwd, str):
             raise ValueError(f"StdioMcpServerConfig '{self.server_id}' 'cwd' must be a string if provided.") 
 
-@dataclass
-class SseMcpServerConfig(BaseMcpConfig):
-    """Configuration parameters for an MCP server using SSE transport."""
-    url: Optional[str] = None # Changed: Added default None
-    token: Optional[str] = None
-    headers: Dict[str, str] = field(default_factory=dict)
-
-    def __post_init__(self):
-        super().__post_init__()
-        self.transport_type = McpTransportType.SSE
-
-        if self.url is None or not isinstance(self.url, str) or not self.url.strip():
-            raise ValueError(f"SseMcpServerConfig '{self.server_id}' 'url' must be a non-empty string.")
-        
-        if self.token is not None and not isinstance(self.token, str):
-            raise ValueError(f"SseMcpServerConfig '{self.server_id}' 'token' must be a string if provided.") 
-        if not isinstance(self.headers, dict) or not all(isinstance(k, str) and isinstance(v, str) for k, v in self.headers.items()):
-            raise ValueError(f"SseMcpServerConfig '{self.server_id}' 'headers' must be a Dict[str, str].") 
-
 @dataclass
 class StreamableHttpMcpServerConfig(BaseMcpConfig):
     """Configuration parameters for an MCP server using Streamable HTTP transport."""

autobyteus/tools/pdf_downloader.py

@@ -7,6 +7,7 @@ from datetime import datetime
 from typing import TYPE_CHECKING, Optional
 
 from autobyteus.tools import tool
+from autobyteus.tools.tool_category import ToolCategory
 from autobyteus.utils.file_utils import get_default_download_folder
 
 if TYPE_CHECKING:
@@ -14,7 +15,7 @@ if TYPE_CHECKING:
 
 logger = logging.getLogger(__name__)
 
-@tool(name="PDFDownloader")
+@tool(name="PDFDownloader", category=ToolCategory.WEB)
 async def pdf_downloader( # function name can be pdf_downloader
     context: 'AgentContext', 
     url: str, 

autobyteus/tools/registry/tool_definition.py

@@ -6,7 +6,7 @@ from typing import Dict, Any, List as TypingList, Type, TYPE_CHECKING, Optional,
 from autobyteus.llm.providers import LLMProvider
 from autobyteus.tools.tool_config import ToolConfig
 from autobyteus.tools.parameter_schema import ParameterSchema
-from autobyteus.tools.tool_category import ToolCategory
+from autobyteus.tools.tool_origin import ToolOrigin
 from autobyteus.tools.usage.providers import (
     XmlSchemaProvider, 
     JsonSchemaProvider, 
@@ -28,10 +28,12 @@ class ToolDefinition:
                  name: str,
                  description: str,
                  argument_schema: Optional['ParameterSchema'],
-                 category: ToolCategory,
+                 origin: ToolOrigin,
+                 category: str,
                  config_schema: Optional['ParameterSchema'] = None,
                  tool_class: Optional[Type['BaseTool']] = None,
-                 custom_factory: Optional[Callable[['ToolConfig'], 'BaseTool']] = None):
+                 custom_factory: Optional[Callable[['ToolConfig'], 'BaseTool']] = None,
+                 metadata: Optional[Dict[str, Any]] = None):
         """
         Initializes the ToolDefinition.
         """
@@ -54,8 +56,12 @@ class ToolDefinition:
              raise TypeError(f"ToolDefinition '{name}' received an invalid 'argument_schema'. Expected ParameterSchema or None.")
         if config_schema is not None and not isinstance(config_schema, ParameterSchema):
              raise TypeError(f"ToolDefinition '{name}' received an invalid 'config_schema'. Expected ParameterSchema or None.")
-        if not isinstance(category, ToolCategory):
-            raise TypeError(f"ToolDefinition '{name}' requires a ToolCategory for 'category'. Got {type(category)}")
+        if not isinstance(origin, ToolOrigin):
+            raise TypeError(f"ToolDefinition '{name}' requires a ToolOrigin for 'origin'. Got {type(origin)}")
+        
+        # Validation for MCP-specific metadata
+        if origin == ToolOrigin.MCP and not (metadata and metadata.get("mcp_server_id")):
+            raise ValueError(f"ToolDefinition '{name}' with origin MCP must provide a 'mcp_server_id' in its metadata.")
 
         self._name = name
         self._description = description
@@ -63,7 +69,9 @@ class ToolDefinition:
         self._config_schema: Optional['ParameterSchema'] = config_schema
         self._tool_class = tool_class
         self._custom_factory = custom_factory
+        self._origin = origin
         self._category = category
+        self._metadata = metadata or {}
         
         logger.debug(f"ToolDefinition created for tool '{self.name}'.")
 
@@ -81,7 +89,11 @@ class ToolDefinition:
     @property
     def config_schema(self) -> Optional['ParameterSchema']: return self._config_schema
     @property
-    def category(self) -> ToolCategory: return self._category
+    def origin(self) -> ToolOrigin: return self._origin
+    @property
+    def category(self) -> str: return self._category
+    @property
+    def metadata(self) -> Dict[str, Any]: return self._metadata
     
     # --- Schema Generation API ---
     def get_usage_xml(self, provider: Optional[LLMProvider] = None) -> str:
@@ -136,4 +148,5 @@ class ToolDefinition:
 
     def __repr__(self) -> str:
         creator_repr = f"class='{self._tool_class.__name__}'" if self._tool_class else "factory=True"
-        return (f"ToolDefinition(name='{self.name}', category='{self.category.value}', {creator_repr})")
+        metadata_repr = f", metadata={self.metadata}" if self.metadata else ""
+        return (f"ToolDefinition(name='{self.name}', origin='{self.origin.value}', category='{self.category}'{metadata_repr}, {creator_repr})")

autobyteus/tools/registry/tool_registry.py

@@ -1,10 +1,12 @@
 # file: autobyteus/tools/registry/tool_registry.py
 import logging
 from typing import Dict, List, Optional, Type, TYPE_CHECKING
+from collections import defaultdict
 
 from autobyteus.tools.registry.tool_definition import ToolDefinition
 from autobyteus.utils.singleton import SingletonMeta
 from autobyteus.tools.tool_config import ToolConfig
+from autobyteus.tools.tool_origin import ToolOrigin
 
 if TYPE_CHECKING:
     from autobyteus.tools.base_tool import BaseTool
@@ -78,19 +80,8 @@ class ToolRegistry(metaclass=SingletonMeta):
 
     def create_tool(self, name: str, config: Optional[ToolConfig] = None) -> 'BaseTool':
         """
-        Creates a tool instance using its definition, either from a factory or a class.
-
-        Args:
-            name: The name of the tool to create.
-            config: Optional ToolConfig with constructor parameters for class-based tools
-                    or to be passed to a custom factory.
-
-        Returns:
-            The tool instance if the definition exists.
-
-        Raises:
-            ValueError: If the tool definition is not found or is invalid.
-            TypeError: If tool instantiation fails.
+        Creates a tool instance using its definition and injects the definition
+        back into the instance.
         """
         definition = self.get_tool_definition(name)
         if not definition:
@@ -98,24 +89,20 @@ class ToolRegistry(metaclass=SingletonMeta):
             raise ValueError(f"No tool definition found for name '{name}'")
         
         try:
-            # Prefer the custom factory if it exists
+            tool_instance: 'BaseTool'
             if definition.custom_factory:
                 logger.info(f"Creating tool instance for '{name}' using its custom factory.")
-                # Pass the config to the factory. The factory can choose to use it or not.
                 tool_instance = definition.custom_factory(config)
-            
-            # Fall back to instantiating the tool_class
             elif definition.tool_class:
-                # For class-based tools, the convention is to pass the ToolConfig object
-                # itself to the constructor under the 'config' keyword argument.
                 logger.info(f"Creating tool instance for '{name}' using class '{definition.tool_class.__name__}' and passing ToolConfig.")
                 tool_instance = definition.tool_class(config=config)
-            
             else:
-                # This case should be prevented by ToolDefinition's validation
                 raise ValueError(f"ToolDefinition for '{name}' is invalid: missing both tool_class and custom_factory.")
 
-            logger.debug(f"Successfully created tool instance for '{name}'")
+            # Inject the definition into the newly created instance.
+            tool_instance.definition = definition
+            logger.debug(f"Injected ToolDefinition into instance of '{name}'.")
+
             return tool_instance
 
         except Exception as e:
@@ -126,23 +113,83 @@ class ToolRegistry(metaclass=SingletonMeta):
     def list_tools(self) -> List[ToolDefinition]:
         """
         Returns a list of all registered tool definitions.
-
-        Returns:
-            A list of ToolDefinition objects.
         """
         return list(self._definitions.values())
 
     def list_tool_names(self) -> List[str]:
         """
         Returns a list of the names of all registered tools.
-
-        Returns:
-            A list of tool name strings.
         """
         return list(self._definitions.keys())
 
     def get_all_definitions(self) -> Dict[str, ToolDefinition]:
         """Returns the internal dictionary of definitions."""
         return dict(ToolRegistry._definitions)
+        
+    def get_tools_by_mcp_server(self, server_id: str) -> List[ToolDefinition]:
+        """
+        Returns a list of all registered tool definitions that originated
+        from a specific MCP server.
+
+        Args:
+            server_id: The unique ID of the MCP server to query for.
+
+        Returns:
+            A list of matching ToolDefinition objects.
+        """
+        if not server_id:
+            return []
+        
+        return [
+            td for td in self._definitions.values()
+            if td.origin == ToolOrigin.MCP and td.metadata.get("mcp_server_id") == server_id
+        ]
+
+    def get_tools_by_category(self, category: str) -> List[ToolDefinition]:
+        """
+        Returns a list of all registered tool definitions that match a specific category.
+
+        Args:
+            category: The category string to filter by.
+
+        Returns:
+            A list of matching ToolDefinition objects, sorted by name.
+        """
+        if not category:
+            return []
+        
+        matching_tools = [
+            td for td in self._definitions.values() if td.category == category
+        ]
+        return sorted(matching_tools, key=lambda td: td.name)
+
+    def get_tools_grouped_by_category(self, origin: Optional[ToolOrigin] = None) -> Dict[str, List[ToolDefinition]]:
+        """
+        Returns all registered tool definitions, grouped into a dictionary by their category.
+        Can optionally filter by tool origin before grouping.
+
+        Args:
+            origin: If provided, only tools from this origin will be included.
+
+        Returns:
+            A dictionary where keys are category strings and values are lists
+            of ToolDefinition objects belonging to that category. Both the categories
+            and the tools within each category are sorted alphabetically.
+        """
+        grouped_tools = defaultdict(list)
+        
+        tools_to_process = self._definitions.values()
+        if origin:
+            tools_to_process = [td for td in tools_to_process if td.origin == origin]
+
+        for td in tools_to_process:
+            grouped_tools[td.category].append(td)
+        
+        # Sort tools within each category and sort the categories themselves for deterministic output
+        sorted_grouped_tools = {}
+        for category in sorted(grouped_tools.keys()):
+            sorted_grouped_tools[category] = sorted(grouped_tools[category], key=lambda td: td.name)
+            
+        return sorted_grouped_tools
 
 default_tool_registry = ToolRegistry()

autobyteus/tools/timer.py

@@ -3,6 +3,7 @@ from typing import Optional, TYPE_CHECKING, Any
 from autobyteus.tools.base_tool import BaseTool
 from autobyteus.tools.tool_config import ToolConfig 
 from autobyteus.tools.parameter_schema import ParameterSchema, ParameterDefinition, ParameterType 
+from autobyteus.tools.tool_category import ToolCategory
 from autobyteus.events.event_emitter import EventEmitter 
 from autobyteus.events.event_types import EventType
 import logging 
@@ -17,6 +18,7 @@ class Timer(BaseTool, EventEmitter):
     A tool that provides timer functionality with configurable duration and event emission.
     The timer runs independently after being started and emits TIMER_UPDATE events.
     """
+    CATEGORY = ToolCategory.UTILITY
 
     def __init__(self, config: Optional[ToolConfig] = None):
         BaseTool.__init__(self, config=config)

autobyteus/tools/tool_category.py

@@ -2,10 +2,20 @@
 from enum import Enum
 
 class ToolCategory(str, Enum):
-    """Enumeration of tool categories to identify their origin."""
-    LOCAL = "local"
-    MCP = "mcp"
-    # BUILT_IN, USER_DEFINED etc. could be added later.
+    """
+    Provides standardized string constants for common tool categories.
+    While tools can use any string for a category, using these constants
+    is recommended to ensure consistency in UI grouping.
+    """
+    USER_INTERACTION = "User Interaction"
+    FILE_SYSTEM = "File System"
+    WEB = "Web"
+    SYSTEM = "System"
+    UTILITY = "Utility"
+    AGENT_COMMUNICATION = "Agent Communication"
+    PROMPT_MANAGEMENT = "Prompt Management"
+    GENERAL = "General"
+    MCP = "MCP"
 
     def __str__(self) -> str:
         return self.value

autobyteus/tools/tool_meta.py

@@ -5,6 +5,7 @@ from typing import Dict, Any
 
 from autobyteus.tools.registry import default_tool_registry, ToolDefinition
 from autobyteus.tools.parameter_schema import ParameterSchema
+from autobyteus.tools.tool_origin import ToolOrigin
 from autobyteus.tools.tool_category import ToolCategory
 
 logger = logging.getLogger(__name__)
@@ -53,6 +54,9 @@ class ToolMeta(ABCMeta):
                         instantiation_config_schema = None
                 except Exception as e:
                     logger.warning(f"Tool class {name} ({tool_name}) has get_config_schema() but it failed: {e}. Assuming no instantiation config.")
+
+            # Get category from class attribute, defaulting to "General"
+            category_str = getattr(cls, 'CATEGORY', ToolCategory.GENERAL)
             
             # Create the definition without pre-generating usage strings
             definition = ToolDefinition(
@@ -62,7 +66,8 @@ class ToolMeta(ABCMeta):
                 custom_factory=None,
                 argument_schema=argument_schema,
                 config_schema=instantiation_config_schema,
-                category=ToolCategory.LOCAL
+                origin=ToolOrigin.LOCAL,
+                category=category_str
             )
             default_tool_registry.register_tool(definition)
             

autobyteus/tools/tool_origin.py

@@ -0,0 +1,10 @@
+# file: autobyteus/autobyteus/tools/tool_origin.py
+from enum import Enum
+
+class ToolOrigin(str, Enum):
+    """Enumeration of tool origins to identify their execution model."""
+    LOCAL = "local"
+    MCP = "mcp"
+
+    def __str__(self) -> str:
+        return self.value

autobyteus/workflow/agentic_workflow.py

@@ -0,0 +1,93 @@
+# file: autobyteus/autobyteus/workflow/agentic_workflow.py
+import logging
+from typing import Optional
+
+from autobyteus.workflow.runtime.workflow_runtime import WorkflowRuntime
+from autobyteus.workflow.events.workflow_events import ProcessUserMessageEvent, ToolApprovalWorkflowEvent
+from autobyteus.agent.message.agent_input_user_message import AgentInputUserMessage
+from autobyteus.workflow.phases.workflow_operational_phase import WorkflowOperationalPhase
+
+logger = logging.getLogger(__name__)
+
+class AgenticWorkflow:
+    """
+    User-facing facade for interacting with a managed workflow.
+    This class is a lightweight wrapper around a WorkflowRuntime instance
+    and is typically created by a WorkflowFactory.
+    """
+    def __init__(self, runtime: WorkflowRuntime):
+        """
+        Initializes the AgenticWorkflow facade.
+
+        Args:
+            runtime: The pre-configured and ready-to-use runtime for the workflow.
+        """
+        if not isinstance(runtime, WorkflowRuntime):
+            raise TypeError(f"AgenticWorkflow requires a WorkflowRuntime instance, got {type(runtime).__name__}")
+        
+        self._runtime = runtime
+        self.workflow_id: str = self._runtime.context.workflow_id
+        logger.info(f"AgenticWorkflow facade created for workflow ID '{self.workflow_id}'.")
+
+    @property
+    def name(self) -> str:
+        return self._runtime.context.config.name
+
+    @property
+    def role(self) -> Optional[str]:
+        """The role of the workflow, for when it's used as a sub-workflow."""
+        return self._runtime.context.config.role
+
+    async def post_message(self, message: AgentInputUserMessage, target_agent_name: Optional[str] = None) -> None:
+        """
+        Submits a message to the workflow, routing it to a specific node (agent or sub-workflow).
+        If `target_agent_name` is not provided, the message is sent to the workflow's coordinator.
+        """
+        final_target_name = target_agent_name or self._runtime.context.config.coordinator_node.name
+        logger.info(f"Workflow '{self.workflow_id}': post_message called. Target: '{final_target_name}'.")
+
+        if not self._runtime.is_running:
+            self.start()
+        
+        event = ProcessUserMessageEvent(
+            user_message=message,
+            target_agent_name=final_target_name
+        )
+        await self._runtime.submit_event(event)
+
+    async def post_tool_execution_approval(
+        self,
+        agent_name: str,
+        tool_invocation_id: str,
+        is_approved: bool,
+        reason: Optional[str] = None
+    ):
+        """Submits a tool execution approval/denial to a specific agent in the workflow."""
+        logger.info(f"Workflow '{self.workflow_id}': post_tool_execution_approval called for agent '{agent_name}'. Approved: {is_approved}.")
+        if not self._runtime.is_running:
+            logger.warning(f"Workflow '{self.workflow_id}' is not running. Cannot post approval.")
+            return
+
+        event = ToolApprovalWorkflowEvent(
+            agent_name=agent_name,
+            tool_invocation_id=tool_invocation_id,
+            is_approved=is_approved,
+            reason=reason,
+        )
+        await self._runtime.submit_event(event)
+
+    def start(self) -> None:
+        """Starts the workflow's background worker thread."""
+        self._runtime.start()
+
+    async def stop(self, timeout: float = 10.0) -> None:
+        """Stops the workflow and all its agents."""
+        await self._runtime.stop(timeout)
+
+    @property
+    def is_running(self) -> bool:
+        """Checks if the workflow's worker is running."""
+        return self._runtime.is_running
+        
+    def get_current_phase(self) -> WorkflowOperationalPhase: 
+        return self._runtime.context.state.current_phase