feat(delegate): Built-in specialized agent types (Explore, Bash) by VascoSch92 · Pull Request #2201 · OpenHands/software-agent-sdk

VascoSch92 · 2026-02-25T16:14:51Z

Summary

The PR adds 2 built-in specialized agents: Explore and Bash. (ref #2051 )

Requirements

Explore, and Bash agent types are available out of the box
Yes. They are loaded automatically in each conversation and at the disposal of the main agent.

Each has an appropriate system prompt and tool subset
System prompts tailored to their function

Users can reference these types in delegation
Yes.

Built-in types can be overridden by user definitions
Yes. The user can define another agent with the same agent and this one will override the built-in one.

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.12-nodejs22`	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:fb8eee2-python

Run

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

All tags pushed for this build

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

About Multi-Architecture Support

Each variant tag (e.g., fb8eee2-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., fb8eee2-python-amd64) are also available if needed

github-actions · 2026-02-25T16:15:26Z

API breakage checks (Griffe)

Result: Failed

Log excerpt (first 1000 characters)


============================================================
Checking openhands-sdk (openhands.sdk)
============================================================
Comparing openhands-sdk 1.11.5 against 1.11.4
::notice title=openhands-sdk API::Ignoring Field metadata-only change (non-breaking): load_public_skills
::notice title=openhands-sdk API::Ignoring Field metadata-only change (non-breaking): temperature
::warning file=openhands-sdk/openhands/sdk/llm/llm.py,line=190,title=LLM.top_p::Attribute value was changed: `Field(default=1.0, ge=0, le=1)` -> `Field(default=None, ge=0, le=1, description='Nucleus sampling parameter. Defaults to None (uses provider default). Set to a value between 0 and 1 to control diversity of outputs.')`
::error title=SemVer::Breaking changes detected (1); require at least minor version bump from 1.11.x, but new is 1.11.5

============================================================
Checking openhands-workspace (openhands.workspace)
============================

Action log

github-actions · 2026-02-25T16:17:51Z

Coverage Report •

File	Stmts	Miss	Cover	Missing
openhands-sdk/openhands/sdk/conversation/impl
local_conversation.py	341	21	93%	282, 287, 315, 358, 376, 389, 451, 600–601, 604, 756, 764, 766, 777, 779–781, 806, 968, 975–976
openhands-sdk/openhands/sdk/subagent
registry.py	96	6	93%	76, 154–155, 159, 197–198
openhands-tools/openhands/tools
__init__.py	11	2	81%	35–36
openhands-tools/openhands/tools/preset
default.py	51	14	72%	104, 109–110, 114–115, 119, 123–126, 131–133, 137
TOTAL	19586	6065	69%

all-hands-bot

Taste Rating: 🟢 Good taste - Clean, straightforward implementation

Analysis: This is solid work. The agent definitions are well-structured with appropriate tool restrictions and clear system prompts. Tests are comprehensive without being excessive - they cover loading, registration, override behavior, and verify agents actually instantiate correctly.

No fundamental data structure issues, no complexity problems, no over-engineering. The code does exactly what it needs to do in a simple, maintainable way.

Verdict: ✅ LGTM - Ready to merge

enyst · 2026-02-25T18:20:02Z

@OpenHands This PR brings agents, active agents that should be possible to run normally and do their thing. I think unit testing with mocks is not great fit for them. Look at the unit tests and reduce those that test too few or unimportant things; instead, look if you can add these to the examples/ where there is an example with subagents. Fix

openhands-ai · 2026-02-25T18:20:29Z

I'm on it! enyst can track my progress at all-hands.dev

- Simplify builtin agent tests (no mocks, focus on registry contracts) - Extend delegation example to demonstrate built-in explore/bash agents Co-authored-by: openhands <openhands@all-hands.dev>

examples/01_standalone_sdk/25_agent_delegation.py

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

examples/01_standalone_sdk/25_agent_delegation.py

github-actions · 2026-02-27T13:38:54Z

Agent server REST API breakage checks (OpenAPI)

Result: Passed

Action log

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

VascoSch92 · 2026-03-02T09:17:51Z

@enyst I completely understand the confusion following the comments here.

After some discussion, we decided to move the builtin agents into the tools package. While it might seem slightly counterintuitive to house agents inside a 'tools' package, it makes sense for several reasons:

Functional Dependency: Subagents are only utilized via the DelegationTool or TaskSetTool; therefore, subagents are functionally dependent on tools.
Meaningful Agents: For subagents to be useful, they require tools. Since tools are defined within the tools package, keeping subagents there reflects the fact that they are dependent on the toolset.
Explicit Registration: In tools.preset.default, there is now a method to register builtin subagents. This means they aren't automatically registered in every conversation; instead, they must be registered explicitly. While this adds a step for the SDK user, it is a more pragmatic approach.
Simplified Examples: I have updated the example accordingly. In my opinion, the current example is still too complex—simplifying it would be a great 'good first issue' for the community!
I updated the tests accordingly :-)

I updated the docs (OpenHands/docs#366)

enyst

Thank you!

Good points, let's play.

VascoSch92 added 2 commits February 25, 2026 17:08

add built-in agents

7037d55

add model key

d833cce

VascoSch92 requested a review from all-hands-bot February 25, 2026 16:15

VascoSch92 requested a review from simonrosenberg February 25, 2026 16:15

This comment was marked as outdated.

Sign in to view

update

ac534fd

VascoSch92 requested a review from all-hands-bot February 25, 2026 16:46

all-hands-bot approved these changes Feb 25, 2026

View reviewed changes

test: streamline builtin agent coverage

a9d8e83

- Simplify builtin agent tests (no mocks, focus on registry contracts) - Extend delegation example to demonstrate built-in explore/bash agents Co-authored-by: openhands <openhands@all-hands.dev>

This comment was marked as outdated.

Sign in to view

VascoSch92 and others added 2 commits February 26, 2026 10:13

Merge branch 'main' into vasco/issue-2051

9d18814

fix example and add logging

89d1c8d

This comment was marked as outdated.

Sign in to view

VascoSch92 mentioned this pull request Feb 26, 2026

fix(tools): merge subagents metrics (TaskToolSet) #2222

Merged

5 tasks

enyst reviewed Feb 26, 2026

View reviewed changes

examples/01_standalone_sdk/25_agent_delegation.py Outdated Show resolved Hide resolved

enyst reviewed Feb 26, 2026

View reviewed changes

openhands-sdk/openhands/sdk/subagent/registry.py Show resolved Hide resolved

Apply suggestion from @enyst

56c40c4

enyst reviewed Feb 26, 2026

View reviewed changes

examples/01_standalone_sdk/25_agent_delegation.py Show resolved Hide resolved

Merge branch 'main' into vasco/issue-2051

a4d4e77

VascoSch92 added 2 commits February 27, 2026 14:41

fix after accepting suggestion

2045091

refactoring after discussion

e1e3e04

VascoSch92 requested a review from all-hands-bot March 2, 2026 08:53

This comment was marked as outdated.

Sign in to view

feedbacks

cf99f54

VascoSch92 force-pushed the vasco/issue-2051 branch from 2aa8b1a to cf99f54 Compare March 2, 2026 09:04

enyst reviewed Mar 2, 2026

View reviewed changes

openhands-tools/openhands/tools/preset/subagents/default_cli.md Show resolved Hide resolved

update tests

8c649c6

enyst approved these changes Mar 2, 2026

View reviewed changes

simonrosenberg approved these changes Mar 2, 2026

View reviewed changes

Merge branch 'main' into vasco/issue-2051

32d8d1c

VascoSch92 enabled auto-merge (squash) March 2, 2026 15:42

VascoSch92 merged commit c31cdee into main Mar 2, 2026
23 checks passed

VascoSch92 deleted the vasco/issue-2051 branch March 2, 2026 15:49

Conversation

VascoSch92 commented Feb 25, 2026 • edited by github-actions bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Requirements

Checklist

Uh oh!

github-actions bot commented Feb 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

API breakage checks (Griffe)

Uh oh!

github-actions bot commented Feb 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment was marked as outdated.

Uh oh!

all-hands-bot left a comment

Choose a reason for hiding this comment

Uh oh!

enyst commented Feb 25, 2026

Uh oh!

openhands-ai bot commented Feb 25, 2026

Uh oh!

This comment was marked as outdated.

This comment was marked as outdated.

This comment was marked as outdated.

Uh oh!

Uh oh!

Uh oh!

github-actions bot commented Feb 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Agent server REST API breakage checks (OpenAPI)

Uh oh!

This comment was marked as outdated.

Uh oh!

This comment was marked as outdated.

Uh oh!

VascoSch92 commented Mar 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

enyst left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

VascoSch92 commented Feb 25, 2026 •

edited by github-actions bot

Loading

github-actions bot commented Feb 25, 2026 •

edited

Loading

github-actions bot commented Feb 25, 2026 •

edited

Loading

github-actions bot commented Feb 27, 2026 •

edited

Loading

VascoSch92 commented Mar 2, 2026 •

edited

Loading