fix(agent-server/sdk): subagents missing in remote workspace

openhands-agent-server/openhands/agent_server/conversation_service.py

@@ -27,6 +27,10 @@
 )
 from openhands.sdk.event import MessageEvent
 from openhands.sdk.event.conversation_state import ConversationStateUpdateEvent
+from openhands.sdk.subagent.registry import (
+    agent_definition_to_factory,
+    register_agent_if_absent,
+)
 from openhands.sdk.utils.cipher import Cipher
 
 
@@ -240,6 +244,20 @@ async def start_conversation(
                     f"{list(request.tool_module_qualnames.keys())}"
                 )
 
+        # Register subagent definitions from the client's registry
+        if request.subagent_definitions:
+            for agent_def in request.subagent_definitions:
+                factory = agent_definition_to_factory(agent_def)
+                if not agent_def.description:
+                    agent_def = agent_def.model_copy(
+                        update={"description": f"Remote agent: {agent_def.name}"}
+                    )
+                register_agent_if_absent(factory, agent_def)
+            logger.info(
+                f"Registered {len(request.subagent_definitions)} subagent "
+                f"definitions for conversation {conversation_id}: "
+                f"{[d.name for d in request.subagent_definitions]}"
+            )
         # Plugin loading is now handled lazily by LocalConversation.
         # Just pass the plugin specs through to StoredConversation.
         # LocalConversation will:

openhands-agent-server/openhands/agent_server/models.py

@@ -21,6 +21,7 @@
     ConfirmationPolicyBase,
     NeverConfirm,
 )
+from openhands.sdk.subagent.schema import AgentDefinition
 from openhands.sdk.utils.models import DiscriminatedUnionMixin, OpenHandsModel
 from openhands.sdk.workspace import LocalWorkspace
 
@@ -108,6 +109,13 @@ class StartConversationRequest(BaseModel):
             "to register the tools for this conversation."
         ),
     )
