autobyteus 1.0.6__py3-none-any.whl → 1.1.1__py3-none-any.whl

autobyteus/agent/llm_response_processor/provider_aware_tool_usage_processor.py

@@ -0,0 +1,54 @@
+# file: autobyteus/autobyteus/agent/llm_response_processor/provider_aware_tool_usage_processor.py
+import logging
+from typing import TYPE_CHECKING
+
+from .base_processor import BaseLLMResponseProcessor
+from autobyteus.tools.usage.parsers import ProviderAwareToolUsageParser
+from autobyteus.tools.usage.parsers.exceptions import ToolUsageParseException
+from autobyteus.agent.events import PendingToolInvocationEvent
+
+if TYPE_CHECKING:
+    from autobyteus.agent.context import AgentContext
+    from autobyteus.agent.events import LLMCompleteResponseReceivedEvent
+    from autobyteus.llm.utils.response_types import CompleteResponse
+
+logger = logging.getLogger(__name__)
+
+class ProviderAwareToolUsageProcessor(BaseLLMResponseProcessor):
+    """
+    A "master" tool usage processor that uses a high-level parser from the
+    `tools` module to extract tool invocations, and then enqueues the
+    necessary agent events based on the parsed results.
+    """
+    def __init__(self):
+        self._parser = ProviderAwareToolUsageParser()
+        logger.debug("ProviderAwareToolUsageProcessor initialized.")
+
+    @classmethod
+    def get_name(cls) -> str:
+        return "provider_aware_tool_usage"
+
+    async def process_response(self, response: 'CompleteResponse', context: 'AgentContext', triggering_event: 'LLMCompleteResponseReceivedEvent') -> bool:
+        """
+        Uses a ProviderAwareToolUsageParser to get a list of tool invocations,
+        and then enqueues a PendingToolInvocationEvent for each one.
+        Propagates ToolUsageParseException if parsing fails.
+        """
+        try:
+            # Delegate parsing to the high-level parser
+            tool_invocations = self._parser.parse(response, context)
+        except ToolUsageParseException:
+            # Re-raise the exception to be caught by the event handler
+            raise
+
+        if not tool_invocations:
+            return False
+
+        logger.info(f"Agent '{context.agent_id}': Parsed {len(tool_invocations)} tool invocations. Enqueuing events.")
+        for invocation in tool_invocations:
+            logger.info(f"Agent '{context.agent_id}' ({self.get_name()}) identified tool invocation: {invocation.name}. Enqueuing event.")
+            await context.input_event_queues.enqueue_tool_invocation_request(
+                PendingToolInvocationEvent(tool_invocation=invocation)
+            )
+        
+        return True

autobyteus/agent/message/__init__.py

@@ -0,0 +1,20 @@
+# file: autobyteus/autobyteus/agent/message/__init__.py
+"""
+Components related to messaging for and between agents.
+Includes inter-agent messages, user input messages, context files, and related tools.
+"""
+from .inter_agent_message_type import InterAgentMessageType
+from .inter_agent_message import InterAgentMessage
+from .agent_input_user_message import AgentInputUserMessage
+from .send_message_to import SendMessageTo
+from .context_file import ContextFile
+from .context_file_type import ContextFileType
+
+__all__ = [
+    "InterAgentMessage", 
+    "InterAgentMessageType", 
+    "AgentInputUserMessage", 
+    "SendMessageTo",
+    "ContextFile",        
+    "ContextFileType",    
+]

autobyteus/agent/message/agent_input_user_message.py

