fix: Use explicit mapping for include_default_tools deserialization

Replace ToolDefinition.resolve_kind() with an explicit BUILT_IN_TOOL_CLASSES
mapping for deserializing include_default_tools. This is more reliable as
resolve_kind() depends on subclass discovery which may fail if classes
haven't been imported.

Also add comprehensive tests for include_default_tools serialization and
deserialization to ensure round-trip works correctly.

Co-authored-by: openhands <[email protected]>

Author: openhands-agent

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

@@ -21,10 +21,26 @@
 from openhands.sdk.llm.utils.model_prompt_spec import get_model_prompt_spec
 from openhands.sdk.logger import get_logger
 from openhands.sdk.mcp import create_mcp_tools
-from openhands.sdk.tool import BUILT_IN_TOOLS, Tool, ToolDefinition, resolve_tool
+from openhands.sdk.tool import (
+    BUILT_IN_TOOLS,
+    FinishTool,
+    ThinkTool,
+    Tool,
+    ToolDefinition,
+    resolve_tool,
+)
 from openhands.sdk.utils.models import DiscriminatedUnionMixin
 
 
+# Explicit mapping of built-in tool class names to their classes.
+# This is more reliable than using resolve_kind() which depends on
+# subclass discovery and may fail if classes haven't been imported.
+BUILT_IN_TOOL_CLASSES: dict[str, type[ToolDefinition]] = {
+    "FinishTool": FinishTool,
+    "ThinkTool": ThinkTool,
+}
+
+
 if TYPE_CHECKING:
     from openhands.sdk.conversation import ConversationState, LocalConversation
     from openhands.sdk.conversation.types import (
@@ -176,7 +192,7 @@ class AgentBase(DiscriminatedUnionMixin, ABC):
     @field_validator("include_default_tools", mode="before")
     @classmethod
     def _val_include_default_tools(cls, v: Any) -> list[str]:
-        """Convert tool classes to their class names if needed.
+        """Convert tool classes to their class names and validate them.
 
         Accepts both strings and tool classes for backward compatibility.
         """
@@ -185,12 +201,19 @@ def _val_include_default_tools(cls, v: Any) -> list[str]:
         result: list[str] = []
         for item in v:
             if isinstance(item, str):
-                result.append(item)
+                name = item
             elif isinstance(item, type):
-                # It's a tool class
-                result.append(item.__name__)
+                # It's a tool class - convert to name
+                name = item.__name__
             else:
                 raise ValueError(f"Invalid item type: {type(item)}")
+            # Validate that the tool name is a known built-in tool
+            if name not in BUILT_IN_TOOL_CLASSES:
+                raise ValueError(
+                    f"Unknown built-in tool class: '{name}'. "
+                    f"Expected one of: {list(BUILT_IN_TOOL_CLASSES.keys())}"
+                )
+            result.append(name)
         return result
 
     @property
@@ -293,9 +316,14 @@ def _initialize(self, state: "ConversationState"):
             )
 
         # Include default tools from include_default_tools; not subject to regex
-        # filtering. Resolve tool class names and instantiate using their .create()
+        # filtering. Use explicit mapping to resolve tool class names.
         for tool_name in self.include_default_tools:
-            tool_class = ToolDefinition.resolve_kind(tool_name)
+            tool_class = BUILT_IN_TOOL_CLASSES.get(tool_name)
+            if tool_class is None:
+                raise ValueError(
+                    f"Unknown built-in tool class: '{tool_name}'. "
+                    f"Expected one of: {list(BUILT_IN_TOOL_CLASSES.keys())}"
+                )
             tool_instances = tool_class.create(state)
             tools.extend(tool_instances)
 

tests/sdk/agent/test_agent_serialization.py

@@ -13,6 +13,7 @@
 from openhands.sdk.llm import LLM
 from openhands.sdk.mcp.client import MCPClient
 from openhands.sdk.mcp.tool import MCPToolDefinition
+from openhands.sdk.tool import FinishTool
 from openhands.sdk.tool.tool import ToolDefinition
 from openhands.sdk.utils.models import OpenHandsModel
 
@@ -221,3 +222,140 @@ class TestModel(BaseModel):
     assert isinstance(deserialized_model.agent, Agent)
     assert deserialized_model.agent.model_dump() == agent.model_dump()
     assert deserialized_model.model_dump() == model.model_dump()
+
+
+def test_include_default_tools_serialization_default() -> None:
+    """Test that include_default_tools serializes correctly with default value."""
+    llm = LLM(model="test-model", usage_id="test-llm")
+    agent = Agent(llm=llm, tools=[])
+
+    # Serialize to JSON
+    agent_json = agent.model_dump_json()
+    agent_dict = json.loads(agent_json)
+
+    # Default should include both FinishTool and ThinkTool as strings
+    assert "include_default_tools" in agent_dict
+    assert set(agent_dict["include_default_tools"]) == {"FinishTool", "ThinkTool"}
+
+
+def test_include_default_tools_serialization_empty() -> None:
+    """Test that include_default_tools serializes correctly when empty."""
+    llm = LLM(model="test-model", usage_id="test-llm")
+    agent = Agent(llm=llm, tools=[], include_default_tools=[])
+
+    # Serialize to JSON
+    agent_json = agent.model_dump_json()
+    agent_dict = json.loads(agent_json)
+
+    # Should be empty list
+    assert agent_dict["include_default_tools"] == []
+
+
+def test_include_default_tools_serialization_partial() -> None:
+    """Test that include_default_tools serializes correctly with partial list."""
+    llm = LLM(model="test-model", usage_id="test-llm")
+    agent = Agent(llm=llm, tools=[], include_default_tools=["FinishTool"])
+
+    # Serialize to JSON
+    agent_json = agent.model_dump_json()
+    agent_dict = json.loads(agent_json)
+
+    # Should be serialized as string
+    assert agent_dict["include_default_tools"] == ["FinishTool"]
+
+
+def test_include_default_tools_deserialization_roundtrip() -> None:
+    """Test that include_default_tools deserializes correctly after round-trip."""
+    llm = LLM(model="test-model", usage_id="test-llm")
+    agent = Agent(llm=llm, tools=[], include_default_tools=["FinishTool"])
+
+    # Serialize to JSON
+    agent_json = agent.model_dump_json()
+
+    # Deserialize from JSON
+    deserialized_agent = AgentBase.model_validate_json(agent_json)
+
+    # Should have the same include_default_tools
+    assert isinstance(deserialized_agent, Agent)
+    assert deserialized_agent.include_default_tools == ["FinishTool"]
+
+
+def test_include_default_tools_deserialization_all_tools() -> None:
+    """Test that include_default_tools deserializes correctly with all tools."""
+    llm = LLM(model="test-model", usage_id="test-llm")
+    agent = Agent(llm=llm, tools=[], include_default_tools=["FinishTool", "ThinkTool"])
+
+    # Serialize to JSON
+    agent_json = agent.model_dump_json()
+
+    # Deserialize from JSON
+    deserialized_agent = AgentBase.model_validate_json(agent_json)
+
+    # Should have both tools
+    assert isinstance(deserialized_agent, Agent)
+    assert set(deserialized_agent.include_default_tools) == {"FinishTool", "ThinkTool"}
+
+
+def test_include_default_tools_deserialization_empty() -> None:
+    """Test that include_default_tools deserializes correctly when empty."""
+    llm = LLM(model="test-model", usage_id="test-llm")
+    agent = Agent(llm=llm, tools=[], include_default_tools=[])
+
+    # Serialize to JSON
+    agent_json = agent.model_dump_json()
+
+    # Deserialize from JSON
+    deserialized_agent = AgentBase.model_validate_json(agent_json)
+
+    # Should be empty
+    assert isinstance(deserialized_agent, Agent)
+    assert deserialized_agent.include_default_tools == []
+
+
+def test_include_default_tools_deserialization_from_dict() -> None:
+    """Test that include_default_tools deserializes correctly from dict."""
+    agent_dict = {
+        "llm": {"model": "test-model", "usage_id": "test-llm"},
+        "tools": [],
+        "include_default_tools": ["ThinkTool"],
+        "kind": "Agent",
+    }
+
+    # Deserialize from dict
+    agent = AgentBase.model_validate(agent_dict)
+
+    # Should have ThinkTool
+    assert isinstance(agent, Agent)
+    assert agent.include_default_tools == ["ThinkTool"]
+
+
+def test_include_default_tools_invalid_tool_name() -> None:
+    """Test that include_default_tools raises error for invalid tool name."""
+    agent_dict = {
+        "llm": {"model": "test-model", "usage_id": "test-llm"},
+        "tools": [],
+        "include_default_tools": ["InvalidTool"],
+        "kind": "Agent",
+    }
+
+    # Should raise ValueError
+    with pytest.raises(ValueError, match="Unknown built-in tool class: 'InvalidTool'"):
+        AgentBase.model_validate(agent_dict)
+
+
+def test_include_default_tools_accepts_tool_class_via_validator() -> None:
+    """Test that include_default_tools validator converts tool classes to strings."""
+    # The validator accepts tool classes and converts them to strings
+    # This is tested via model_validate to bypass type checking
+    agent_dict = {
+        "llm": {"model": "test-model", "usage_id": "test-llm"},
+        "tools": [],
+        "include_default_tools": [FinishTool],  # Pass class, not string
+        "kind": "Agent",
+    }
+
+    agent = AgentBase.model_validate(agent_dict)
+
+    # Should be converted to string
+    assert isinstance(agent, Agent)
+    assert agent.include_default_tools == ["FinishTool"]