+    subagent_definitions: list[AgentDefinition] = Field(
+        default_factory=list,
+        description=(
+            "Subagent definitions from the client's registry. These are "
+            "registered on the server so DelegateTool can advertise them."
+        ),
+    )
     plugins: list[PluginSource] | None = Field(
         default=None,
         description=(

openhands-sdk/openhands/sdk/conversation/impl/remote_conversation.py

@@ -635,10 +635,14 @@ def __init__(
 
         if should_create:
             # Import here to avoid circular imports
+            from openhands.sdk.subagent.registry import (
+                get_registered_agent_definitions,
+            )
             from openhands.sdk.tool.registry import get_tool_module_qualnames
 
             tool_qualnames = get_tool_module_qualnames()
             logger.debug(f"Sending tool_module_qualnames to server: {tool_qualnames}")
+            subagent_defs = get_registered_agent_definitions()
             payload = {
                 "agent": agent.model_dump(
                     mode="json", context={"expose_secrets": True}
@@ -652,6 +656,8 @@ def __init__(
                 ).model_dump(),
                 # Include tool module qualnames for dynamic registration on server
                 "tool_module_qualnames": tool_qualnames,
+                # Include subagent definitions for delegate tool on server
+                "subagent_definitions": [d.model_dump() for d in subagent_defs],
                 # Include plugins to load on server
                 "plugins": [p.model_dump() for p in plugins] if plugins else None,
             }

openhands-sdk/openhands/sdk/subagent/registry.py

@@ -28,6 +28,8 @@ def create_security_expert(llm):
 from threading import RLock
 from typing import TYPE_CHECKING, NamedTuple
 
+from pydantic import SecretStr
+
 from openhands.sdk.logger import get_logger
 from openhands.sdk.subagent.load import (
     load_project_agents,
@@ -44,10 +46,10 @@ def create_security_expert(llm):
 
 
 class AgentFactory(NamedTuple):
-    """Simple container for an agent factory function and its description."""
+    """Simple container for an agent factory function and its definition."""
 
     factory_func: Callable[["LLM"], "Agent"]
-    description: str
+    definition: AgentDefinition
 
 
 # Global registry for user-registered agent factories
@@ -71,19 +73,34 @@ def register_agent(
     Raises:
         ValueError: If an agent with the same name already exists
     """
+    try:
+        from openhands.sdk.llm.llm import LLM as _LLM
+
+        _model_placeholder = "__introspect__"
+        agent = factory_func(_LLM(model=_model_placeholder, api_key=SecretStr("n/a")))
+        definition = AgentDefinition.from_agent(
+            agent, name=name, description=description
+        )
+        # If the model was our placeholder, the factory didn't set one explicitly
+        if definition.model == _model_placeholder:
+            definition = definition.model_copy(update={"model": "inherit"})
+    except Exception:
+        logger.debug(f"Could not introspect factory for agent '{name}'")
+        definition = AgentDefinition(name=name, description=description)
+
     with _registry_lock:
         if name in _agent_factories:
             raise ValueError(f"Agent '{name}' already registered")
 
         _agent_factories[name] = AgentFactory(
-            factory_func=factory_func, description=description
+            factory_func=factory_func,
+            definition=definition,
         )
 
 
 def register_agent_if_absent(
-    name: str,
     factory_func: Callable[["LLM"], "Agent"],
-    description: str,
+    definition: AgentDefinition,
 ) -> bool:
     """
     Register a custom agent if no agent with that name exists yet.
@@ -93,20 +110,19 @@ def register_agent_if_absent(
     with programmatically registered agents.
 
     Args:
-        name: Unique name for the agent
         factory_func: Function that takes an LLM and returns an Agent
-        description: Human-readable description of what this agent does
+        definition: AgentDefinition describing the agent.
 
     Returns:
         True if the agent was registered, False if an agent with that name
         already existed.
     """
     with _registry_lock:
-        if name in _agent_factories:
+        if definition.name in _agent_factories:
             return False
 
-        _agent_factories[name] = AgentFactory(
-            factory_func=factory_func, description=description
+        _agent_factories[definition.name] = AgentFactory(
+            factory_func=factory_func, definition=definition
         )
         return True
 
@@ -200,11 +216,11 @@ def register_file_agents(work_dir: str | Path) -> list[str]:
     registered: list[str] = []
     for agent_def in deduplicated:
         factory = agent_definition_to_factory(agent_def)
-        was_registered = register_agent_if_absent(
-            name=agent_def.name,
-            factory_func=factory,
-            description=agent_def.description or f"File-based agent: {agent_def.name}",
-        )
+        if not agent_def.description:
+            agent_def = agent_def.model_copy(
+                update={"description": f"File-based agent: {agent_def.name}"}
+            )
+        was_registered = register_agent_if_absent(factory, agent_def)
         if was_registered:
             registered.append(agent_def.name)
             logger.info(
@@ -232,11 +248,11 @@ def register_plugin_agents(agents: list[AgentDefinition]) -> list[str]:
     registered: list[str] = []
     for agent_def in agents:
         factory = agent_definition_to_factory(agent_def)
-        was_registered = register_agent_if_absent(
-            name=agent_def.name,
-            factory_func=factory,
-            description=agent_def.description or f"Plugin agent: {agent_def.name}",
-        )
+        if not agent_def.description:
+            agent_def = agent_def.model_copy(
+                update={"description": f"Plugin agent: {agent_def.name}"}
+            )
+        was_registered = register_agent_if_absent(factory, agent_def)
         if was_registered:
             registered.append(agent_def.name)
             logger.info(f"Registered plugin agent '{agent_def.name}'")
@@ -294,11 +310,17 @@ def get_factory_info() -> str:
         return "\n".join(info_lines)
 
     for name, factory in sorted(user_factories.items()):
-        info_lines.append(f"- **{name}**: {factory.description}")
+        info_lines.append(f"- **{name}**: {factory.definition.description}")
 
     return "\n".join(info_lines)
 
 
+def get_registered_agent_definitions() -> list[AgentDefinition]:
+    """Return stored AgentDefinitions for forwarding to remote servers."""
+    with _registry_lock:
+        return [f.definition for f in _agent_factories.values()]
+
+
 def _reset_registry_for_tests() -> None:
     """Clear the registry for tests to avoid cross-test contamination."""
     with _registry_lock:

openhands-sdk/openhands/sdk/subagent/schema.py

@@ -4,12 +4,16 @@
 
 import re
 from pathlib import Path
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
 import frontmatter
 from pydantic import BaseModel, Field
 
 
+if TYPE_CHECKING:
+    from openhands.sdk.agent.base import AgentBase
+
+
 def _extract_examples(description: str) -> list[str]:
     """Extract <example> tags from description for agent triggering."""
     pattern = r"<example>(.*?)</example>"
@@ -111,3 +115,37 @@ def load(cls, agent_path: Path) -> AgentDefinition:
             when_to_use_examples=when_to_use_examples,
             metadata=metadata,
         )
+
+    @classmethod
+    def from_agent(
+        cls,
+        agent: AgentBase,
+        name: str,
+        description: str,
+    ) -> AgentDefinition:
+        """Build an AgentDefinition by introspecting a live Agent instance.
+
+        Args:
+            agent: The agent to extract configuration from.
+            name: Name for the agent definition.
+            description: Human-readable description of the agent.
+
+        Returns:
+            A fully populated AgentDefinition.
+        """
+        tools = [t.name for t in agent.tools]
+
+        if agent.agent_context and agent.agent_context.system_message_suffix:
+            system_prompt = agent.agent_context.system_message_suffix
+        else:
+            system_prompt = ""
+
+        model = agent.llm.model if agent.llm.model else "inherit"
+
+        return cls(
+            name=name,
+            description=description,
+            tools=tools,
+            system_prompt=system_prompt,
+            model=model,
+        )

openhands-tools/openhands/tools/preset/default.py

@@ -123,11 +123,11 @@ def register_builtins_agents(cli_mode: bool = False) -> list[str]:
     registered: list[str] = []
     for agent_def in builtins_agents_def:
         factory = agent_definition_to_factory(agent_def)
-        was_registered = register_agent_if_absent(
-            name=agent_def.name,
-            factory_func=factory,
-            description=agent_def.description or f"Agent: {agent_def.name}",
-        )
+        if not agent_def.description:
+            agent_def = agent_def.model_copy(
+                update={"description": f"Agent: {agent_def.name}"}
+            )
+        was_registered = register_agent_if_absent(factory, agent_def)
         if was_registered:
             registered.append(agent_def.name)
             logger.info(