autobyteus 1.1.3__py3-none-any.whl → 1.1.5__py3-none-any.whl

autobyteus/workflow/bootstrap_steps/agent_tool_injection_step.py

@@ -0,0 +1,34 @@
+# file: autobyteus/autobyteus/workflow/bootstrap_steps/agent_tool_injection_step.py
+import logging
+from typing import TYPE_CHECKING, Dict, Set
+
+from autobyteus.workflow.bootstrap_steps.base_workflow_bootstrap_step import BaseWorkflowBootstrapStep
+from autobyteus.agent.context import AgentConfig
+from autobyteus.agent.message.send_message_to import SendMessageTo
+from autobyteus.workflow.context.workflow_node_config import WorkflowNodeConfig
+from autobyteus.tools.registry import default_tool_registry
+
+if TYPE_CHECKING:
+    from autobyteus.workflow.context.workflow_context import WorkflowContext
+    from autobyteus.workflow.phases.workflow_phase_manager import WorkflowPhaseManager
+
+logger = logging.getLogger(__name__)
+
+class AgentToolInjectionStep(BaseWorkflowBootstrapStep):
+    """
+    Bootstrap step to inject workflow-aware tools like SendMessageTo into
+    agent configurations just before they are used. This step is now effectively
+    a placeholder as tool injection is handled just-in-time by the TeamManager,
+    but it is kept for potential future use and to maintain the bootstrap sequence structure.
+    The primary logic of applying the coordinator prompt has been moved to the TeamManager
+    to ensure it happens just before the coordinator is created.
+    """
+    async def execute(self, context: 'WorkflowContext', phase_manager: 'WorkflowPhaseManager') -> bool:
+        workflow_id = context.workflow_id
+        logger.info(f"Workflow '{workflow_id}': Executing AgentToolInjectionStep (now a placeholder).")
+        # The logic for injecting SendMessageTo and setting the coordinator prompt is now
+        # handled just-in-time by the TeamManager to better support lazy-loading of nodes.
+        # This step is preserved in the bootstrap sequence for clarity and future expansion.
+        logger.debug(f"Workflow '{workflow_id}': Tool injection and prompt setting are deferred to TeamManager.")
+        return True
+

autobyteus/workflow/bootstrap_steps/base_workflow_bootstrap_step.py

@@ -0,0 +1,23 @@
+# file: autobyteus/autobyteus/workflow/bootstrap_steps/base_workflow_bootstrap_step.py
+import logging
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from autobyteus.workflow.context.workflow_context import WorkflowContext
+    from autobyteus.workflow.phases.workflow_phase_manager import WorkflowPhaseManager
+
+logger = logging.getLogger(__name__)
+
+class BaseWorkflowBootstrapStep(ABC):
+    """Abstract base class for individual steps in the workflow bootstrapping process."""
+
+    @abstractmethod
+    async def execute(self, context: 'WorkflowContext', phase_manager: 'WorkflowPhaseManager') -> bool:
+        """
+        Executes the bootstrap step.
+
+        Returns:
+            True if the step completed successfully, False otherwise.
+        """
+        raise NotImplementedError("Subclasses must implement the 'execute' method.")

autobyteus/workflow/bootstrap_steps/coordinator_initialization_step.py

