Hey all, I just wanted to say a few words about sub-agents, as there has been some confusion. The main agent can call or delegate to sub-agents using a tool.

openhands.tools

has two tools for this:

DelegationTool

and

TaskToolSet

. Why are there two tools, and how do they differ?

DelegationTool

is the older version, while TaskToolSet is the newer one. Both accomplish the same thing but in different ways (they have different underlying architectures). The architecture of

TaskToolSet

is very similar to the one CC is using.

┌─────────────────────┬────────────────────────────────────────────┬────────────────────────────────────────────┐                                                                                                  
  │ Aspect              │ DelegateTool                               │ TaskToolSet                                │                                                                                                  
  ├─────────────────────┼────────────────────────────────────────────┼────────────────────────────────────────────┤                                                                                                  
  │ Philosophy          │ Pool of named workers you manage           │ On-demand task execution                   │                                                                                                  
  │ Commands            │ Two-phase: spawn then delegate             │ Single task command                        │                                                                                                  
  │ Agent Identification│ User-defined string IDs ("research")       │ Auto-generated IDs ("task_00000001")       │                                                                                                  
  │ Agent Creation      │ Explicit spawn with ids & agent_types      │ Implicit — agent created per task          │                                                                                                  
  │ Task Assignment     │ Dict mapping: {"id1":"task..."}            │ Single: prompt="...", subagent_type="..."  │                                                                                                  
  │ Parallelism         │ Native — multiple tasks run in parallel    │ Sequential per call, LLM can multi-invoke  │                                                                                                                                                                                                                                                                                                 
  │ Sub-agent Persist.  │ Long-lived across multiple delegate calls  │ Per-task — evicted after completion        │                                                                                                  
  │ Resume Support      │ Implicit — same ID reuses conversation     │ Explicit — resume="task_00000001"          │                                                                                                  
  │ State Management    │ Stateful pool in _sub_agents dict          │ TaskManager evicts after completion        │                                                                                                  
  │ Confirmation        │ confirmation_handler callback              │ confirmation_handler callback              │                                                                                                  
  │ Visualizer          │ Yes — create_sub_visualizer()              │ Yes — create_sub_visualizer()              │                                                                                                  
  │ Metrics Tracking    │ Synced under delegate:{agent_id}           │ Synced under task:{task_id}                │
  │ Persistence Dir     │ Inherits under subagents/                  │ Inherits under subagents/ or temp dir      │                                                                                                  
  │ Complexity          │ Higher (spawn + delegate workflow)          │ Lower (single call)                       |                                                                                                 
  │ Control             │ More explicit                              │ More automated                             │                                                                                                  
  └─────────────────────┴────────────────────────────────────────────┴────────────────────────────────────────────┘

I will recommend using the

TaskToolSet

because: • It has been evaluated against five benchmarks, meaning we have iterated on it to fix bugs and ensure it works well with the main agent. • The Tool API is simpler: It requires only a single call to create and run a task. • If we want to implement background sub-agents, the

TaskToolSet

already has the necessary architecture. • Parallelism: While not as "native" as

DelegationTool

, the LLM can invoke multiple task tools in parallel, which covers most use cases.

Is there a good way to direct the agent to use one tool over the other?

And is there any reason to keep DelegationTool?

Is there a good way to direct the agent to use one tool over the other?

Just give one tool to the agent, not both.

And is there any reason to keep DelegationTool?

There is just one problem: the CLI already provides the

DelegationTool

to the agent. If we delete it or replace it with

TaskToolSet

, we will run into backward-compatibility issues with persisted conversations. Currently, our system allows us to add tools, but not to replace or delete them. However, I believe we can find a strategy to work around this.

You can mark it as deprecated with a deadline, and we can remove it afterwards

Can we really do that with tools... and their specific events?

Yeah, we’ll need to have a way to handle this, but never changing our tool set is not the answer 🙂

The answer currently in that PR is: always read those events; map them to something innocently-ish, in this case "view".

Solution for the CLI: • if the persisted convo has the DelegationTool: add in the tool set the delegationn tool and not the TaskSetTool • if no DelegationTool in the convo: add the TaskToolSet At the same time we deprecate the DelegationTool. Is this possible? For the cloud: We don't have subagents now, so we already start with TaskToolSet

That sounds good to me!

Sounds reasonable to me too, but I also wonder if we could generalize this so in the future if we encounter a similar issue we can use the same mechanism

@nutritious-balloon-65098 Please open 4 issues: • OpenHands/OpenHands-CLI: Replace

DelegateTool

with

TaskToolSet

for the main agent. • OpenHands/OpenHands-CLI: Ensure backward compatibility for persisted conversations with the new tool (as explained in Slack). • OpenHands/software-agent-sdk: Deprecate the

DelegateTool

. • OpenHands/software-agent-sdk: Research strategies for updating the toolset while maintaining backward compatibility with persisted sessions (e.g., look into Codex and Claude Code implementations).

I'm on it! Vasco can track my progress here.

Alternative: • summarize old conversations when such mismatch exists • use the NEW tools +

summary

• ... done?