From 12d4aea8075306d4d783ee69b973f07b19640fed Mon Sep 17 00:00:00 2001 From: VascoSch92 Date: Mon, 2 Mar 2026 10:45:49 +0100 Subject: [PATCH 1/2] update docs --- sdk/guides/agent-file-based.mdx | 41 +++++++++++++++++++++++++++------ 1 file changed, 34 insertions(+), 7 deletions(-) diff --git a/sdk/guides/agent-file-based.mdx b/sdk/guides/agent-file-based.mdx index 627e44a4..88c883aa 100644 --- a/sdk/guides/agent-file-based.mdx +++ b/sdk/guides/agent-file-based.mdx @@ -99,17 +99,45 @@ Place agent files in these directories, scanned in **priority order** (first mat Put agents shared across all your projects in `~/.agents/agents/`. Put project-specific agents in `{project}/.agents/agents/`. -## Built-in Agents +## Built-in Sub-Agents -The SDK ships with built-in agents that are automatically loaded at the beginning of each conversation and are available to the user. +The `tools` package ships with built-in sub-agents as Markdown files in `openhands/tools/preset/subagents/`. +They can be registered via `register_builtins_agents()` and become available for delegation tasks. -By default, agents include `FinishTool` and `ThinkTool`; they are appended after tool filtering. +By default, all agents include `finish` tool and the `think` tool. -The table below summarizes all available built-in agents: +### Available Built-in Sub-Agents | Agent | Tools | Description | |--------|-------|-------| -| **default** | `terminal`, `file_editor`, `task_tracker`, `browser_tool_set` | general purpose agent | +| **default** | `terminal`, `file_editor`, `task_tracker`, `browser_tool_set` | General-purpose agent. Used as the fallback when no agent name is specified. | +| **default cli mode** | `terminal`, `file_editor`, `task_tracker` | Same as `default` but without browser tools (used in CLI mode). | +| **explore** | `terminal` | Read-only codebase exploration agent. Finds files, searches code, reads source — never creates or modifies anything. | +| **bash** | `terminal` | Command execution specialist. Runs shell commands, builds, tests, and git operations. | + +In CLI mode, the `default` agent (with browser tools) is replaced by the `default cli mode` agent. In non-CLI mode, `default cli mode` is filtered out. + +### Registering Built-in Sub-Agents + +Call `register_builtins_agents()` to register all built-in sub-agents. This is typically done once before creating a conversation: + +```python icon="python" +from openhands.tools.preset.default import register_builtins_agents + +# Register built-in sub-agents (default, explore, bash) +register_builtins_agents() + +# Or in CLI mode (swaps default for default cli mode — no browser) +register_builtins_agents(cli_mode=True) +``` + + +Registration order matters when you programmatically register agents with the same name as a built-in. + `register_builtins_agents()` uses `register_agent_if_absent()`, which silently skips names that are already taken, + so if you register your custom agents **before** calling `register_builtins_agents()`, your agents win. + If you call `register_builtins_agents()` first, a subsequent `register_agent()` with a conflicting name will raise a `ValueError`. + + ## Overall Priority @@ -120,8 +148,7 @@ When the same agent name is defined in multiple places, the highest-priority sou | 1 (highest) | **Programmatic** `register_agent()` | Registered first, never overwritten | | 2 | **Plugin agents** (`Plugin.agents`) | Loaded from plugin `agents/` directories | | 3 | **Project-level** file-based agents | `.agents/agents/*.md` or `.openhands/agents/*.md` | -| 4 | **User-level** file-based agents | `~/.agents/agents/*.md` or `~/.openhands/agents/*.md` | -| 5 (lowest) | **Built-in agents** | SDK built-in agents | +| 4 (lowest) | **User-level** file-based agents | `~/.agents/agents/*.md` or `~/.openhands/agents/*.md` | ## Auto-Registration From e4cc0341d839cb7a2ae8470a2713481ea4ab0b0a Mon Sep 17 00:00:00 2001 From: VascoSch92 Date: Mon, 2 Mar 2026 13:42:53 +0100 Subject: [PATCH 2/2] feedback of all-hands-bot --- sdk/guides/agent-file-based.mdx | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/sdk/guides/agent-file-based.mdx b/sdk/guides/agent-file-based.mdx index 88c883aa..e96439f0 100644 --- a/sdk/guides/agent-file-based.mdx +++ b/sdk/guides/agent-file-based.mdx @@ -99,9 +99,9 @@ Place agent files in these directories, scanned in **priority order** (first mat Put agents shared across all your projects in `~/.agents/agents/`. Put project-specific agents in `{project}/.agents/agents/`. -## Built-in Sub-Agents +## Built-in Agents -The `tools` package ships with built-in sub-agents as Markdown files in `openhands/tools/preset/subagents/`. +The `openhands-tools` package ships with built-in sub-agents as Markdown files in `openhands/tools/preset/subagents/`. They can be registered via `register_builtins_agents()` and become available for delegation tasks. By default, all agents include `finish` tool and the `think` tool. @@ -121,7 +121,7 @@ In CLI mode, the `default` agent (with browser tools) is replaced by the `defaul Call `register_builtins_agents()` to register all built-in sub-agents. This is typically done once before creating a conversation: -```python icon="python" +```python icon="python" focus={3-4, 6-7} from openhands.tools.preset.default import register_builtins_agents # Register built-in sub-agents (default, explore, bash) @@ -132,10 +132,9 @@ register_builtins_agents(cli_mode=True) ``` -Registration order matters when you programmatically register agents with the same name as a built-in. - `register_builtins_agents()` uses `register_agent_if_absent()`, which silently skips names that are already taken, - so if you register your custom agents **before** calling `register_builtins_agents()`, your agents win. - If you call `register_builtins_agents()` first, a subsequent `register_agent()` with a conflicting name will raise a `ValueError`. +Registration order is critical when programmatically registering agents that share a name with a built-in agent. The system is designed to skip registration if a name is already taken. Therefore, if you register your custom agents before the built-in agents are loaded, your custom versions will take precedence. + +Conversely, if the built-in agents are loaded first, they will take precedence, and any subsequent registration of a custom agent with the same name will be ignored.