@@ -0,0 +1,41 @@
+# file: autobyteus/autobyteus/workflow/bootstrap_steps/coordinator_initialization_step.py
+import logging
+from typing import TYPE_CHECKING
+
+from autobyteus.workflow.bootstrap_steps.base_workflow_bootstrap_step import BaseWorkflowBootstrapStep
+
+if TYPE_CHECKING:
+    from autobyteus.workflow.context.workflow_context import WorkflowContext
+    from autobyteus.workflow.phases.workflow_phase_manager import WorkflowPhaseManager
+
+logger = logging.getLogger(__name__)
+
+class CoordinatorInitializationStep(BaseWorkflowBootstrapStep):
+    """
+    Bootstrap step that eagerly instantiates and starts the coordinator agent
+    using the TeamManager. This ensures the coordinator is ready before the
+    workflow becomes idle.
+    """
+    async def execute(self, context: 'WorkflowContext', phase_manager: 'WorkflowPhaseManager') -> bool:
+        workflow_id = context.workflow_id
+        logger.info(f"Workflow '{workflow_id}': Executing CoordinatorInitializationStep.")
+        
+        try:
+            team_manager = context.team_manager
+            if not team_manager:
+                raise RuntimeError("TeamManager not found in workflow context. It should be created by the factory.")
+
+            coordinator_name = context.config.coordinator_node.name
+
+            # This call now ensures the coordinator agent is fully created and ready.
+            coordinator = await team_manager.ensure_coordinator_is_ready(coordinator_name)
+            
+            if not coordinator:
+                raise RuntimeError(f"TeamManager failed to return a ready coordinator agent for '{coordinator_name}'.")
+
+            logger.info(f"Workflow '{workflow_id}': Coordinator '{coordinator_name}' initialized and started via TeamManager.")
+            return True
+        
+        except Exception as e:
+            logger.error(f"Workflow '{workflow_id}': Failed to initialize coordinator agent: {e}", exc_info=True)
+            return False

autobyteus/workflow/bootstrap_steps/coordinator_prompt_preparation_step.py

