Refactor ToolDefinition architecture to use subclass pattern for all tools

examples/01_standalone_sdk/02_custom_tools.py

@@ -16,7 +16,7 @@
     LLMConvertibleEvent,
     Observation,
     TextContent,
-    ToolDefinition,
+    ToolBase,
     get_logger,
 )
 from openhands.sdk.tool import (
@@ -131,14 +131,14 @@ def __call__(self, action: GrepAction, conversation=None) -> GrepObservation:  #
 cwd = os.getcwd()
 
 
-def _make_bash_and_grep_tools(conv_state) -> list[ToolDefinition]:
+def _make_bash_and_grep_tools(conv_state) -> list[ToolBase]:
     """Create execute_bash and custom grep tools sharing one executor."""
 
     bash_executor = BashExecutor(working_dir=conv_state.workspace.working_dir)
     bash_tool = execute_bash_tool.set_executor(executor=bash_executor)
 
     grep_executor = GrepExecutor(bash_executor)
-    grep_tool = ToolDefinition(
+    grep_tool = ToolBase(
         name="grep",
         description=_GREP_DESCRIPTION,
         action_type=GrepAction,

openhands-sdk/openhands/sdk/__init__.py

@@ -38,7 +38,6 @@
     Observation,
     Tool,
     ToolBase,
-    ToolDefinition,
     list_registered_tools,
     register_tool,
     resolve_tool,
@@ -66,7 +65,6 @@
     "ThinkingBlock",
     "RedactedThinkingBlock",
     "Tool",
-    "ToolDefinition",
     "ToolBase",
     "AgentBase",
     "Agent",

openhands-sdk/openhands/sdk/agent/agent.py

@@ -34,7 +34,6 @@
 from openhands.sdk.security.llm_analyzer import LLMSecurityAnalyzer
 from openhands.sdk.tool import (
     Action,
-    FinishTool,
     Observation,
 )
 from openhands.sdk.tool.builtins import FinishAction, ThinkAction
@@ -418,6 +417,6 @@ def _execute_action_event(
         on_event(obs_event)
 
         # Set conversation state
-        if tool.name == FinishTool.name:
+        if tool.name == "finish":
             state.agent_status = AgentExecutionStatus.FINISHED
         return obs_event

openhands-sdk/openhands/sdk/agent/base.py

@@ -15,7 +15,7 @@
 from openhands.sdk.logger import get_logger
 from openhands.sdk.mcp import create_mcp_tools
 from openhands.sdk.security.llm_analyzer import LLMSecurityAnalyzer
-from openhands.sdk.tool import BUILT_IN_TOOLS, Tool, ToolDefinition, resolve_tool
+from openhands.sdk.tool import BUILT_IN_TOOLS, Tool, ToolBase, resolve_tool
 from openhands.sdk.utils.models import DiscriminatedUnionMixin
 from openhands.sdk.utils.pydantic_diff import pretty_pydantic_diff
 
@@ -142,7 +142,7 @@ class AgentBase(DiscriminatedUnionMixin, ABC):
     )
 
     # Runtime materialized tools; private and non-serializable
-    _tools: dict[str, ToolDefinition] = PrivateAttr(default_factory=dict)
+    _tools: dict[str, ToolBase] = PrivateAttr(default_factory=dict)
 
     @property
     def prompt_dir(self) -> str:
@@ -199,7 +199,7 @@ def _initialize(self, state: "ConversationState"):
             logger.warning("Agent already initialized; skipping re-initialization.")
             return
 
-        tools: list[ToolDefinition] = []
+        tools: list[ToolBase] = []
         for tool_spec in self.tools:
             tools.extend(resolve_tool(tool_spec, state))
 
@@ -220,13 +220,15 @@ def _initialize(self, state: "ConversationState"):
             )
 
         # Always include built-in tools; not subject to filtering
-        tools.extend(BUILT_IN_TOOLS)
+        # Instantiate built-in tools using their .create() method
+        for tool_class in BUILT_IN_TOOLS:
+            tools.extend(tool_class.create(state))
 
         # Check tool types
         for tool in tools:
-            if not isinstance(tool, ToolDefinition):
+            if not isinstance(tool, ToolBase):
                 raise ValueError(
-                    f"Tool {tool} is not an instance of 'ToolDefinition'. "
+                    f"Tool {tool} is not an instance of 'ToolBase'. "
                     f"Got type: {type(tool)}"
                 )
 
@@ -405,7 +407,7 @@ def _walk(obj: object) -> Iterable[LLM]:
         yield from _walk(self)
 
     @property
-    def tools_map(self) -> dict[str, ToolDefinition]:
+    def tools_map(self) -> dict[str, ToolBase]:
         """Get the initialized tools map.
         Raises:
             RuntimeError: If the agent has not been initialized.

openhands-sdk/openhands/sdk/mcp/tool.py

@@ -20,7 +20,7 @@
     Action,
     Observation,
     ToolAnnotations,
-    ToolDefinition,
+    ToolBase,
     ToolExecutor,
 )
 from openhands.sdk.tool.schema import Schema
@@ -114,7 +114,7 @@ def _create_mcp_action_type(action_type: mcp.types.Tool) -> type[Schema]:
     return mcp_action_type
 
 
-class MCPToolDefinition(ToolDefinition[MCPToolAction, MCPToolObservation]):
+class MCPToolDefinition(ToolBase[MCPToolAction, MCPToolObservation]):
     """MCP Tool that wraps an MCP client and provides tool functionality."""
 
     mcp_tool: mcp.types.Tool = Field(description="The MCP tool definition.")

openhands-sdk/openhands/sdk/tool/__init__.py

@@ -15,14 +15,12 @@
     ExecutableTool,
     ToolAnnotations,
     ToolBase,
-    ToolDefinition,
     ToolExecutor,
 )
 
 
 __all__ = [
     "Tool",
-    "ToolDefinition",
     "ToolBase",
     "ToolAnnotations",
     "ToolExecutor",

openhands-sdk/openhands/sdk/tool/builtins/finish.py

@@ -1,5 +1,5 @@
 from collections.abc import Sequence
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Self
 
 from pydantic import Field
 from rich.text import Text
@@ -9,13 +9,14 @@
     Action,
     Observation,
     ToolAnnotations,
-    ToolDefinition,
+    ToolBase,
     ToolExecutor,
 )
 
 
 if TYPE_CHECKING:
     from openhands.sdk.conversation.base import BaseConversation
+    from openhands.sdk.conversation.state import ConversationState
 
 
 class FinishAction(Action):
@@ -67,17 +68,42 @@ def __call__(
         return FinishObservation(message=action.message)
 
 
-FinishTool = ToolDefinition(
-    name="finish",
-    action_type=FinishAction,
-    observation_type=FinishObservation,
-    description=TOOL_DESCRIPTION,
-    executor=FinishExecutor(),
-    annotations=ToolAnnotations(
-        title="finish",
-        readOnlyHint=True,
-        destructiveHint=False,
-        idempotentHint=True,
-        openWorldHint=False,
-    ),
-)
+class FinishTool(ToolBase[FinishAction, FinishObservation]):
+    """Tool for signaling the completion of a task or conversation."""
+
+    @classmethod
+    def create(
+        cls,
+        conv_state: "ConversationState | None" = None,  # noqa: ARG003
+        **params,
+    ) -> Sequence[Self]:
+        """Create FinishTool instance.
+
+        Args:
+            conv_state: Optional conversation state (not used by FinishTool).
+            **params: Additional parameters (none supported).
+
+        Returns:
+            A sequence containing a single FinishTool instance.
+
+        Raises:
+            ValueError: If any parameters are provided.
+        """
+        if params:
+            raise ValueError("FinishTool doesn't accept parameters")
+        return [
+            cls(
+                name="finish",
+                action_type=FinishAction,
+                observation_type=FinishObservation,
+                description=TOOL_DESCRIPTION,
+                executor=FinishExecutor(),
+                annotations=ToolAnnotations(
+                    title="finish",
+                    readOnlyHint=True,
+                    destructiveHint=False,
+                    idempotentHint=True,
+                    openWorldHint=False,
+                ),
+            )
+        ]

openhands-sdk/openhands/sdk/tool/builtins/think.py

@@ -1,5 +1,5 @@
 from collections.abc import Sequence
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Self
 
 from pydantic import Field
 from rich.text import Text
@@ -9,13 +9,14 @@
     Action,
     Observation,
     ToolAnnotations,
-    ToolDefinition,
+    ToolBase,
     ToolExecutor,
 )
 
 
 if TYPE_CHECKING:
     from openhands.sdk.conversation.base import BaseConversation
+    from openhands.sdk.conversation.state import ConversationState
 
 
 class ThinkAction(Action):
@@ -83,16 +84,41 @@ def __call__(
         return ThinkObservation()
 
 
-ThinkTool = ToolDefinition(
-    name="think",
-    description=THINK_DESCRIPTION,
-    action_type=ThinkAction,
-    observation_type=ThinkObservation,
-    executor=ThinkExecutor(),
-    annotations=ToolAnnotations(
-        readOnlyHint=True,
-        destructiveHint=False,
-        idempotentHint=True,
-        openWorldHint=False,
-    ),
-)
+class ThinkTool(ToolBase[ThinkAction, ThinkObservation]):
+    """Tool for logging thoughts without making changes."""
+
+    @classmethod
+    def create(
+        cls,
+        conv_state: "ConversationState | None" = None,  # noqa: ARG003
+        **params,
+    ) -> Sequence[Self]:
+        """Create ThinkTool instance.
+
+        Args:
+            conv_state: Optional conversation state (not used by ThinkTool).
+            **params: Additional parameters (none supported).
+
+        Returns:
+            A sequence containing a single ThinkTool instance.
+
+        Raises:
+            ValueError: If any parameters are provided.
+        """
+        if params:
+            raise ValueError("ThinkTool doesn't accept parameters")
+        return [
+            cls(
+                name="think",
+                description=THINK_DESCRIPTION,
+                action_type=ThinkAction,
+                observation_type=ThinkObservation,
+                executor=ThinkExecutor(),
+                annotations=ToolAnnotations(
+                    readOnlyHint=True,
+                    destructiveHint=False,
+                    idempotentHint=True,
+                    openWorldHint=False,
+                ),
+            )
+        ]