@@ -0,0 +1,96 @@
+# file: autobyteus/autobyteus/agent/message/agent_input_user_message.py
+import logging
+from typing import Optional, List, Dict, Any
+from dataclasses import dataclass, field
+
+from .context_file import ContextFile # Import the new ContextFile dataclass
+
+logger = logging.getLogger(__name__)
+
+@dataclass
+class AgentInputUserMessage: 
+    """
+    Represents a message received from an external user interacting with the agent system.
+    This is a simple dataclass. It includes support for a list of ContextFile objects, 
+    allowing users to provide various documents as context.
+    """
+    content: str
+    image_urls: Optional[List[str]] = field(default=None) # Basic list of strings
+    context_files: Optional[List[ContextFile]] = field(default=None)
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self):
+        # Basic type validation that dataclasses don't do automatically for mutable defaults or complex types
+        if self.image_urls is not None and not (isinstance(self.image_urls, list) and all(isinstance(url, str) for url in self.image_urls)):
+            raise TypeError("AgentInputUserMessage 'image_urls' must be a list of strings if provided.")
+        if self.context_files is not None and not (isinstance(self.context_files, list) and all(isinstance(cf, ContextFile) for cf in self.context_files)):
+            raise TypeError("AgentInputUserMessage 'context_files' must be a list of ContextFile objects if provided.")
+        if not isinstance(self.metadata, dict): # Should be caught by default_factory, but good practice
+             raise TypeError("AgentInputUserMessage 'metadata' must be a dictionary.")
+        if not isinstance(self.content, str):
+            raise TypeError("AgentInputUserMessage 'content' must be a string.")
+
+        if logger.isEnabledFor(logging.DEBUG):
+            num_context_files = len(self.context_files) if self.context_files else 0
+            logger.debug(
+                f"AgentInputUserMessage initialized. Content: '{self.content[:50]}...', "
+                f"Image URLs: {self.image_urls}, Num ContextFiles: {num_context_files}, "
+                f"Metadata keys: {list(self.metadata.keys())}"
+            )
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Serializes the AgentInputUserMessage to a dictionary."""
+        # Manually handle serialization of list of ContextFile objects
+        context_files_dict_list = None
+        if self.context_files:
+            context_files_dict_list = [cf.to_dict() for cf in self.context_files]
+
+        return {
+            "content": self.content,
+            "image_urls": self.image_urls,
+            "context_files": context_files_dict_list,
+            "metadata": self.metadata,
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> 'AgentInputUserMessage':
+        """Deserializes an AgentInputUserMessage from a dictionary."""
+        content = data.get("content")
+        if not isinstance(content, str): # Ensure content is string
+            raise ValueError("AgentInputUserMessage 'content' in dictionary must be a string.")
+
+        image_urls = data.get("image_urls")
+        if image_urls is not None and not (isinstance(image_urls, list) and all(isinstance(url, str) for url in image_urls)):
+            raise ValueError("AgentInputUserMessage 'image_urls' in dictionary must be a list of strings if provided.")
+
+        context_files_data = data.get("context_files")
+        context_files_list: Optional[List[ContextFile]] = None
+        if context_files_data is not None:
+            if not isinstance(context_files_data, list):
+                raise ValueError("AgentInputUserMessage 'context_files' in dictionary must be a list if provided.")
+            context_files_list = [ContextFile.from_dict(cf_data) for cf_data in context_files_data]
+        
+        metadata = data.get("metadata", {})
+        if not isinstance(metadata, dict):
+            raise ValueError("AgentInputUserMessage 'metadata' in dictionary must be a dict if provided.")
+
+        return cls(
+            content=content,
+            image_urls=image_urls,
+            context_files=context_files_list,
+            metadata=metadata
+        )
+
+    def __repr__(self) -> str:
+        content_preview = f"{self.content[:100]}..." if len(self.content) > 100 else self.content
+        images_repr = f", image_urls={self.image_urls}" if self.image_urls else ""
+        
+        if self.context_files:
+            context_repr = f", context_files=[{len(self.context_files)} ContextFile(s)]"
+        else:
+            context_repr = ""
+            
+        meta_repr = f", metadata_keys={list(self.metadata.keys())}" if self.metadata else ""
+        
+        return (f"AgentInputUserMessage(content='{content_preview}'"
+                f"{images_repr}{context_repr}{meta_repr})")

autobyteus/agent/message/context_file.py

@@ -0,0 +1,82 @@
+# file: autobyteus/autobyteus/agent/message/context_file.py
+import os
+import logging
+from typing import Optional, Dict, Any
+from dataclasses import dataclass, field
+
+from .context_file_type import ContextFileType
+
+logger = logging.getLogger(__name__)
+
+@dataclass
+class ContextFile:
+    """
+    Represents a single context file provided to an agent.
+    This is a simple dataclass, deferring path validation and file access
+    to input processors.
+    """
+    path: str
+    file_type: ContextFileType = ContextFileType.UNKNOWN
+    file_name: Optional[str] = None
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self):
+        """
+        Called after the dataclass's __init__ method.
+        Used here to infer file_name and file_type if not provided or UNKNOWN.
+        """
+        if self.file_name is None and self.path:
+            try:
+                self.file_name = os.path.basename(self.path)
+            except Exception as e:
+                logger.warning(f"Could not determine basename for path '{self.path}': {e}")
+                self.file_name = "unknown_file"
+
+        if self.file_type == ContextFileType.UNKNOWN and self.path:
+            inferred_type = ContextFileType.from_path(self.path)
+            if inferred_type != ContextFileType.UNKNOWN:
+                self.file_type = inferred_type
+                logger.debug(f"Inferred file type for '{self.path}' as {self.file_type.value}")
+            else:
+                logger.debug(f"Could not infer specific file type for '{self.path}', remaining UNKNOWN.")
+        
+        # Ensure path is a string
+        if not isinstance(self.path, str):
+            # This ideally should be caught by type hints earlier, but as a runtime safeguard:
+            raise TypeError(f"ContextFile path must be a string, got {type(self.path)}")
+            
+        if logger.isEnabledFor(logging.DEBUG):
+            logger.debug(f"ContextFile initialized: path='{self.path}', type='{self.file_type.value}', name='{self.file_name}'")
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Serializes the ContextFile to a dictionary."""
+        return {
+            "path": self.path,
+            "file_type": self.file_type.value, # Serialize enum to its value
+            "file_name": self.file_name,
+            "metadata": self.metadata,
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> 'ContextFile':
+        """Deserializes a ContextFile from a dictionary."""
+        if not isinstance(data.get("path"), str):
+            raise ValueError("ContextFile 'path' in dictionary must be a string.")
+        
+        file_type_str = data.get("file_type", ContextFileType.UNKNOWN.value)
+        try:
+            file_type = ContextFileType(file_type_str)
+        except ValueError:
+            logger.warning(f"Invalid file_type string '{file_type_str}' in ContextFile data. Defaulting to UNKNOWN.")
+            file_type = ContextFileType.UNKNOWN
+            
+        return cls(
+            path=data["path"],
+            file_type=file_type,
+            file_name=data.get("file_name"),
+            metadata=data.get("metadata", {})
+        )
+
+    def __repr__(self) -> str:
+        return (f"ContextFile(path='{self.path}', file_name='{self.file_name}', "
+                f"file_type='{self.file_type.value}', metadata_keys={list(self.metadata.keys())})")

autobyteus/agent/message/context_file_type.py

@@ -0,0 +1,63 @@
+from enum import Enum
+import os
+
+class ContextFileType(str, Enum):
+    """
+    Enumerates the types of context files that can be provided to an agent.
+    """
+    TEXT = "text"          # .txt, .md (if treated as plain text initially)
+    MARKDOWN = "markdown"  # .md (if specific markdown processing is intended)
+    PDF = "pdf"            # .pdf
+    DOCX = "docx"          # .docx (Microsoft Word)
+    PPTX = "pptx"          # .pptx (Microsoft PowerPoint)
+    XLSX = "xlsx"          # .xlsx (Microsoft Excel)
+    CSV = "csv"            # .csv
+    JSON = "json"          # .json
+    XML = "xml"            # .xml
+    HTML = "html"          # .html, .htm
+    PYTHON = "python"      # .py
+    JAVASCRIPT = "javascript" # .js
+    IMAGE = "image"        # .png, .jpg, .jpeg, .gif, .webp (when image is for contextual analysis, not direct LLM vision input)
+    UNKNOWN = "unknown"    # Fallback for unrecognized types
+
+    @classmethod
+    def from_path(cls, file_path: str) -> 'ContextFileType':
+        """
+        Infers the ContextFileType from a file path based on its extension.
+        """
+        if not file_path or not isinstance(file_path, str):
+            return cls.UNKNOWN
+        
+        _, extension = os.path.splitext(file_path.lower())
+        
+        if extension == ".txt":
+            return cls.TEXT
+        elif extension == ".md":
+            return cls.MARKDOWN 
+        elif extension == ".pdf":
+            return cls.PDF
+        elif extension == ".docx":
+            return cls.DOCX
+        elif extension == ".pptx":
+            return cls.PPTX
+        elif extension == ".xlsx":
+            return cls.XLSX
+        elif extension == ".csv":
+            return cls.CSV
+        elif extension == ".json":
+            return cls.JSON
+        elif extension == ".xml":
+            return cls.XML
+        elif extension in [".html", ".htm"]:
+            return cls.HTML
+        elif extension == ".py":
+            return cls.PYTHON
+        elif extension == ".js":
+            return cls.JAVASCRIPT
+        elif extension in [".png", ".jpg", ".jpeg", ".gif", ".webp"]:
+            return cls.IMAGE 
+        else:
+            return cls.UNKNOWN
+
+    def __str__(self) -> str:
+        return self.value

autobyteus/agent/message/{message.py → inter_agent_message.py}

@@ -1,16 +1,16 @@
-from autobyteus.agent.message.message_types import MessageType
+from autobyteus.agent.message.inter_agent_message_type import InterAgentMessageType 
 
-class Message:
+class InterAgentMessage:
     def __init__(self, recipient_role_name: str, recipient_agent_id: str, content: str, 
-                 message_type: MessageType, sender_agent_id: str):
+                 message_type: InterAgentMessageType, sender_agent_id: str): # Updated type hint for message_type
         self.recipient_role_name = recipient_role_name
         self.recipient_agent_id = recipient_agent_id
         self.content = content