@@ -0,0 +1,108 @@
+# file: autobyteus/autobyteus/workflow/bootstrap_steps/coordinator_prompt_preparation_step.py
+import logging
+from typing import TYPE_CHECKING, Dict, Set, List
+
+from autobyteus.workflow.bootstrap_steps.base_workflow_bootstrap_step import BaseWorkflowBootstrapStep
+from autobyteus.agent.context import AgentConfig
+from autobyteus.workflow.context.workflow_node_config import WorkflowNodeConfig
+from autobyteus.workflow.context.workflow_config import WorkflowConfig
+
+if TYPE_CHECKING:
+    from autobyteus.workflow.context.workflow_context import WorkflowContext
+    from autobyteus.workflow.phases.workflow_phase_manager import WorkflowPhaseManager
+
+logger = logging.getLogger(__name__)
+
+class CoordinatorPromptPreparationStep(BaseWorkflowBootstrapStep):
+    """
+    Bootstrap step to dynamically generate the coordinator's system prompt
+    based on the workflow's structure and store it in the workflow's state.
+    """
+    async def execute(self, context: 'WorkflowContext', phase_manager: 'WorkflowPhaseManager') -> bool:
+        workflow_id = context.workflow_id
+        logger.info(f"Workflow '{workflow_id}': Executing CoordinatorPromptPreparationStep.")
+        try:
+            coordinator_node = context.config.coordinator_node
+            member_nodes = {node for node in context.config.nodes if node != coordinator_node}
+
+            member_node_ids = self._generate_unique_node_ids(member_nodes)
+            dynamic_prompt = self._generate_prompt(context, member_node_ids)
+            
+            context.state.prepared_coordinator_prompt = dynamic_prompt
+
+            logger.info(f"Workflow '{workflow_id}': Coordinator prompt prepared successfully and stored in state.")
+            return True
+        except Exception as e:
+            logger.error(f"Workflow '{workflow_id}': Failed to prepare coordinator prompt: {e}", exc_info=True)
+            return False
+
+    def _generate_unique_node_ids(self, member_nodes: Set[WorkflowNodeConfig]) -> Dict[WorkflowNodeConfig, str]:
+        id_map: Dict[WorkflowNodeConfig, str] = {}
+        name_counts: Dict[str, int] = {}
+        sorted_nodes = sorted(list(member_nodes), key=lambda n: n.name)
+        for node in sorted_nodes:
+            base_name = node.name
+            count = name_counts.get(base_name, 0)
+            unique_id = f"{base_name}_{count + 1}" if base_name in name_counts else base_name
+            id_map[node] = unique_id
+            name_counts[base_name] = count + 1
+        return id_map
+
+    def _generate_prompt(self, context: 'WorkflowContext', member_node_ids: Dict[WorkflowNodeConfig, str]) -> str:
+        prompt_parts: List[str] = []
+
+        tools_section = (
+            "### Your Tools\n"
+            "To accomplish your goal, you have access to the following tools. You should use them as needed.\n"
+            "{{tools}}"
+        )
+
+        if member_node_ids:
+            role_and_goal = (
+                "You are the coordinator of a team of specialist agents and sub-workflows. Your primary goal is to "
+                "achieve the following objective by delegating tasks to your team members:\n"
+                f"### Goal\n{context.config.description}"
+            )
+            prompt_parts.append(role_and_goal)
+            
+            team_lines = []
+            for node, uid in member_node_ids.items():
+                node_def = node.node_definition
+                if node.is_subworkflow and isinstance(node_def, WorkflowConfig):
+                    # For sub-workflows, use its role and description
+                    role = node_def.role or "(Sub-Workflow)"
+                    team_lines.append(f"- **{uid}** (Role: {role}): {node_def.description}")
+                elif isinstance(node_def, AgentConfig):
+                    # For agents, use its role and description
+                    team_lines.append(f"- **{uid}** (Role: {node_def.role}): {node_def.description}")
+
+            team_manifest = "### Your Team\n" + "\n".join(team_lines)
+            prompt_parts.append(team_manifest)
+
+            rules_list: List[str] = []
+            for node, uid in member_node_ids.items():
+                if node.dependencies:
+                    dep_names = [member_node_ids.get(dep, dep.name) for dep in node.dependencies]
+                    rules_list.append(f"To use '{uid}', you must have already successfully used: {', '.join(f'`{name}`' for name in dep_names)}.")
+            
+            if rules_list:
+                rules_section = "### Execution Rules\n" + "\n".join(rules_list)
+                prompt_parts.append(rules_section)
+
+            prompt_parts.append(tools_section)
+                
+            final_instruction = "### Your Task\nAnalyze the user's request, formulate a plan, and use the `SendMessageTo` tool to delegate tasks to your team. Address team members by their unique ID as listed under 'Your Team'."
+            prompt_parts.append(final_instruction)
+        else:
+            role_and_goal = (
+                "You are working alone. Your primary goal is to achieve the following objective:\n"
+                f"### Goal\n{context.config.description}"
+            )
+            prompt_parts.append(role_and_goal)
+            prompt_parts.append("### Your Team\nYou are working alone on this task.")
+            prompt_parts.append(tools_section)
+            final_instruction = "### Your Task\nAnalyze the user's request, formulate a plan, and use your available tools to achieve the goal."
+            prompt_parts.append(final_instruction)
+
+        return "\n\n".join(prompt_parts)
+

autobyteus/workflow/bootstrap_steps/workflow_bootstrapper.py

