Deprecate DelegateTool in favor of TaskToolSet (#2668)

Co-authored-by: openhands <openhands@all-hands.dev>
Co-authored-by: enyst <engel.nyst@gmail.com>

Author: 3 people

openhands-tools/openhands/tools/delegate/definition.py

@@ -1,4 +1,9 @@
-"""Delegate tool definitions for OpenHands agents."""
+"""Delegate tool definitions for OpenHands agents.
+
+.. deprecated:: 1.16.0
+    DelegateTool is deprecated in favor of TaskToolSet. Use TaskToolSet for
+    sub-agent delegation. DelegateTool will be removed in version 1.23.0.
+"""
 
 import pathlib
 from collections.abc import Sequence
@@ -14,6 +19,7 @@
     ToolAnnotations,
     ToolDefinition,
 )
+from openhands.sdk.utils.deprecation import warn_deprecated
 
 
 if TYPE_CHECKING:
@@ -61,7 +67,12 @@ class DelegateObservation(Observation):
 
 
 class DelegateTool(ToolDefinition[DelegateAction, DelegateObservation]):
-    """A ToolDefinition subclass that automatically initializes a DelegateExecutor."""
+    """A ToolDefinition subclass that automatically initializes a DelegateExecutor.
+
+    .. deprecated:: 1.16.0
+        DelegateTool is deprecated in favor of TaskToolSet. Use TaskToolSet for
+        sub-agent delegation. DelegateTool will be removed in version 1.23.0.
+    """
 
     @classmethod
     def create(
@@ -72,6 +83,9 @@ def create(
     ) -> Sequence["DelegateTool"]:
         """Initialize DelegateTool with a DelegateExecutor.
 
+        .. deprecated:: 1.16.0
+            Use TaskToolSet instead. DelegateTool will be removed in version 1.23.0.
+
         Args:
             conv_state: Conversation state (used to get workspace location)
             max_children: Maximum number of concurrent sub-agents (default: 5)
@@ -84,6 +98,13 @@ def create(
         Returns:
             List containing a single delegate tool definition
         """
+        warn_deprecated(
+            "DelegateTool",
+            deprecated_in="1.16.0",
+            removed_in="1.23.0",
+            details="Use TaskToolSet instead for sub-agent delegation.",
+        )
+
         # Import here to avoid circular imports
         from openhands.sdk.subagent import get_factory_info
         from openhands.tools.delegate.impl import DelegateExecutor

tests/tools/delegate/test_delegation.py

@@ -2,9 +2,11 @@
 
 import json
 import uuid
+import warnings
 from pathlib import Path
 from unittest.mock import MagicMock, patch
 
+from deprecation import DeprecatedWarning
 from pydantic import SecretStr
 
 from openhands.sdk.agent.utils import fix_malformed_tool_arguments
@@ -21,7 +23,7 @@
     DelegateExecutor,
     DelegateObservation,
 )
-from openhands.tools.delegate.definition import DelegateAction
+from openhands.tools.delegate.definition import DelegateAction, DelegateTool
 from openhands.tools.preset import register_builtins_agents
 
 
@@ -547,3 +549,22 @@ def test_spawn_no_persistence_when_parent_has_none():
     sub_conv = executor._sub_agents["sub1"]
     # The sub-conversation should have no persistence_dir
     assert sub_conv._state.persistence_dir is None
+
+
+def test_delegate_tool_create_emits_deprecation_warning():
+    """DelegateTool.create() emits a deprecation warning."""
+    register_builtins_agents()
+
+    conv_state = MagicMock()
+    conv_state.workspace.working_dir = "/tmp"
+
+    with warnings.catch_warnings(record=True) as w:
+        warnings.simplefilter("always")
+        DelegateTool.create(conv_state)
+
+    deprecation_warnings = [
+        warning for warning in w if issubclass(warning.category, DeprecatedWarning)
+    ]
+    assert len(deprecation_warnings) == 1
+    assert "DelegateTool" in str(deprecation_warnings[0].message)
+    assert "TaskToolSet" in str(deprecation_warnings[0].message)