-        self.message_type = message_type
+        self.message_type: InterAgentMessageType = message_type # Updated type hint for attribute
         self.sender_agent_id = sender_agent_id
 
     def __eq__(self, other):
-        if not isinstance(other, Message):
+        if not isinstance(other, InterAgentMessage): # Updated class check
             return False
         return (self.recipient_role_name == other.recipient_role_name and
                 self.recipient_agent_id == other.recipient_agent_id and
@@ -19,23 +19,23 @@ class Message:
                 self.sender_agent_id == other.sender_agent_id)
 
     def __repr__(self):
-        return (f"Message(recipient_role_name='{self.recipient_role_name}', "
+        return (f"InterAgentMessage(recipient_role_name='{self.recipient_role_name}', " # Updated class name
                 f"recipient_agent_id='{self.recipient_agent_id}', "
                 f"content='{self.content}', "
-                f"message_type=<{self.message_type.__class__.__name__}.{self.message_type.name}: '{self.message_type.value}'>, "
+                f"message_type=<{self.message_type.__class__.__name__}.{self.message_type.name}: '{self.message_type.value}'>, " # message_type class name will be InterAgentMessageType
                 f"sender_agent_id='{self.sender_agent_id}')")
 
     @classmethod
     def create_with_dynamic_message_type(cls, recipient_role_name: str, recipient_agent_id: str,
-                                         content: str, message_type: str, sender_agent_id: str):
+                                         content: str, message_type: str, sender_agent_id: str) -> 'InterAgentMessage': # Updated return type hint
         if not message_type:
             raise ValueError("message_type cannot be empty")
         
         try:
-            msg_type = MessageType(message_type.lower())
+            msg_type = InterAgentMessageType(message_type.lower()) # Use renamed InterAgentMessageType
         except ValueError:
-            msg_type = MessageType.add_type(message_type.upper(), message_type.lower())
+            msg_type = InterAgentMessageType.add_type(message_type.upper(), message_type.lower()) # Use renamed InterAgentMessageType
             if msg_type is None:
-                raise ValueError(f"Failed to create or find MessageType: {message_type}")
+                raise ValueError(f"Failed to create or find InterAgentMessageType: {message_type}") # Updated message
         
-        return cls(recipient_role_name, recipient_agent_id, content, msg_type, sender_agent_id)
+        return cls(recipient_role_name, recipient_agent_id, content, msg_type, sender_agent_id)

autobyteus/agent/message/{message_types.py → inter_agent_message_type.py}

@@ -1,6 +1,6 @@
 from autobyteus.utils.dynamic_enum import DynamicEnum
 
-class MessageType(DynamicEnum):
+class InterAgentMessageType(DynamicEnum):
     TASK_ASSIGNMENT = "task_assignment"
     TASK_RESULT = "task_result"
     TASK_COMPLETED = "task_completed"
@@ -8,16 +8,16 @@ class MessageType(DynamicEnum):
     ERROR = "error"
 
     @classmethod