@@ -0,0 +1,50 @@
+# file: autobyteus/autobyteus/workflow/bootstrap_steps/workflow_bootstrapper.py
+import logging
+from typing import TYPE_CHECKING, List, Optional
+
+from autobyteus.workflow.bootstrap_steps.base_workflow_bootstrap_step import BaseWorkflowBootstrapStep
+from autobyteus.workflow.bootstrap_steps.workflow_runtime_queue_initialization_step import WorkflowRuntimeQueueInitializationStep
+from autobyteus.workflow.bootstrap_steps.coordinator_prompt_preparation_step import CoordinatorPromptPreparationStep
+from autobyteus.workflow.bootstrap_steps.agent_tool_injection_step import AgentToolInjectionStep
+from autobyteus.workflow.bootstrap_steps.coordinator_initialization_step import CoordinatorInitializationStep
+from autobyteus.workflow.events.workflow_events import WorkflowReadyEvent
+
+if TYPE_CHECKING:
+    from autobyteus.workflow.context.workflow_context import WorkflowContext
+    from autobyteus.workflow.phases.workflow_phase_manager import WorkflowPhaseManager
+
+logger = logging.getLogger(__name__)
+
+class WorkflowBootstrapper:
+    """Orchestrates the workflow's bootstrapping process."""
+    def __init__(self, steps: Optional[List[BaseWorkflowBootstrapStep]] = None):
+        self.bootstrap_steps = steps or [
+            WorkflowRuntimeQueueInitializationStep(),
+            CoordinatorPromptPreparationStep(),
+            AgentToolInjectionStep(),
+            CoordinatorInitializationStep(),
+        ]
+
+    async def run(self, context: 'WorkflowContext', phase_manager: 'WorkflowPhaseManager') -> bool:
+        workflow_id = context.workflow_id
+        await phase_manager.notify_bootstrapping_started()
+        logger.info(f"Workflow '{workflow_id}': Bootstrapper starting.")
+
+        for step in self.bootstrap_steps:
+            step_name = step.__class__.__name__
+            logger.debug(f"Workflow '{workflow_id}': Executing bootstrap step: {step_name}")
+            if not await step.execute(context, phase_manager):
+                error_message = f"Bootstrap step {step_name} failed."
+                logger.error(f"Workflow '{workflow_id}': {error_message}")
+                await phase_manager.notify_error_occurred(error_message, f"Failed during bootstrap step '{step_name}'.")
+                return False
+        
+        logger.info(f"Workflow '{workflow_id}': All bootstrap steps completed successfully.")
+        if context.state.input_event_queues:
+            await context.state.input_event_queues.enqueue_internal_system_event(WorkflowReadyEvent())
+        else:
+            logger.critical(f"Workflow '{workflow_id}': Bootstrap succeeded but queues not available.")
+            await phase_manager.notify_error_occurred("Queues unavailable after bootstrap.", "")
+            return False
+            
+        return True

autobyteus/workflow/bootstrap_steps/workflow_runtime_queue_initialization_step.py

@@ -0,0 +1,25 @@
+# file: autobyteus/autobyteus/workflow/bootstrap_steps/workflow_runtime_queue_initialization_step.py
+import logging
+from typing import TYPE_CHECKING
+
+from autobyteus.workflow.bootstrap_steps.base_workflow_bootstrap_step import BaseWorkflowBootstrapStep
+from autobyteus.workflow.events.workflow_input_event_queue_manager import WorkflowInputEventQueueManager
+
+if TYPE_CHECKING:
+    from autobyteus.workflow.context.workflow_context import WorkflowContext
+    from autobyteus.workflow.phases.workflow_phase_manager import WorkflowPhaseManager
+
+logger = logging.getLogger(__name__)
+
+class WorkflowRuntimeQueueInitializationStep(BaseWorkflowBootstrapStep):
+    """Bootstrap step for initializing the workflow's runtime event queues."""
+    async def execute(self, context: 'WorkflowContext', phase_manager: 'WorkflowPhaseManager') -> bool:
+        workflow_id = context.workflow_id
+        logger.info(f"Workflow '{workflow_id}': Executing WorkflowRuntimeQueueInitializationStep.")
+        try:
+            context.state.input_event_queues = WorkflowInputEventQueueManager()
+            logger.info(f"Workflow '{workflow_id}': WorkflowInputEventQueueManager initialized.")
+            return True
+        except Exception as e:
+            logger.error(f"Workflow '{workflow_id}': Critical failure during queue initialization: {e}", exc_info=True)
+            return False

autobyteus/workflow/context/__init__.py

