Tutorial 22: Subagent Delegation

This is part of the Hermes Agent official tutorial series. View all tutorials

Imagine you’re the team lead on a project. You could do everything yourself, but that’s slow. Instead, you hand out specific tasks to your teammates, give them the details they need, and wait for them to report back. That’s exactly what Subagent Delegation does for Hermes Agent — it lets your main agent hire temporary “workers” to handle tasks in the background.

---

Step 1: Understand the Basic Idea

When you call delegate_task, Hermes creates one or more child agents (subagents). Each child:

• Gets a completely fresh conversation — it knows nothing about your chat history.
• Has access to the same tools as the parent agent.
• Runs in its own isolated terminal session.
• Returns only a final summary to the parent.

Think of it like sending a colleague to research a topic. They don’t sit through your entire meeting — you just hand them a note with the task and context, and they come back with a report.

---

Step 2: Delegate a Single Task

The simplest use case: one task, one subagent.

delegate_task(
    goal="Debug why tests fail",
    context="Error: assertion in test_foo.py line 42"
)

The goal tells the subagent what to do. The context gives it everything it needs to do it.

---

Step 3: Delegate Multiple Tasks in Parallel

Need several things done at once? Pass a list of tasks. By default, Hermes runs up to 3 subagents concurrently (you can change this — there’s no hard limit).

delegate_task(tasks=[
    {"goal": "Research topic A", "context": "Focus on recent primary sources"},
    {"goal": "Research topic B", "context": "Compare the leading explanations"},
    {"goal": "Fix the build", "context": "Project root: /home/user/project"}
])

Each subagent works independently. The parent waits for all of them, then combines the results.

---

Step 4: The Golden Rule — Subagents Know Nothing

This is the most important point, so listen up:

Subagents start with zero knowledge of your conversation.

If you say “Fix the error” without explaining what “the error” is, the subagent will be lost. You must pass all necessary context in the goal and context fields.

Here’s a bad example:

# BAD - subagent has no idea what "the error" is
delegate_task(goal="Fix the error")

And the good version:

# GOOD - subagent has all context it needs
delegate_task(
    goal="Fix the TypeError in api/handlers.py",
    context="""The file api/handlers.py has a TypeError on line 47:
    'NoneType' object has no attribute 'get'.
    The function process_request() receives a dict from parse_body(),
    but parse_body() returns None when Content-Type is missing.
    The project is at /home/user/myproject and uses Python 3.11."""
)

Think of the context as a briefing document. The more specific you are, the better the subagent’s work will be.

---

Step 5: Use It for Real-World Workflows

Parallel Research

Gather information on multiple topics at once:

delegate_task(tasks=[
    {
        "goal": "Research the current state of WebAssembly in 2025",
        "context": "Focus on: browser support, non-browser runtimes, language support"
    },
    {
        "goal": "Research the current state of RISC-V adoption in 2025",
        "context": "Focus on: server chips, embedded systems, software ecosystem"
    },
    {
        "goal": "Research quantum computing progress in 2025",
        "context": "Focus on: error correction breakthroughs, practical applications, key players"
    }
])

Code Review + Fix

Hand off a full review-and-fix job to a fresh context:

delegate_task(
    goal="Review the authentication module for security issues and fix any found",
    context="""Project at /home/user/webapp.
    Auth module files: src/auth/login.py, src/auth/jwt.py, src/auth/middleware.py.
    The project uses Flask, PyJWT, and bcrypt.
    Focus on: SQL injection, JWT validation, password handling, session management.
    Fix any issues found and run the test suite (pytest tests/auth/)."""
)

---

Summary

Subagent delegation is your way to parallelize work in Hermes Agent. Remember these key points:

• Use delegate_task for one task or a batch of tasks.
• Always provide full context — subagents start from scratch.
• Up to 3 concurrent subagents by default, configurable if you need more.
• Each subagent returns a structured summary — what it did, what it found, files changed, issues encountered.

It’s like having a team of assistants who only know what you tell them — so tell them everything they need.

---

Next up: Tutorial 23 — we’ll explore how to chain multiple delegations and combine their results into a single, polished output. Stay tuned!