-    def add_type(cls, name: str, value: str) -> 'MessageType':
+    def add_type(cls, name: str, value: str) -> 'InterAgentMessageType': # Updated return type hint
         """
-        Add a new message type dynamically.
+        Add a new inter-agent message type dynamically.
 
         Args:
             name (str): The name of the new message type.
             value (str): The value of the new message type.
 
         Returns:
-            MessageType: The newly created MessageType.
+            InterAgentMessageType: The newly created InterAgentMessageType. # Updated return type in docstring
 
         Raises:
             ValueError: If the name or value already exists.
@@ -25,5 +25,7 @@ class MessageType(DynamicEnum):
         try:
             return cls.add(name, value)
         except ValueError as e:
-            print(f"Warning: Failed to add new message type. {str(e)}")
-            return None
+            # Consider logging a warning here if a logger is available and appropriate
+            # For now, print as in original code
+            print(f"Warning: Failed to add new inter-agent message type. {str(e)}")
+            return None

autobyteus/agent/message/send_message_to.py

@@ -1,44 +1,150 @@
-# file: autobyteus/agent/group/send_message_to.py
-from autobyteus.agent.message.message import Message
+# file: autobyteus/autobyteus/agent/message/send_message_to.py
+import logging
+from typing import TYPE_CHECKING, Any, Optional
+
+from autobyteus.agent.message.inter_agent_message import InterAgentMessage
 from autobyteus.tools.base_tool import BaseTool
-from typing import TYPE_CHECKING, Any
+from autobyteus.agent.group.agent_group_context import AgentGroupContext
+# Updated imports for schema
+from autobyteus.tools.parameter_schema import ParameterSchema, ParameterDefinition, ParameterType
 
 if TYPE_CHECKING:
-    from autobyteus.agent.orchestrator.base_agent_orchestrator import BaseAgentOrchestrator
+    from autobyteus.agent.context import AgentContext
+    from autobyteus.agent.agent import Agent 
+
+logger = logging.getLogger(__name__)
 
 class SendMessageTo(BaseTool):
-    def __init__(self, orchestrator: 'BaseAgentOrchestrator'):
+    """
+    A tool for sending messages to other agents within the same AgentGroup.
+    It utilizes AgentGroupContext injected into the calling agent's AgentContext
+    to resolve recipient agents.
+    """
+    TOOL_NAME = "SendMessageTo" # Class attribute for the name
+
+    def __init__(self):
         super().__init__()
-        self.orchestrator = orchestrator
+        logger.debug(f"{self.get_name()} tool initialized.") # Use get_name()
+
+    @classmethod
+    def get_name(cls) -> str: # Implemented as per BaseTool requirement
+        return cls.TOOL_NAME
+
+    @classmethod
+    def get_description(cls) -> str:
+        return ("Sends a message to another agent within the same group. "
+                "Can target by role or specific agent ID.")
+
+    @classmethod
+    def get_argument_schema(cls) -> Optional[ParameterSchema]:
+        schema = ParameterSchema()
+        schema.add_parameter(ParameterDefinition(
+            name="recipient_role_name",
+            param_type=ParameterType.STRING,
+            description="The general role name of the recipient agent (e.g., 'worker', 'reviewer').",
+            required=True
+        ))
+        schema.add_parameter(ParameterDefinition(
+            name="content",
+            param_type=ParameterType.STRING,
+            description="The actual message text.",
+            required=True
+        ))
+        schema.add_parameter(ParameterDefinition(
+            name="message_type",
+            param_type=ParameterType.STRING, # Or ENUM if InterAgentMessageType values are known and fixed for schema
+            description="Type of the message (e.g., TASK_ASSIGNMENT, CLARIFICATION). Custom types allowed.",
+            required=True
+        ))
+        schema.add_parameter(ParameterDefinition(
+            name="recipient_agent_id",
+            param_type=ParameterType.STRING,
+            description='Optional. Specific ID of the recipient agent. If "unknown" or omitted, resolves by role.',
+            required=False,
+            default_value=None # Explicitly no default, truly optional
+        ))
+        return schema
+
+    # tool_usage_xml() and tool_usage_json() are inherited from BaseTool
+    # get_config_schema() for instantiation defaults to None
+
+    async def _execute(self, 
+                       context: 'AgentContext', 
+                       recipient_role_name: str, 
+                       content: str, 
+                       message_type: str, 
+                       recipient_agent_id: Optional[str] = None) -> str: # Named parameters
+        """
+        Sends a message to another agent in the group.
+        Arguments are validated by BaseTool.execute().
+        """
+        sender_agent_id = context.agent_id
+        logger.info(f"Tool '{self.get_name()}': Sender '{sender_agent_id}' attempting to send message. "
+                    f"Recipient Role: '{recipient_role_name}', Recipient ID: '{recipient_agent_id}', Type: '{message_type}'.")
+
+        group_context_any = context.custom_data.get('agent_group_context')
+        
+        if not isinstance(group_context_any, AgentGroupContext):
+            error_msg = f"Tool '{self.get_name()}' critical error: AgentGroupContext not found or invalid in AgentContext.custom_data for agent '{sender_agent_id}'. Cannot send message."
+            logger.error(error_msg)
+            return f"Error: {error_msg}"
+        
+        group_context: AgentGroupContext = group_context_any # Type cast after check
+
+        target_agent: Optional['Agent'] = None
+
+        # Use recipient_agent_id if provided and not explicitly "unknown" (case-insensitive)
+        if recipient_agent_id and recipient_agent_id.lower() != "unknown":
+            target_agent = group_context.get_agent(recipient_agent_id)
+            if not target_agent:
+                logger.warning(f"Tool '{self.get_name()}': Agent with ID '{recipient_agent_id}' not found in group '{group_context.group_id}'. "
+                               f"Attempting to find by role '{recipient_role_name}'.")
+        
+        if not target_agent: 
+            agents_with_role = group_context.get_agents_by_role(recipient_role_name)
+            if not agents_with_role:
+                error_msg = f"No agent found with role '{recipient_role_name}' (and specific ID '{recipient_agent_id}' if provided was not found) in group '{group_context.group_id}'."
+                logger.error(f"Tool '{self.get_name()}': {error_msg}")
+                return f"Error: {error_msg}"
+            
+            if len(agents_with_role) > 1:
+                logger.warning(f"Tool '{self.get_name()}': Multiple agents ({len(agents_with_role)}) found for role '{recipient_role_name}'. "
+                               f"Sending to the first one: {agents_with_role[0].agent_id}. "
+                               "Consider using specific recipient_agent_id for clarity.")
+            target_agent = agents_with_role[0]
+            # Update recipient_agent_id to the one resolved by role if it was initially None or "unknown"
+            recipient_agent_id = target_agent.agent_id
+
+
+        if not target_agent: 
+            error_msg = f"Could not resolve recipient agent with role '{recipient_role_name}' or ID '{recipient_agent_id}'." # recipient_agent_id would be updated here
+            logger.error(f"Tool '{self.get_name()}': {error_msg}")
+            return f"Error: {error_msg}"
 
-    async def _execute(self, recipient_role_name: str, recipient_agent_id: str, content: str, message_type: str, sender_agent_id: str) -> Any:
         try:
-            message = Message.create_with_dynamic_message_type(recipient_role_name, recipient_agent_id, content, message_type, sender_agent_id)
-            return await self.orchestrator.route_message(message)
-        except ValueError as e:
-            return f"Error: {str(e)}"
-    
-    def tool_usage_xml(self) -> str:
-        return '''SendMessageTo: Sends a message to another agent in the group. Usage:
-    <command name="SendMessageTo">
-      <arg name="recipient_role_name">GeneralRoleName</arg>
-      <arg name="recipient_agent_id">SpecificAgentId or "unknown"</arg>
-      <arg name="content">Your message here</arg>
-      <arg name="message_type">TASK_ASSIGNMENT|TASK_RESULT|TASK_COMPLETED|CLARIFICATION|ERROR</arg>
-      <arg name="sender_agent_id">YourSpecificAgentId</arg>
-    </command>
-    where:
-    - "recipient_role_name" is the general role name of the recipient agent
-    - "recipient_agent_id" is the specific ID of the recipient agent, or "unknown" if not known
-    - "content" is the actual message text
-    - "message_type" is one of: TASK_ASSIGNMENT, TASK_RESULT, TASK_COMPLETED, CLARIFICATION, or ERROR
-    - "sender_agent_id" is the specific ID of the sender agent
-    Example:
-    <command name="SendMessageTo">
-      <arg name="recipient_role_name">worker</arg>
-      <arg name="recipient_agent_id">worker_001</arg>
-      <arg name="content">Please provide more details about the task output.</arg>
-      <arg name="message_type">CLARIFICATION</arg>
-      <arg name="sender_agent_id">coordinator_001</arg>
-    </command>
-    '''
+            message_to_send = InterAgentMessage.create_with_dynamic_message_type(
+                recipient_role_name=target_agent.context.config.role, 
+                recipient_agent_id=target_agent.agent_id, # Use the definitively resolved agent ID
+                content=content,
+                message_type=message_type,
+                sender_agent_id=sender_agent_id
+            )
+            
+            await target_agent.post_inter_agent_message(message_to_send)
+            success_msg = (f"Message successfully sent from '{sender_agent_id}' to agent "
+                           f"'{target_agent.agent_id}' (Role: '{target_agent.context.config.role}').")
+            logger.info(f"Tool '{self.get_name()}': {success_msg}")
+            return success_msg
+        except ValueError as ve: 
+            error_msg = f"Error creating message: {str(ve)}"
+            logger.error(f"Tool '{self.get_name()}': {error_msg}", exc_info=True)
+            return f"Error: {error_msg}"
+        except Exception as e:
+            error_msg = f"An unexpected error occurred while sending message: {str(e)}"
+            logger.error(f"Tool '{self.get_name()}': {error_msg}", exc_info=True)
+            return f"Error: {error_msg}"
+
+    # tool_usage_xml was defined directly here, this is now inherited from BaseTool
+    # BaseTool.tool_usage_xml() will use get_argument_schema() to generate it.
+    # If a custom XML format was desired that differs from the auto-generated one,
+    # then this method could be overridden. For now, assume auto-generated is fine.

autobyteus/agent/phases/__init__.py

@@ -0,0 +1,18 @@
+# file: autobyteus/autobyteus/agent/phases/__init__.py
+"""
+This package contains components for defining and describing agent operational phases
+and their transitions.
+"""
+from .phase_enum import AgentOperationalPhase
+from .transition_info import PhaseTransitionInfo
+from .transition_decorator import phase_transition
+from .discover import PhaseTransitionDiscoverer
+from .manager import AgentPhaseManager
+
+__all__ = [
+    "AgentOperationalPhase",
+    "PhaseTransitionInfo",
+    "phase_transition",
+    "PhaseTransitionDiscoverer",
+    "AgentPhaseManager",
+]