@@ -0,0 +1,17 @@
+# file: autobyteus/autobyteus/workflow/context/__init__.py
+"""
+Components related to the workflow's runtime context, state, and configuration.
+"""
+from autobyteus.workflow.context.team_manager import TeamManager
+from autobyteus.workflow.context.workflow_config import WorkflowConfig
+from autobyteus.workflow.context.workflow_context import WorkflowContext
+from autobyteus.workflow.context.workflow_node_config import WorkflowNodeConfig
+from autobyteus.workflow.context.workflow_runtime_state import WorkflowRuntimeState
+
+__all__ = [
+    "TeamManager",
+    "WorkflowConfig",
+    "WorkflowContext",
+    "WorkflowNodeConfig",
+    "WorkflowRuntimeState",
+]

autobyteus/workflow/context/team_manager.py

@@ -0,0 +1,147 @@
+# file: autobyteus/autobyteus/workflow/context/team_manager.py
+import asyncio
+import logging
+from typing import List, Dict, Optional, TYPE_CHECKING, Union
+
+from autobyteus.agent.factory import AgentFactory
+from autobyteus.agent.utils.wait_for_idle import wait_for_agent_to_be_idle
+from autobyteus.workflow.utils.wait_for_idle import wait_for_workflow_to_be_idle
+from autobyteus.workflow.exceptions import WorkflowNodeNotFoundException
+from autobyteus.agent.message.send_message_to import SendMessageTo
+from autobyteus.tools.registry import default_tool_registry
+
+if TYPE_CHECKING:
+    from autobyteus.agent.agent import Agent
+    from autobyteus.workflow.agentic_workflow import AgenticWorkflow
+    from autobyteus.workflow.events.workflow_events import InterAgentMessageRequestEvent
+    from autobyteus.workflow.runtime.workflow_runtime import WorkflowRuntime
+    from autobyteus.workflow.streaming.agent_event_multiplexer import AgentEventMultiplexer
+    from autobyteus.agent.context.agent_config import AgentConfig
+    from autobyteus.workflow.context.workflow_config import WorkflowConfig
+
+ManagedNode = Union['Agent', 'AgenticWorkflow']
+
+logger = logging.getLogger(__name__)
+
+class TeamManager:
+    """
+    Manages all nodes (agents and sub-workflows) within a workflow. It handles
+    lazy creation, on-demand startup, and provides access to managed instances.
+    """
+    def __init__(self, workflow_id: str, runtime: 'WorkflowRuntime', multiplexer: 'AgentEventMultiplexer'):
+        self.workflow_id = workflow_id
+        self._runtime = runtime
+        self._multiplexer = multiplexer
+        self._agent_factory = AgentFactory()
+        self._nodes_cache: Dict[str, ManagedNode] = {}
+        self._coordinator_agent: Optional['Agent'] = None
+        logger.info(f"TeamManager created for workflow '{self.workflow_id}'.")
+
+    async def dispatch_inter_agent_message_request(self, event: 'InterAgentMessageRequestEvent'):
+        await self._runtime.submit_event(event)
+
+    async def ensure_node_is_ready(self, name: str) -> ManagedNode:
+        """
+        Retrieves a node (agent or sub-workflow) by its unique friendly name.
+        If the node has not been created yet, it is instantiated. If it is not
+        running, it is started and awaited until idle.
+        Returns a fully ready node instance or raises an exception.
+        """
+        node_instance = self._nodes_cache.get(name)
+        
+        was_created = False
+        if not node_instance:
+            logger.debug(f"Node '{name}' not in cache for workflow '{self.workflow_id}'. Attempting lazy creation.")
+            
+            node_config_wrapper = self._runtime.context.get_node_config_by_name(name)
+            if not node_config_wrapper:
+                raise WorkflowNodeNotFoundException(node_name=name, workflow_id=self.workflow_id)
+
+            node_definition = node_config_wrapper.node_definition
+
+            if node_config_wrapper.is_subworkflow:
+                from autobyteus.workflow.factory.workflow_factory import WorkflowFactory
+                from autobyteus.workflow.context.workflow_config import WorkflowConfig
+                
+                workflow_factory = WorkflowFactory() # Get singleton instance
+                if not isinstance(node_definition, WorkflowConfig):
+                     raise TypeError(f"Expected WorkflowConfig for node '{name}', but found {type(node_definition)}")
+                logger.info(f"Lazily creating sub-workflow node '{name}' in workflow '{self.workflow_id}'.")
+                node_instance = workflow_factory.create_workflow(config=node_definition)
+            else:
+                from autobyteus.agent.context.agent_config import AgentConfig
+                if not isinstance(node_definition, AgentConfig):
+                     raise TypeError(f"Expected AgentConfig for node '{name}', but found {type(node_definition)}")
+                
+                # --- Apply Deferred Logic from Bootstrap Step ---
+                final_config = node_definition.copy()
+
+                # 1. Inject SendMessageTo tool
+                send_message_tool = default_tool_registry.create_tool(SendMessageTo.get_name())
+                if isinstance(send_message_tool, SendMessageTo):
+                    send_message_tool.set_team_manager(self)
+                final_config.tools = [t for t in final_config.tools if not isinstance(t, SendMessageTo)]
+                final_config.tools.append(send_message_tool)
+
+                # 2. Apply coordinator prompt if this is the coordinator
+                coordinator_node_name = self._runtime.context.config.coordinator_node.name
+                if name == coordinator_node_name:
+                    coordinator_prompt = self._runtime.context.state.prepared_coordinator_prompt
+                    if coordinator_prompt:
+                        final_config.system_prompt = coordinator_prompt
+                        logger.info(f"Applied dynamic prompt to coordinator '{name}'.")
+                
+                logger.info(f"Lazily creating agent node '{name}' in workflow '{self.workflow_id}'.")
+                node_instance = self._agent_factory.create_agent(config=final_config)
+            
+            self._nodes_cache[name] = node_instance
+            was_created = True
+
+        if was_created and node_instance:
+            from autobyteus.workflow.agentic_workflow import AgenticWorkflow
+            from autobyteus.agent.agent import Agent
+            if isinstance(node_instance, AgenticWorkflow):
+                self._multiplexer.start_bridging_workflow_events(node_instance, name)
+            elif isinstance(node_instance, Agent):
+                self._multiplexer.start_bridging_agent_events(node_instance, name)
+
+        # On-Demand Startup Logic
+        if not node_instance.is_running:
+            from autobyteus.workflow.agentic_workflow import AgenticWorkflow
+            logger.info(f"Workflow '{self.workflow_id}': Node '{name}' is not running. Starting on-demand.")
+            try:
+                node_instance.start()
+                if isinstance(node_instance, AgenticWorkflow):
+                    await wait_for_workflow_to_be_idle(node_instance, timeout=120.0)
+                else:
+                    await wait_for_agent_to_be_idle(node_instance, timeout=60.0)
+            except Exception as e:
+                logger.error(f"Workflow '{self.workflow_id}': Failed to start node '{name}' on-demand: {e}", exc_info=True)
+                raise RuntimeError(f"Failed to start node '{name}' on-demand.") from e
+        
+        return node_instance
+
+    def get_all_agents(self) -> List['Agent']:
+        from autobyteus.agent.agent import Agent
+        return [node for node in self._nodes_cache.values() if isinstance(node, Agent)]
+
+    def get_all_sub_workflows(self) -> List['AgenticWorkflow']:
+        from autobyteus.workflow.agentic_workflow import AgenticWorkflow
+        return [node for node in self._nodes_cache.values() if isinstance(node, AgenticWorkflow)]
+
+    @property
+    def coordinator_agent(self) -> Optional['Agent']:
+        return self._coordinator_agent
+
+    async def ensure_coordinator_is_ready(self, coordinator_name: str) -> 'Agent':
+        """
+        Ensures the coordinator agent is created, started, and ready, then
+        designates it as the coordinator.
+        """
+        from autobyteus.agent.agent import Agent
+        node = await self.ensure_node_is_ready(coordinator_name)
+        if not isinstance(node, Agent):
+            raise TypeError(f"Coordinator node '{coordinator_name}' resolved to a non-agent type: {type(node).__name__}")
+
+        self._coordinator_agent = node
+        return node

