feat(delegate): Built-in specialized agent types (Explore, Bash) (#2201)

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

Author: 3 people

examples/01_standalone_sdk/25_agent_delegation.py

@@ -9,8 +9,6 @@
 
 import os
 
-from pydantic import SecretStr
-
 from openhands.sdk import (
     LLM,
     Agent,
@@ -26,30 +24,26 @@
     DelegateTool,
     DelegationVisualizer,
 )
-from openhands.tools.preset.default import get_default_tools
+from openhands.tools.preset.default import get_default_tools, register_builtins_agents
 
 
 ONLY_RUN_SIMPLE_DELEGATION = False
 
 logger = get_logger(__name__)
 
 # Configure LLM and agent
-# You can get an API key from https://app.all-hands.dev/settings/api-keys
-api_key = os.getenv("LLM_API_KEY")
-assert api_key is not None, "LLM_API_KEY environment variable is not set."
-model = os.getenv("LLM_MODEL", "anthropic/claude-sonnet-4-5-20250929")
 llm = LLM(
-    model=model,
-    api_key=SecretStr(api_key),
+    model=os.getenv("LLM_MODEL", "anthropic/claude-sonnet-4-5-20250929"),
+    api_key=os.getenv("LLM_API_KEY"),
     base_url=os.environ.get("LLM_BASE_URL", None),
     usage_id="agent",
 )
 
 cwd = os.getcwd()
 
-register_tool("DelegateTool", DelegateTool)
-tools = get_default_tools(enable_browser=False)
-tools.append(Tool(name="DelegateTool"))
+tools = get_default_tools(enable_browser=True)
+tools.append(Tool(name=DelegateTool.name))
+register_builtins_agents()
 
 main_agent = Agent(
     llm=llm,
@@ -61,7 +55,7 @@
     visualizer=DelegationVisualizer(name="Delegator"),
 )
 
-task_message = (
+conversation.send_message(
     "Forget about coding. Let's switch to travel planning. "
     "Let's plan a trip to London. I have two issues I need to solve: "
     "Lodging: what are the best areas to stay at while keeping budget in mind? "
@@ -72,7 +66,6 @@
     "They should keep it short. After getting the results, merge both analyses "
     "into a single consolidated report.\n\n"
 )
-conversation.send_message(task_message)
 conversation.run()
 
 conversation.send_message(
@@ -81,18 +74,57 @@
 conversation.run()
 
 # Report cost for simple delegation example
-cost_1 = conversation.conversation_stats.get_combined_metrics().accumulated_cost
-print(f"EXAMPLE_COST (simple delegation): {cost_1}")
+cost_simple = conversation.conversation_stats.get_combined_metrics().accumulated_cost
+print(f"EXAMPLE_COST (simple delegation): {cost_simple}")
 
 print("Simple delegation example done!", "\n" * 20)
 
-
-# -------- Agent Delegation Second Part: User-Defined Agent Types --------
-
 if ONLY_RUN_SIMPLE_DELEGATION:
+    # For CI: always emit the EXAMPLE_COST marker before exiting.
+    print(f"EXAMPLE_COST: {cost_simple}")
     exit(0)
 
 
+# -------- Agent Delegation Second Part: Built-in Agent Types (Explore + Bash) --------
+
+main_agent = Agent(
+    llm=llm,
+    tools=[Tool(name=DelegateTool.name)],
+)
+conversation = Conversation(
+    agent=main_agent,
+    workspace=cwd,
+    visualizer=DelegationVisualizer(name="Delegator (builtins)"),
+)
+
+builtin_task_message = (
+    "Demonstrate SDK built-in sub-agent types. "
+    "1) Spawn an 'explore' sub-agent and ask it to list the markdown files in "
+    "openhands-sdk/openhands/sdk/subagent/builtins/ and summarize what each "
+    "built-in agent type is for (based on the file contents). "
+    "2) Spawn a 'bash' sub-agent and ask it to run `python --version` in the "
+    "terminal and return the exact output. "
+    "3) Merge both results into a short report. "
+    "Do not use internet access."
+)
+
+print("=" * 100)
+print("Demonstrating built-in agent delegation (explore + bash)...")
+print("=" * 100)
+
+conversation.send_message(builtin_task_message)
+conversation.run()
+
+# Report cost for builtin agent types example
+cost_builtin = conversation.conversation_stats.get_combined_metrics().accumulated_cost
+print(f"EXAMPLE_COST (builtin agents): {cost_builtin}")
+
+print("Built-in agent delegation example done!", "\n" * 20)
+
+
+# -------- Agent Delegation Third Part: User-Defined Agent Types --------
+
+
 def create_lodging_planner(llm: LLM) -> Agent:
     """Create a lodging planner focused on London stays."""
     skills = [
@@ -190,10 +222,12 @@ def create_activities_planner(llm: LLM) -> Agent:
 conversation.run()
 
 # Report cost for user-defined agent types example
-cost_2 = conversation.conversation_stats.get_combined_metrics().accumulated_cost
-print(f"EXAMPLE_COST (user-defined agents): {cost_2}")
+cost_user_defined = (
+    conversation.conversation_stats.get_combined_metrics().accumulated_cost
+)
+print(f"EXAMPLE_COST (user-defined agents): {cost_user_defined}")
 
 print("All done!")
 
 # Full example cost report for CI workflow
-print(f"EXAMPLE_COST: {cost_1 + cost_2}")
+print(f"EXAMPLE_COST: {cost_simple + cost_builtin + cost_user_defined}")

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

@@ -51,7 +51,6 @@
     register_file_agents,
     register_plugin_agents,
 )
-from openhands.sdk.subagent.registry import register_builtins_agents
 from openhands.sdk.tool.schema import Action, Observation
 from openhands.sdk.utils.cipher import Cipher
 from openhands.sdk.workspace import LocalWorkspace
@@ -417,12 +416,9 @@ def _register_file_based_agents(self) -> None:
                 then `{project}/.openhands/agents/*.md`)
           4. User-level file agents (`~/.agents/agents/*.md`,
                 then `~/.openhands/agents/*.md`)
-          5. SDK builtin agents (`subagent/builtins/*.md`)
         """
         # register project-level and then user-level file-based agents
         register_file_agents(self.workspace.working_dir)
-        # register builtins agents
-        register_builtins_agents()
 
     def _ensure_agent_ready(self) -> None:
         """Ensure the agent is fully initialized with plugins and agents loaded.

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

@@ -30,7 +30,6 @@ def create_security_expert(llm):
 
 from openhands.sdk.logger import get_logger
 from openhands.sdk.subagent.load import (
-    load_agents_from_dir,
     load_project_agents,
     load_user_agents,
 )
@@ -43,8 +42,6 @@ def create_security_expert(llm):
 
 logger = get_logger(__name__)
 
-BUILTINS_DIR = Path(__file__).parent / "builtins"
-
 
 class AgentFactory(NamedTuple):
     """Simple container for an agent factory function and its description."""
@@ -127,11 +124,15 @@ def agent_definition_to_factory(
       `AgentContext`.
     - `model: inherit` preserves the parent LLM; an explicit model name
       creates a copy via `model_copy(update=...)`.
+
+    Raises:
+        ValueError: If a tool provided to the agent is not registered.
     """
 
     def _factory(llm: "LLM") -> "Agent":
         from openhands.sdk.agent.agent import Agent
         from openhands.sdk.context.agent_context import AgentContext
+        from openhands.sdk.tool.registry import list_registered_tools
         from openhands.sdk.tool.spec import Tool
 
         # Handle model override
@@ -147,7 +148,15 @@ def _factory(llm: "LLM") -> "Agent":
         )
 
         # Resolve tools
-        tools = [Tool(name=tool_name) for tool_name in agent_def.tools]
+        tools: list[Tool] = []
+        registered_tools: set[str] = set(list_registered_tools())
+        for tool_name in agent_def.tools:
+            if tool_name not in registered_tools:
+                raise ValueError(
+                    f"Tool '{tool_name}' not registered"
+                    f"but was given to agent {agent_def.name}."
+                )
+            tools.append(Tool(name=tool_name))
 
         return Agent(
             llm=llm,
@@ -235,35 +244,6 @@ def register_plugin_agents(agents: list[AgentDefinition]) -> list[str]:
     return registered
 
 
-def register_builtins_agents() -> list[str]:
-    """Load and register SDK builtin agents from ``subagent/builtins/*.md``.
-
-    They are registered via ``register_agent_if_absent`` and will not
-    overwrite agents already registered by programmatic calls, plugins,
-    or project/user-level file-based definitions.
-
-    Returns:
-        List of agent names that were actually registered.
-    """
-    builtins_agents_def = load_agents_from_dir(BUILTINS_DIR)
-
-    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 was_registered:
-            registered.append(agent_def.name)
-            logger.info(
-                f"Registered file-based agent '{agent_def.name}'"
-                + (f" from {agent_def.source}" if agent_def.source else "")
-            )
-    return registered
-
-
 def get_agent_factory(name: str | None) -> AgentFactory:
     """
     Get a registered agent factory by name.

openhands-tools/openhands/tools/__init__.py

@@ -23,6 +23,7 @@
 from openhands.tools.preset.default import (
     get_default_agent,
     get_default_tools,
+    register_builtins_agents,
     register_default_tools,
 )
 from openhands.tools.task_tracker import TaskTrackerTool
@@ -44,4 +45,5 @@
     "get_default_agent",
     "get_default_tools",
     "register_default_tools",
+    "register_builtins_agents",
 ]

openhands-tools/openhands/tools/preset/__init__.py

@@ -18,7 +18,7 @@
   setups.
 """
 
-from .default import get_default_agent
+from .default import get_default_agent, register_builtins_agents
 from .gemini import get_gemini_agent, get_gemini_tools
 from .gpt5 import get_gpt5_agent
 from .planning import get_planning_agent
@@ -30,4 +30,5 @@
     "get_gemini_tools",
     "get_gpt5_agent",
     "get_planning_agent",
+    "register_builtins_agents",
 ]

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

@@ -1,12 +1,15 @@
 """Default preset configuration for OpenHands agents."""
 
-from openhands.sdk import Agent
+from pathlib import Path
+
+from openhands.sdk import Agent, agent_definition_to_factory, load_agents_from_dir
 from openhands.sdk.context.condenser import (
     LLMSummarizingCondenser,
 )
 from openhands.sdk.context.condenser.base import CondenserBase
 from openhands.sdk.llm.llm import LLM
 from openhands.sdk.logger import get_logger
+from openhands.sdk.subagent import register_agent_if_absent
 from openhands.sdk.tool import Tool
 
 
@@ -83,3 +86,52 @@ def get_default_agent(
         ),
     )
     return agent
+
+
+def register_builtins_agents(cli_mode: bool = False) -> list[str]:
+    """Load and register builtin agents from ``subagent/*.md``.
+
+    They are registered via `register_agent_if_absent` and will not
+    overwrite agents already registered by programmatic calls, plugins,
+    or project/user-level file-based definitions.
+
+    Args:
+        cli_mode: Whether to load the default agent in cli mode or not.
+
+    Returns:
+        List of agents which were actually registered.
+    """
+    register_default_tools(
+        # Disable browser tools in CLI mode
+        enable_browser=not cli_mode,
+    )
+
+    subagent_dir = Path(__file__).parent / "subagents"
+    builtins_agents_def = load_agents_from_dir(subagent_dir)
+
+    # if we are in cli mode, we filter out the default agent (with browser tool)
+    # otherwise, we filter out the default cli agent
+    if cli_mode:
+        builtins_agents_def = [
+            agent for agent in builtins_agents_def if agent.name != "default"
+        ]
+    else:
+        builtins_agents_def = [
+            agent for agent in builtins_agents_def if agent.name != "default cli mode"
+        ]
+
+    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 was_registered:
+            registered.append(agent_def.name)
+            logger.info(
+                f"Registered file-based agent '{agent_def.name}'"
+                + (f" from {agent_def.source}" if agent_def.source else "")
+            )
+    return registered

openhands-tools/openhands/tools/preset/subagents/bash.md

@@ -0,0 +1,36 @@
+---
+name: bash
+model: inherit
+description: >-
+  Command execution specialist (terminal only).
+  <example>Run a shell command</example>
+  <example>Execute a build or test script</example>
+  <example>Check system information or process status</example>
+tools:
+  - terminal
+---
+
+You are a command-line execution specialist. Your sole interface is the
+terminal — use it to run shell commands on behalf of the caller.
+
+## Core capabilities
+
+- Execute arbitrary shell commands (bash/sh).
+- Run builds, tests, linters, formatters, and other development tooling.
+- Inspect system state: processes, disk usage, environment variables, network.
+- Perform git operations (commit, push, rebase, etc.).
+
+## Guidelines
+
+1. **Be precise.** Run exactly what was requested. Do not add extra flags or
+   steps unless they are necessary for correctness.
+2. **Check before destroying.** For destructive operations (`rm -rf`, `git
+   reset --hard`, `DROP TABLE`, etc.), confirm the intent and scope before
+   executing.
+3. **Report results clearly.** After running a command, summarize the outcome —
+   exit code, key output lines, and any errors.
+4. **Chain when appropriate.** Use `&&` to chain dependent commands so later
+   steps only run if earlier ones succeed.
+5. **Avoid interactive commands.** Do not run commands that require interactive
+   input (e.g., `vim`, `less`, `git rebase -i`). Use non-interactive
+   alternatives instead.

…enhands/sdk/subagent/builtins/default.md …nhands/tools/preset/subagents/default.mdopenhands-sdk/openhands/sdk/subagent/builtins/default.md renamed to openhands-tools/openhands/tools/preset/subagents/default.md openhands-sdk/openhands/sdk/subagent/builtins/default.md renamed to openhands-tools/openhands/tools/preset/subagents/default.md

@@ -0,0 +1,8 @@
+---
+name: default cli mode
+description: Default general-purpose agent
+tools:
+  - terminal
+  - file_editor
+  - task_tracker
+---