autobyteus 1.0.4__tar.gz → 1.0.5__tar.gz

{autobyteus-1.0.4 → autobyteus-1.0.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: autobyteus
-Version: 1.0.4
+Version: 1.0.5
 Summary: Multi-Agent framework
 Home-page: https://github.com/AutoByteus/autobyteus
 Author: Ryan Zheng

{autobyteus-1.0.4 → autobyteus-1.0.5}/autobyteus/agent/agent.py

@@ -223,7 +223,7 @@ class Agent(EventEmitter):
             
         external_tools_section = ""
         for i, tool in enumerate(self.tools):
-            external_tools_section += f"  {i + 1} {tool.tool_usage_xml()}\n\n"
+            external_tools_section += f"  {i + 1} {tool.tool_usage()}\n\n"
         return external_tools_section.strip()
 
     def on_task_completed(self, *args, **kwargs):

autobyteus-1.0.5/autobyteus/agent/factory/agent_factory.py

@@ -0,0 +1,94 @@
+# file: autobyteus/agent/factory/agent_factory.py
+import logging
+from autobyteus.agent.agent import Agent
+from autobyteus.agent.group.group_aware_agent import GroupAwareAgent
+from autobyteus.llm.llm_factory import LLMFactory
+from autobyteus.tools.factory.tool_factory import ToolFactory
+from autobyteus.prompt.prompt_builder import PromptBuilder
+from autobyteus.llm.models import LLMModel
+from typing import List, Union
+
+logger = logging.getLogger(__name__)
+
+class AgentFactory:
+    """
+    Factory class for creating different types of agents.
+
+    This factory simplifies the creation of Agent instances by encapsulating
+    the necessary dependencies and configurations.
+    """
+    def __init__(self,
+                 role: str,
+                 agent_type: str,
+                 tool_factory: ToolFactory,
+                 llm_factory: LLMFactory,
+                 prompt_builder: PromptBuilder, # Agent requires prompt_builder or initial_user_message
+                 llm_model: LLMModel,
+                 tool_names: List[str]):
+        """
+        Initializes the AgentFactory.
+
+        Args:
+            role: The role the created agents will fulfill.
+            agent_type: The type of agent to create ("standalone" or "group_aware").
+            tool_factory: A factory to create tool instances.
+            llm_factory: A factory to create LLM instances.
+            prompt_builder: The PromptBuilder instance to configure the agent's system prompt.
+            llm_model: The specific LLM model configuration to use.
+            tool_names: A list of tool names the agent should be equipped with.
+        """
+        self.role = role
+        self.agent_type = agent_type
+        self.tool_factory = tool_factory
+        self.llm_factory = llm_factory
+        self.prompt_builder = prompt_builder
+        self.llm_model = llm_model
+        self.tool_names = tool_names
+        logger.info(f"AgentFactory initialized for role '{role}' and type '{agent_type}'")
+
+    def create_agent(self, agent_id: str) -> Union[Agent, GroupAwareAgent]:
+        """
+        Creates an agent instance based on the factory's configuration.
+
+        Args:
+            agent_id: The unique identifier for the agent being created.
+
+        Returns:
+            An instance of Agent or GroupAwareAgent.
+
+        Raises:
+            ValueError: If the configured agent_type is unsupported.
+        """
+        logger.info(f"Creating agent with id '{agent_id}' for role '{self.role}' and type '{self.agent_type}'")
+        try:
+            tools = [self.tool_factory.create_tool(name) for name in self.tool_names]
+            logger.debug(f"Tools created for agent '{agent_id}': {[tool.get_name() for tool in tools]}")
+        except Exception as e:
+            logger.error(f"Error creating tools for agent '{agent_id}': {e}")
+            raise ValueError(f"Failed to create tools for agent {agent_id}: {e}") from e
+
+        try:
+            llm = self.llm_factory.create_llm(self.llm_model)
+            logger.debug(f"LLM instance created for agent '{agent_id}' using model '{self.llm_model.model_name}'")
+        except Exception as e:
+            logger.error(f"Error creating LLM for agent '{agent_id}': {e}")
+            raise ValueError(f"Failed to create LLM for agent {agent_id}: {e}") from e
+
+        agent_args = {
+            "agent_id": agent_id,
+            "role": self.role,
+            "prompt_builder": self.prompt_builder,
+            "llm": llm,
+            "tools": tools
+        }
+
+        if self.agent_type == "standalone":
+            logger.debug(f"Instantiating Agent with args: {agent_args}")
+            return Agent(**agent_args)
+        elif self.agent_type == "group_aware":
+            logger.debug(f"Instantiating GroupAwareAgent with args: {agent_args}")
+            return GroupAwareAgent(**agent_args)
+        else:
+            logger.error(f"Unsupported agent type specified in factory: {self.agent_type}")
+            raise ValueError(f"Unsupported agent type: {self.agent_type}")
+

{autobyteus-1.0.4 → autobyteus-1.0.5}/autobyteus/agent/message/send_message_to.py

@@ -18,9 +18,6 @@ class SendMessageTo(BaseTool):
         except ValueError as e:
             return f"Error: {str(e)}"
     
-    def tool_usage(self) -> str:
-        return self.tool_usage_xml()
-
     def tool_usage_xml(self) -> str:
         return '''SendMessageTo: Sends a message to another agent in the group. Usage:
     <command name="SendMessageTo">

autobyteus-1.0.5/autobyteus/agent/registry/__init__.py

@@ -0,0 +1,11 @@
+# file: autobyteus/autobyteus/agent/registry/__init__.py
+from .agent_definition import AgentDefinition
+from .agent_registry import AgentRegistry, default_agent_registry
+from autobyteus.agent.factory.agent_factory import AgentFactory
+
+__all__ = [
+    "AgentDefinition",
+    "AgentRegistry",
+    "default_agent_registry",
+    "AgentFactory"
+]

autobyteus-1.0.5/autobyteus/agent/registry/agent_definition.py

@@ -0,0 +1,94 @@
+import logging
+from typing import Dict, List, Any, Optional
+
+logger = logging.getLogger(__name__)
+
+class AgentDefinition:
+    """
+    Represents the static definition of an agent, containing its role, description,
+    tools, optional system prompt, and optional initial user message.
+    """
+    def __init__(self,
+                 role: str,
+                 description: str,
+                 tools: List[str],
+                 system_prompt: Optional[str] = None,
+                 initial_user_message: Optional[str] = None):
+        """
+        Initializes the AgentDefinition.
+
+        Args:
+            role: The unique role identifier of the agent (e.g., 'coordinator', 'worker').
+            description: A human-readable description of the agent's purpose.
+            tools: A list of tool names the agent can use.
+            system_prompt: An optional system prompt to configure the LLM's behavior.
+            initial_user_message: An optional initial user message to start the agent's conversation.
+
+        Raises:
+            ValueError: If role, description, or tools are invalid, or if system_prompt or
+                        initial_user_message are not strings when provided.
+        """
+        if not role or not isinstance(role, str):
+            raise ValueError("AgentDefinition requires a non-empty string 'role'.")
+        if not description or not isinstance(description, str):
+            raise ValueError(f"AgentDefinition '{role}' requires a non-empty string 'description'.")
+        if not isinstance(tools, list) or not all(isinstance(t, str) and t for t in tools):
+            raise ValueError(f"AgentDefinition '{role}' requires a non-empty list of tool name strings.")
+        if system_prompt is not None and not isinstance(system_prompt, str):
+            raise ValueError(f"AgentDefinition '{role}' system_prompt must be a string or None.")
+        if initial_user_message is not None and not isinstance(initial_user_message, str):
+            raise ValueError(f"AgentDefinition '{role}' initial_user_message must be a string or None.")
+
+        self._role = role
+        self._description = description
+        self._tools = tools
+        self._system_prompt = system_prompt
+        self._initial_user_message = initial_user_message
+
+        logger.debug(f"AgentDefinition created for role '{self.role}'.")
+
+    @property
+    def role(self) -> str:
+        """The unique role identifier of the agent."""
+        return self._role
+
+    @property
+    def description(self) -> str:
+        """The human-readable description of the agent's purpose."""
+        return self._description
+
+    @property
+    def tools(self) -> List[str]:
+        """The list of tool names the agent can use."""
+        return self._tools
+
+    @property
+    def system_prompt(self) -> Optional[str]:
+        """The optional system prompt for the agent."""
+        return self._system_prompt
+
+    @property
+    def initial_user_message(self) -> Optional[str]:
+        """The optional initial user message for the agent."""
+        return self._initial_user_message
+
+    def __repr__(self) -> str:
+        """Provides a developer-friendly string representation."""
+        desc_repr = self.description
+        if len(desc_repr) > 70:
+            desc_repr = desc_repr[:67] + "..."
+        # Remove newlines/tabs for cleaner logging
+        desc_repr = desc_repr.replace('\n', '\\n').replace('\t', '\\t')
+        return (f"AgentDefinition(role='{self.role}', description='{desc_repr}', "
+                f"tools={self.tools}, system_prompt='{self.system_prompt}', "
+                f"initial_user_message='{self.initial_user_message}')")
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Returns a dictionary representation of the agent definition."""
+        return {
+            "role": self.role,
+            "description": self.description,
+            "tools": self.tools,
+            "system_prompt": self.system_prompt,
+            "initial_user_message": self.initial_user_message
+        }

autobyteus-1.0.5/autobyteus/agent/registry/agent_registry.py

@@ -0,0 +1,114 @@
+# file: autobyteus/autobyteus/agent/registry/agent_registry.py
+import logging
+from typing import Dict, List, Optional
+
+from autobyteus.utils.singleton import SingletonMeta
+from autobyteus.agent.factory.agent_factory import AgentFactory
+from .agent_definition import AgentDefinition
+
+logger = logging.getLogger(__name__)
+
+class AgentRegistry(metaclass=SingletonMeta):
+    """
+    Manages AgentDefinitions (role, description, tools, initial_user_message, agent_class),
+    populated exclusively via programmatic registration. Uses AgentFactory to create agent instances.
+    """
+    _definitions: Dict[str, AgentDefinition] = {}
+
+    def __init__(self, agent_factory: AgentFactory):
+        """
+        Initializes the AgentRegistry with an AgentFactory.
+
+        Args:
+            agent_factory: The AgentFactory instance used to create agent instances.
+        """
+        self.agent_factory = agent_factory
+        logger.info("AgentRegistry initialized with AgentFactory.")
+
+    def register_agent(self, definition: AgentDefinition):
+        """
+        Registers an agent definition (role, description, tools, initial_user_message, agent_class) programmatically.
+
+        Args:
+            definition: The AgentDefinition object to register.
+
+        Raises:
+            ValueError: If the definition is invalid. Overwrites existing definitions with the same role.
+        """
+        if not isinstance(definition, AgentDefinition):
+            raise ValueError("Attempted to register an object that is not an AgentDefinition.")
+
+        role = definition.role
+        if role in self._definitions:
+            logger.warning(f"Overwriting existing agent definition for role: '{role}'")
+        AgentRegistry._definitions[role] = definition
+        logger.info(f"Successfully registered agent definition: '{role}'")
+
+    def get_agent_definition(self, role: str) -> Optional[AgentDefinition]:
+        """
+        Retrieves the definition for a specific agent role.
+
+        Args:
+            role: The unique role of the agent definition to retrieve.
+
+        Returns:
+            The AgentDefinition object if found, otherwise None.
+        """
+        definition = self._definitions.get(role)
+        if not definition:
+            logger.debug(f"Agent definition not found for role: '{role}'")
+        return definition
+
+    def create_agent(self, role: str, agent_id: str):
+        """
+        Creates an agent instance using the AgentFactory based on the agent definition.
+
+        Args:
+            role: The role of the agent to create.
+            agent_id: The unique identifier for the agent instance.
+
+        Returns:
+            The agent instance if the definition exists, otherwise None.
+
+        Raises:
+            ValueError: If the agent definition is not found.
+        """
+        definition = self.get_agent_definition(role)
+        if not definition:
+            logger.error(f"Cannot create agent: No definition found for role '{role}'")
+            raise ValueError(f"No agent definition found for role '{role}'")
+        
+        logger.info(f"Creating agent instance for role '{role}' with id '{agent_id}' using AgentFactory")
+        return self.agent_factory.create_agent(agent_id)
+
+    def list_agents(self) -> List[AgentDefinition]:
+        """
+        Returns a list of all registered agent definitions.
+
+        Returns:
+            A list of AgentDefinition objects.
+        """
+        return list(self._definitions.values())
+
+    def list_agent_roles(self) -> List[str]:
+        """
+        Returns a list of the roles of all registered agents.
+
+        Returns:
+            A list of agent role strings.
+        """
+        return list(self._definitions.keys())
+
+    def get_all_definitions(self) -> Dict[str, AgentDefinition]:
+        """Returns the internal dictionary of definitions."""
+        return dict(AgentRegistry._definitions)
+
+default_agent_registry = AgentRegistry(agent_factory=AgentFactory(
+    role="default",
+    agent_type="group_aware",
+    tool_factory=ToolFactory(),
+    llm_factory=LLMFactory(),
+    prompt_builder=PromptBuilder(),
+    llm_model=LLMModel(),
+    tool_names=[]
+))

autobyteus-1.0.5/autobyteus/agent/remote_agent.py

@@ -0,0 +1,9 @@
+# file: autobyteus/autobyteus/agent/remote_agent.py
+from autobyteus.agent.agent import Agent
+
+class RemoteAgent(Agent):
+    """
+    A placeholder class for remote agents that will interact with external systems
+    (e.g., via MCP or HTTP protocols). To be implemented in the future.
+    """
+    pass

{autobyteus-1.0.4 → autobyteus-1.0.5}/autobyteus/llm/autobyteus_provider.py

@@ -56,12 +56,13 @@ class AutobyteusModelProvider:
                         value=model_info["value"],
                         provider=LLMProvider(model_info["provider"]),  # Convert string to enum
                         llm_class=AutobyteusLLM,
+                        canonical_name=model_info["canonical_name"],  # Add canonical_name
                         default_config=llm_config
                     )
                     
                     LLMFactory.register_model(llm_model)
                     registered_count += 1
-                    logger.debug(f"Registered model: {model_info['name']}")
+                    logger.debug(f"Registered model: {model_info['name']} with canonical name: {model_info['canonical_name']}")
                     
                 except Exception as e:
                     logger.error(f"Model registration failed: {str(e)}")

{autobyteus-1.0.4 → autobyteus-1.0.5}/autobyteus/llm/llm_factory.py

@@ -98,6 +98,7 @@ class LLMFactory:
                 value="gpt-4o",
                 provider=LLMProvider.OPENAI,
                 llm_class=OpenAILLM,
+                canonical_name="gpt-4o",
                 default_config=LLMConfig(
                     rate_limit=40, 
                     token_limit=8192,
@@ -105,38 +106,32 @@ class LLMFactory:
                 )
             ),
             LLMModel(
-                name="o1_API",
-                value="o1",
+                name="o3_API",
+                value="o3",
                 provider=LLMProvider.OPENAI,
                 llm_class=OpenAILLM,
+                canonical_name="o3",
                 default_config=LLMConfig(
                     pricing_config=TokenPricingConfig(15.00, 60.00)
                 )
             ),
             LLMModel(
-                name="o1_MINI_API",
-                value="o3-mini",
+                name="o4_MINI_API",
+                value="o4-mini",
                 provider=LLMProvider.OPENAI,
                 llm_class=OpenAILLM,
+                canonical_name="o4-mini",
                 default_config=LLMConfig(
                     pricing_config=TokenPricingConfig(1.0, 4.00)
                 )
             ),
-            LLMModel(
-                name="GPT_3_5_TURBO_API",
-                value="gpt-3.5-turbo",
-                provider=LLMProvider.OPENAI,
-                llm_class=OpenAILLM,
-                default_config=LLMConfig(
-                    pricing_config=TokenPricingConfig(1.50, 2.00)
-                )
-            ),
             # MISTRAL Provider Models
             LLMModel(
                 name="MISTRAL_LARGE_API",
                 value="mistral-large-latest",
                 provider=LLMProvider.MISTRAL,
                 llm_class=MistralLLM,
+                canonical_name="mistral-large",
                 default_config=LLMConfig(
                     pricing_config=TokenPricingConfig(2.00, 6.00)
                 )
@@ -147,6 +142,7 @@ class LLMFactory:
                 value="claude-3-7-sonnet-20250219",
                 provider=LLMProvider.ANTHROPIC,
                 llm_class=ClaudeLLM,
+                canonical_name="claude-3.7",
                 default_config=LLMConfig(
                     pricing_config=TokenPricingConfig(3.00, 15.00)
                 )
@@ -156,6 +152,7 @@ class LLMFactory:
                 value="anthropic.claude-3-7-sonnet-20250219-v1:0",
                 provider=LLMProvider.ANTHROPIC,
                 llm_class=ClaudeLLM,
+                canonical_name="claude-3.7",
                 default_config=LLMConfig(
                     pricing_config=TokenPricingConfig(3.00, 15.00)
                 )
@@ -166,6 +163,7 @@ class LLMFactory:
                 value="deepseek-chat",
                 provider=LLMProvider.DEEPSEEK,
                 llm_class=DeepSeekLLM,
+                canonical_name="deepseek-chat",
                 default_config=LLMConfig(
                     rate_limit=60,
                     token_limit=8000,
@@ -178,6 +176,7 @@ class LLMFactory:
                 value="deepseek-reasoner",
                 provider=LLMProvider.DEEPSEEK,
                 llm_class=DeepSeekLLM,
+                canonical_name="deepseek-reasoner",
                 default_config=LLMConfig(
                     rate_limit=60,
                     token_limit=8000,
@@ -190,6 +189,7 @@ class LLMFactory:
                 value="gemini-1-5-pro",
                 provider=LLMProvider.GEMINI,
                 llm_class=OpenAILLM,
+                canonical_name="gemini-1.5-pro",
                 default_config=LLMConfig(
                     pricing_config=TokenPricingConfig(1.25, 5.00)
                 )
@@ -199,6 +199,7 @@ class LLMFactory:
                 value="gemini-1-5-flash",
                 provider=LLMProvider.GEMINI,
                 llm_class=OpenAILLM,
+                canonical_name="gemini-1.5-flash",
                 default_config=LLMConfig(
                     pricing_config=TokenPricingConfig(0.075, 0.30)
                 )
@@ -209,6 +210,7 @@ class LLMFactory:
                 value="grok-2-1212",
                 provider=LLMProvider.GROK,
                 llm_class=GrokLLM,
+                canonical_name="grok-2",
                 default_config=LLMConfig(
                     rate_limit=60,
                     token_limit=8000,
@@ -290,3 +292,21 @@ class LLMFactory:
         """
         LLMFactory.ensure_initialized()
         return LLMFactory._models_by_provider.get(provider, [])
+
+    @staticmethod
+    def get_canonical_name(model_name: str) -> Optional[str]:
+        """
+        Get the canonical name for a model by its name.
+        
+        Args:
+            model_name (str): The model name (e.g., "GPT_4o_API")
+            
+        Returns:
+            Optional[str]: The canonical name if found, None otherwise
+        """
+        LLMFactory.ensure_initialized()
+        for models in LLMFactory._models_by_provider.values():
+            for model_instance in models:
+                if model_instance.name == model_name:
+                    return model_instance.canonical_name
+        return None

{autobyteus-1.0.4 → autobyteus-1.0.5}/autobyteus/llm/models.py

@@ -13,6 +13,7 @@ class LLMModel:
     Represents a single model's metadata:
       - name (str): A human-readable label, e.g. "GPT-4 Official" 
       - value (str): A unique identifier used in code or APIs, e.g. "gpt-4o"
+      - canonical_name (str): A shorter, standardized reference name for prompts, e.g. "gpt-4o" or "claude-3.7"
       - provider (LLMProvider): The provider enum 
       - llm_class (Type[BaseLLM]): Which Python class to instantiate 
       - default_config (LLMConfig): Default configuration (token limit, etc.)
@@ -26,6 +27,7 @@ class LLMModel:
         value: str,
         provider: LLMProvider,
         llm_class: Type["BaseLLM"],
+        canonical_name: str,
         default_config: Optional[LLMConfig] = None
     ):
         # Validate name doesn't already exist as a class attribute
@@ -36,6 +38,7 @@ class LLMModel:
             
         self._name = name
         self._value = value
+        self._canonical_name = canonical_name
         self.provider = provider
         self.llm_class = llm_class
         self.default_config = default_config if default_config else LLMConfig()
@@ -58,6 +61,14 @@ class LLMModel:
         """
         return self._value
 
+    @property
+    def canonical_name(self) -> str:
+        """
+        A standardized, shorter reference name for this model.
+        Useful for prompt engineering and cross-referencing similar models.
+        """
+        return self._canonical_name
+
     def create_llm(self, custom_config: Optional[LLMConfig] = None) -> "BaseLLM":
         """
         Instantiate the LLM class for this model, applying
@@ -69,5 +80,6 @@ class LLMModel:
     def __repr__(self):
         return (
             f"LLMModel(name='{self._name}', value='{self._value}', "
+            f"canonical_name='{self._canonical_name}', "
             f"provider='{self.provider.name}', llm_class='{self.llm_class.__name__}')"
         )

{autobyteus-1.0.4 → autobyteus-1.0.5}/autobyteus/llm/ollama_provider.py

@@ -79,6 +79,7 @@ class OllamaModelProvider:
                         value=model_name,
                         provider=LLMProvider.OLLAMA,
                         llm_class=OllamaLLM,
+                        canonical_name=model_name,  # Use model_name as the canonical_name
                         default_config=LLMConfig(
                             rate_limit=60,
                             token_limit=8192,

{autobyteus-1.0.4 → autobyteus-1.0.5}/autobyteus/tools/ask_user_input.py

@@ -12,27 +12,16 @@ class AskUserInput(BaseTool):
         super().__init__()
         self.logger = logging.getLogger(__name__)
 
-    def tool_usage(self):
+    @classmethod
+    def tool_usage_xml(cls):
         """
-        Return a string describing the usage of the AskUserInput tool.
+        Return an XML string describing the usage of the AskUserInput tool.
+
+        Returns:
+            str: An XML description of how to use the AskUserInput tool.
         """
-        return '''AskUserInput: Requests input from the user based on LLM's prompt. 
-        Usage: <<<AskUserInput(request="[Your request here]")>>>
-        
-        Examples:
-        1. When needing to request user for search input:
-           <<<AskUserInput(request="What would you like to search for?")>>>
-        
-        2. When needing to request user for form input:
-           <<<AskUserInput(request="Please enter your full name:")>>>
-        
-        3. When needing to request user for a choice:
-           <<<AskUserInput(request="Select an option (1, 2, or 3):")>>>
-        '''
-
-    def tool_usage_xml(self):
         return '''AskUserInput: Requests input from the user based on a given context or prompt. 
-    <command name="AskUserInput"
+    <command name="AskUserInput">
     <arg name="request">[Your request here]</arg>
     </command>
 
@@ -90,4 +79,4 @@ class AskUserInput(BaseTool):
         except Exception as e:
             error_message = f"An error occurred while getting user input: {str(e)}"
             self.logger.error(error_message)
-            return f"[Error: {error_message}]"
+            return f"[Error: {error_message}]"

autobyteus-1.0.5/autobyteus/tools/base_tool.py

@@ -0,0 +1,77 @@
+# File: autobyteus/tools/base_tool.py
+
+import logging
+from abc import ABC, abstractmethod
+from typing import Optional, Any
+
+from autobyteus.events.event_emitter import EventEmitter
+from autobyteus.events.event_types import EventType
+
+from .tool_meta import ToolMeta
+
+logger = logging.getLogger('autobyteus')
+
+class BaseTool(ABC, EventEmitter, metaclass=ToolMeta):
+    """
+    Abstract base class for all tools, with auto-registration via ToolMeta.
+
+    Subclasses inherit a default `get_name` (the class name) and MUST implement
+    the abstract class method `tool_usage_xml`, and the abstract instance
+    method `_execute`.
+    """
+    def __init__(self):
+        super().__init__()
+        self.agent_id: Optional[str] = None
+        logger.debug(f"BaseTool instance initializing for potential class {self.__class__.__name__}")
+
+    @classmethod
+    def get_name(cls) -> str:
+        """
+        Return the name of the tool. Defaults to the class name.
+        Can be overridden by child classes if a different registration name is needed.
+        """
+        return cls.__name__
+    
+    @classmethod
+    def tool_usage_xml(cls) -> str:
+        """
+        Return the static usage description string for the tool in XML format.
+        Must be implemented by subclasses.
+        """
+        pass
+
+    def set_agent_id(self, agent_id: str):
+        """Sets the ID of the agent using this tool instance."""
+        self.agent_id = agent_id
+        logger.debug(f"Agent ID '{agent_id}' set for tool instance '{self.__class__.get_name()}'")
+
+    async def execute(self, **kwargs):
+        """
+        Execute the tool's main functionality by calling _execute.
+        Argument validation must be handled within _execute.
+        """
+        tool_name = self.__class__.get_name()
+        logger.info(f"Executing tool '{tool_name}' for agent '{self.agent_id}' with args: {kwargs}")
+        try:
+            result = await self._execute(**kwargs)
+            logger.info(f"Tool '{tool_name}' execution completed successfully.")
+            return result
+        except Exception as e:
+            logger.error(f"Tool '{tool_name}' execution failed: {str(e)}", exc_info=True)
+            return f"Error executing tool '{tool_name}': {str(e)}"
+
+    @abstractmethod
+    async def _execute(self, **kwargs) -> Any:
+        """
+        Implement the actual execution logic in subclasses.
+        MUST handle own argument validation.
+        """
+        pass
+
+    @classmethod
+    def tool_usage(cls) -> str:
+        """
+        Returns the tool's static XML usage description by calling the class method tool_usage_xml.
+        This is a convenience class method.
+        """
+        return cls.tool_usage_xml()