autobyteus/workflow/context/workflow_config.py

@@ -0,0 +1,30 @@
+# file: autobyteus/autobyteus/workflow/context/workflow_config.py
+import logging
+from dataclasses import dataclass, field
+from typing import List, Optional, Tuple
+
+from autobyteus.workflow.context.workflow_node_config import WorkflowNodeConfig
+
+logger = logging.getLogger(__name__)
+
+@dataclass(frozen=True)
+class WorkflowConfig:
+    """
+    Represents the complete, static configuration for an AgenticWorkflow instance.
+    This is the user's primary input for defining a workflow.
+    """
+    name: str
+    description: str
+    nodes: Tuple[WorkflowNodeConfig, ...]
+    coordinator_node: WorkflowNodeConfig
+    role: Optional[str] = None
+
+    def __post_init__(self):
+        if not self.name or not isinstance(self.name, str):
+            raise ValueError("The 'name' in WorkflowConfig must be a non-empty string.")
+        if not self.nodes:
+            raise ValueError("The 'nodes' collection in WorkflowConfig cannot be empty.")
+        if self.coordinator_node not in self.nodes:
+            raise ValueError("The 'coordinator_node' must be one of the nodes in the 'nodes' collection.")
+        logger.debug(f"WorkflowConfig validated for workflow: '{self.name}'.")
+

