Skip to main content

​
Overview

Agent delegation allows a main agent to spawn multiple sub-agents and delegate tasks to them for parallel processing. Each sub-agent runs independently with its own conversation context and returns results that the main agent can consolidate and process further. This pattern is useful when:
  • Breaking down complex problems into independent subtasks
  • Processing multiple related tasks in parallel
  • Separating concerns between different specialized sub-agents
  • Improving throughput for parallelizable work

​
Quick Start

This example is available on GitHub: examples/01_standalone_sdk/25_agent_delegation.py
examples/01_standalone_sdk/25_agent_delegation.py
"""
Agent Delegation Example

This example demonstrates the agent delegation feature where a main agent
delegates tasks to sub-agents for parallel processing.
Each sub-agent runs independently and returns its results to the main agent,
which then merges both analyses into a single consolidated report.
"""

import os

from pydantic import SecretStr

from openhands.sdk import (
    LLM,
    Agent,
    Conversation,
    Tool,
    get_logger,
)
from openhands.sdk.tool import register_tool
from openhands.tools.delegate import DelegateTool
from openhands.tools.preset.default import get_default_tools


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", "openhands/claude-sonnet-4-5-20250929")
llm = LLM(
    model=model,
    api_key=SecretStr(api_key),
    usage_id="agent",
)

cwd = os.getcwd()

register_tool("DelegateTool", DelegateTool)
tools = get_default_tools(enable_browser=False)
tools.append(Tool(name="DelegateTool"))

main_agent = Agent(
    llm=llm,
    tools=tools,
)
conversation = Conversation(
    agent=main_agent,
    workspace=cwd,
)

task_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? "
    "Activities: what are the top 5 must-see attractions and hidden gems? "
    "Please use the delegation tools to handle these two tasks in parallel. "
    "Make sure the sub-agents use their own knowledge "
    "and dont rely on internet access. "
    "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()
Running the Example
export LLM_API_KEY="your-api-key"
cd agent-sdk
uv run python examples/01_standalone_sdk/25_agent_delegation.py

​
How It Works

The delegation system consists of two main operations:

​
1. Spawning Sub-Agents

Before delegating work, the agent must first spawn sub-agents with meaningful identifiers: 
# Agent uses the delegate tool to spawn sub-agents
{
    "command": "spawn",
    "ids": ["lodging", "activities"]
}
Each spawned sub-agent:
  • Gets a unique identifier that the agent specify (e.g., “lodging”, “activities”)
  • Inherits the same LLM configuration as the parent agent
  • Operates in the same workspace as the main agent
  • Maintains its own independent conversation context

​
2. Delegating Tasks

Once sub-agents are spawned, the agent can delegate tasks to them: 
# Agent uses the delegate tool to assign tasks
{
    "command": "delegate",
    "tasks": {
        "lodging": "Find the best budget-friendly areas to stay in London",
        "activities": "List top 5 must-see attractions and hidden gems in London"
    }
}
The delegate operation:
  • Runs all sub-agent tasks in parallel using threads
  • Blocks until all sub-agents complete their work
  • Returns a single consolidated observation with all results
  • Handles errors gracefully and reports them per sub-agent

​
Setting Up the DelegateTool

​
1. Register the Tool

from openhands.sdk.tool import register_tool
from openhands.tools.delegate import DelegateTool

register_tool("DelegateTool", DelegateTool)

​
2. Add to Agent Tools

from openhands.sdk import Tool
from openhands.tools.preset.default import get_default_tools

tools = get_default_tools(enable_browser=False)
tools.append(Tool(name="DelegateTool"))

agent = Agent(llm=llm, tools=tools)

​
3. Configure Maximum Sub-Agents (Optional)

The user can limit the maximum number of concurrent sub-agents: 
from openhands.tools.delegate import DelegateTool

class CustomDelegateTool(DelegateTool):
    @classmethod
    def create(cls, conv_state, max_children: int = 3):
        # Only allow up to 3 sub-agents
        return super().create(conv_state, max_children=max_children)

register_tool("DelegateTool", CustomDelegateTool)

​
Tool Commands

​
spawn

Initialize sub-agents with meaningful identifiers. Parameters:
  • command: "spawn"
  • ids: List of string identifiers (e.g., ["research", "implementation", "testing"])
Returns: A message indicating the sub-agents were successfully spawned. Example: 
{
    "command": "spawn",
    "ids": ["research", "implementation", "testing"]
}

​
delegate

Send tasks to specific sub-agents and wait for results. Parameters:
  • command: "delegate"
  • tasks: Dictionary mapping sub-agent IDs to task descriptions
Returns: A consolidated message containing all results from the sub-agents. Example: 
{
    "command": "delegate",
    "tasks": {
        "research": "Find best practices for async code",
        "implementation": "Refactor the MyClass class",
        "testing": "Write unit tests for the refactored code"
    }
}