refactor(tools): built-in agents

[VascoSch92]

Summary

This PR changes the built-in subagents available to the main agent.

Motivation

After various rounds of evaluation, a few issues came up:

• default was not a good name for the default agent — the main agent had trouble knowing when to call it.
• default_cli and default were problematic. In fact, they are essentially the same agent, the only difference being that one has web browser access.
• The main agent had trouble calling the correct agent.

Solution

• default is renamed to general_purpose and the prompt is updated.
• Separation between the default agent and a specific agent for web browsing. This way, we can give more guidance to the web browser agent on how to accomplish its task.
• explore was misleading for a web browser agent, so the name was changed to code-explorer. Same for bash.

Other

• Renamed cli_mode parameter to enable_browser with inverted semantics:
  • the code is much easier to understand
  • Old: cli_mode=False → default agent included browser tools
  • New: enable_browser=True → registers a dedicated web researcher agent with browser tools
  • The general-purpose agent no longer gets browser tools regardless of configuration. Browser capabilities are now isolated in the web researcher agent.
  • Added test_general_purpose_has_no_browser_tools to document this intentional architectural change.

Checklist

• If the PR is changing/adding functionality, are there tests to reflect this?
• If there is an example, have you run the example to make sure that it works?
• If there are instructions on how to run the code, have you followed the instructions and made sure that it works?
• If the feature is significant enough to require documentation, is there a PR open on the OpenHands/docs repository with the same branch name?
• Is the github CI passing?

---

Agent Server images for this PR

• GHCR package: https://github.com/OpenHands/agent-sdk/pkgs/container/agent-server

Variants & Base Images

Variant	Architectures	Base Image	Docs / Tags
java	amd64, arm64	eclipse-temurin:17-jdk	Link
python	amd64, arm64	nikolaik/python-nodejs:python3.13-nodejs22-slim	Link
golang	amd64, arm64	golang:1.21-bookworm	Link

Pull (multi-arch manifest)

# Each variant is a multi-arch manifest supporting both amd64 and arm64
docker pull ghcr.io/openhands/agent-server:e46fbb0-python

Run

docker run -it --rm \
  -p 8000:8000 \
  --name agent-server-e46fbb0-python \
  ghcr.io/openhands/agent-server:e46fbb0-python

All tags pushed for this build

ghcr.io/openhands/agent-server:e46fbb0-golang-amd64
ghcr.io/openhands/agent-server:e46fbb0-golang_tag_1.21-bookworm-amd64
ghcr.io/openhands/agent-server:e46fbb0-golang-arm64
ghcr.io/openhands/agent-server:e46fbb0-golang_tag_1.21-bookworm-arm64
ghcr.io/openhands/agent-server:e46fbb0-java-amd64
ghcr.io/openhands/agent-server:e46fbb0-eclipse-temurin_tag_17-jdk-amd64
ghcr.io/openhands/agent-server:e46fbb0-java-arm64
ghcr.io/openhands/agent-server:e46fbb0-eclipse-temurin_tag_17-jdk-arm64
ghcr.io/openhands/agent-server:e46fbb0-python-amd64
ghcr.io/openhands/agent-server:e46fbb0-nikolaik_s_python-nodejs_tag_python3.13-nodejs22-slim-amd64
ghcr.io/openhands/agent-server:e46fbb0-python-arm64
ghcr.io/openhands/agent-server:e46fbb0-nikolaik_s_python-nodejs_tag_python3.13-nodejs22-slim-arm64
ghcr.io/openhands/agent-server:e46fbb0-golang
ghcr.io/openhands/agent-server:e46fbb0-java
ghcr.io/openhands/agent-server:e46fbb0-python

About Multi-Architecture Support

• Each variant tag (e.g., e46fbb0-python) is a multi-arch manifest supporting both amd64 and arm64
• Docker automatically pulls the correct architecture for your platform
• Individual architecture tags (e.g., e46fbb0-python-amd64) are also available if needed

[github-actions]

Python API breakage checks — ✅ PASSED

Result: ✅ PASSED

Action log

[github-actions]

REST API breakage checks (OpenAPI) — ✅ PASSED

Result: ✅ PASSED

Action log

[github-actions]

Coverage Report •

File	Stmts	Miss	Cover	Missing
openhands-sdk/openhands/sdk/subagent
registry.py	130	6	95%	117, 242–243, 247, 293–294
openhands-tools/openhands/tools/preset
default.py	51	2	96%	110–111
openhands-tools/openhands/tools/task
definition.py	58	25	56%	72, 78–80, 82–84, 86–87, 95, 100–101, 104, 106, 177, 230, 232, 234–235, 239, 244–245, 247–248, 254
TOTAL	23001	5880	74%

[all-hands-bot]

Taste Rating

🟡 Acceptable - Solid architectural refactoring with good backward compatibility handling.

Assessment

The core changes are sound:

• Separating browser capabilities into a dedicated web-researcher agent eliminates the confusing cli_mode boolean logic
• The cli_mode → enable_browser rename is much clearer (no more inverted semantics)
• Backward compatibility properly handled via deprecation mapping with version info
• Test coverage is comprehensive - verifies both name mapping AND tool correctness

Verdict

✅ Code quality is solid - Implementation is correct, tests are thorough, no critical issues found.

⚠️ Human review required - Per repo guidelines, this PR modifies agent behavior (prompts, tool assignments, agent routing) and should NOT be auto-approved. A human maintainer must review after considering evaluation impact.

All previously identified issues have been resolved. The architectural separation is good engineering taste.

[all-hands-bot]

⚠️ Eval Risk - Human Review Required

This PR modifies agent behavior (prompts, tool assignments, agent routing) and should NOT be auto-approved per repo guidelines. A human maintainer must review after considering evaluation impact.

Assessment: All previously identified issues have been resolved. The architectural change (separating general-purpose from browser-specific agents) is solid and the backward compatibility handling is correct. However, this changes core agent behavior and requires eval verification before merging.

[all-hands-bot]

[Automatic Post]: This PR seems to be currently waiting for review. @enyst, could you please take a look when you have a chance?

[all-hands-bot]

[Automatic Post]: It has been a while since there was any activity on this PR. @VascoSch92, are you still working on it? If so, please go ahead, if not then please request review, close it, or request that someone else follow up.

[VascoSch92]

@enyst :-) Would be nice to merge that. The subagents that we have now are not so good. And I would like to merge that before we have TaskToolSet in cloud. (because of backward compatibility).

Do you have blockers or things i should change?

[enyst]

Thank you, and sorry for the delay. It looks good and it's localized in subagents, time for fun! ❤️