autobyteus/workflow/context/workflow_context.py

@@ -0,0 +1,61 @@
+# file: autobyteus/autobyteus/workflow/context/workflow_context.py
+import logging
+from typing import TYPE_CHECKING, List, Optional, Dict
+
+if TYPE_CHECKING:
+    from autobyteus.workflow.context.workflow_config import WorkflowConfig
+    from autobyteus.workflow.context.workflow_runtime_state import WorkflowRuntimeState
+    from autobyteus.agent.agent import Agent
+    from autobyteus.workflow.phases.workflow_phase_manager import WorkflowPhaseManager
+    from autobyteus.workflow.context.team_manager import TeamManager
+    from autobyteus.workflow.streaming.agent_event_multiplexer import AgentEventMultiplexer
+    from autobyteus.agent.context import AgentConfig
+    from autobyteus.workflow.context.workflow_node_config import WorkflowNodeConfig
+
+logger = logging.getLogger(__name__)
+
+class WorkflowContext:
+    """Represents the complete operational context for a single workflow instance."""
+    def __init__(self, workflow_id: str, config: 'WorkflowConfig', state: 'WorkflowRuntimeState'):
+        if not workflow_id or not isinstance(workflow_id, str):
+            raise ValueError("WorkflowContext requires a non-empty string 'workflow_id'.")
+        
+        self.workflow_id: str = workflow_id
+        self.config: 'WorkflowConfig' = config
+        self.state: 'WorkflowRuntimeState' = state
+        self._node_config_map: Optional[Dict[str, 'WorkflowNodeConfig']] = None
+        
+        logger.info(f"WorkflowContext composed for workflow_id '{self.workflow_id}'.")
+
+    def get_node_config_by_name(self, name: str) -> Optional['WorkflowNodeConfig']:
+        """Efficiently retrieves a node's config by its friendly name."""
+        if self._node_config_map is None:
+            # Build cache on first access
+            self._node_config_map = {node.name: node for node in self.config.nodes}
+        return self._node_config_map.get(name)
+
+    @property
+    def agents(self) -> List['Agent']:
+        """Returns all agents managed by the TeamManager."""
+        if self.state.team_manager:
+            return self.state.team_manager.get_all_agents()
+        return []
+
+    @property
+    def coordinator_agent(self) -> Optional['Agent']:
+        """Returns the coordinator agent from the TeamManager."""
+        if self.state.team_manager:
+            return self.state.team_manager.coordinator_agent
+        return None
+
+    @property
+    def phase_manager(self) -> Optional['WorkflowPhaseManager']:
+        return self.state.phase_manager_ref
+
+    @property
+    def team_manager(self) -> Optional['TeamManager']:
+        return self.state.team_manager
+        
+    @property
+    def multiplexer(self) -> Optional['AgentEventMultiplexer']:
+        return self.state.multiplexer_ref

autobyteus/workflow/context/workflow_node_config.py

@@ -0,0 +1,76 @@
+# file: autobyteus/autobyteus/workflow/context/workflow_node_config.py
+from __future__ import annotations
+import logging
+import uuid
+from dataclasses import dataclass, field
+from typing import List, TYPE_CHECKING, Union, Tuple
+
+# The import is moved into the TYPE_CHECKING block to break the circular dependency at module load time.
+if TYPE_CHECKING:
+    from autobyteus.agent.context import AgentConfig
+    from autobyteus.workflow.context.workflow_config import WorkflowConfig
+
+logger = logging.getLogger(__name__)
+
+@dataclass
+class WorkflowNodeConfig:
+    """
+    Represents a node in an agentic workflow graph.
+
+    This is the core building block for defining workflows. A node can be either
+    a single agent (defined by an AgentConfig) or an entire sub-workflow
+    (defined by a WorkflowConfig).
+
+    Attributes:
+        node_definition: The configuration for the agent or sub-workflow at this node.
+        dependencies: A tuple of other WorkflowNodeConfig objects that must be
+                      successfully executed before this node can be executed.
+        node_id: A unique identifier for this node instance.
+    """
+    node_definition: Union["AgentConfig", "WorkflowConfig"]
+    dependencies: Tuple[WorkflowNodeConfig, ...] = field(default_factory=tuple)
+    node_id: str = field(default_factory=lambda: f"node_{uuid.uuid4().hex}", init=False, repr=False)
+
+    def __post_init__(self):
+        """Validates the node configuration."""
+        from autobyteus.agent.context import AgentConfig
+        from autobyteus.workflow.context.workflow_config import WorkflowConfig
+        
+        if not isinstance(self.node_definition, (AgentConfig, WorkflowConfig)):
+            raise TypeError("The 'node_definition' attribute must be an instance of AgentConfig or WorkflowConfig.")
+        
+        if not all(isinstance(dep, WorkflowNodeConfig) for dep in self.dependencies):
+            raise TypeError("All items in 'dependencies' must be instances of WorkflowNodeConfig.")
+
+        logger.debug(f"WorkflowNodeConfig created for: '{self.name}' (NodeID: {self.node_id}). Dependencies: {[dep.name for dep in self.dependencies]}")
+
+    @property
+    def name(self) -> str:
+        """A convenience property to get the node's name from its definition."""
+        return self.node_definition.name
+
+    @property
+    def effective_config(self) -> Union["AgentConfig", "WorkflowConfig"]:
+        """Returns the underlying AgentConfig or WorkflowConfig."""
+        return self.node_definition
+
+    @property
+    def is_subworkflow(self) -> bool:
+        """Returns True if this node represents a sub-workflow."""
+        from autobyteus.workflow.context.workflow_config import WorkflowConfig
+        return isinstance(self.node_definition, WorkflowConfig)
+    
+    def __hash__(self):
+        """
+        Makes the node hashable based on its unique node_id, allowing it to be
+        used in sets and as dictionary keys.
+        """
+        return hash(self.node_id)
+    
+    def __eq__(self, other):
+        """
+        Compares two nodes based on their unique node_id.
+        """
+        if isinstance(other, WorkflowNodeConfig):
+            return self.node_id == other.node_id
+        return False