Subagents

This page covers the active subagent API. The important point is that the current feature is a delegated parent-agent clone model, not a system for independently defined child agents.

Subagents are not defined in capability.yaml, and they are not separate agent markdown files. The current runtime API works like this:

1. define a normal parent Agent
2. attach create_subagent_tool(parent_agent)
3. let the parent call spawn_agent(...) when it needs focused delegated work

What Actually Gets Created

spawn_agent() does not look up a separate saved child agent. It clones the parent agent with parent_agent.with_(...), then overrides three fields:

• name
• instructions
• max_steps

By default, the child keeps the parent’s:

• model
• normal tools
• hooks
• most other runtime configuration

The cloned child starts with a fresh trajectory via reset(), and gets a copied tools list with SubAgentToolset removed so it cannot recursively spawn more subagents.

Note

planner, reviewer, and similar names in the examples are built-in runtime profiles, not manifest-defined child agents.

What This Feature Is

Use this when you want a parent agent to hand off one narrow task to a temporary delegated clone with different instructions.

Do not read this API as:

• a registry of separately defined child agents
• a manifest-level subagent declaration system
• a way to assign a distinct child-only toolset or model through docs-facing config

The Tool API

The toolset exposes one main method:

await subagents.spawn_agent(
    task="Find all auth middleware entry points",
    agent_type="explore",
    custom_instructions=None,
)

Arguments:

• task: the delegated task text
• agent_type: built-in profile name
• custom_instructions: optional override for the built-in profile instructions

The return value is a string summary containing:

• the subagent name
• the delegated task
• steps taken
• tokens used
• the final result text

Built-In Profiles

These profiles come from the runtime code today:

agent_type	Runtime name	max_steps	Use it for
explore	explorer	20	file search, code search, structure discovery
plan	planner	15	implementation design without changing code
test	tester	25	running tests and analyzing failures
review	reviewer	15	bug-finding and code review
general	assistant	30	anything else

Minimal Working Example

This is the smallest useful pattern:

from dreadnode.agents import Agent
from dreadnode.agents.subagent import create_subagent_tool


parent = Agent(
    name="lead",
    model="gpt-4o-mini",
    instructions="""
    You own the final answer.
    Use spawn_agent for narrow delegated work:
    - use explore for search and discovery
    - use plan for implementation design
    - use test for verification
    - use review for bug finding
    Summarize subagent results before replying.
    """,
)

subagents = create_subagent_tool(parent)
parent.tools.append(subagents)

result = await parent.chat(
    "Inspect the authentication flow, find the entry points, and propose where to add audit logging."
)

In this pattern, the parent agent decides when to call spawn_agent. You do not define a second agent in YAML for the delegated role.

Call It Directly From Python

If you want explicit control instead of relying on the parent LLM to choose delegation, call the tool method directly:

from dreadnode.agents import Agent
from dreadnode.agents.subagent import create_subagent_tool


parent = Agent(
    name="lead",
    model="gpt-4o-mini",
    instructions="Delegate narrow technical subtasks when it helps.",
)
subagents = create_subagent_tool(parent)

report = await subagents.spawn_agent(
    task="Find all capability loader entry points and summarize what they do.",
    agent_type="explore",
)

review = await subagents.spawn_agent(
    task="Review the loader for edge cases around unknown manifest keys.",
    agent_type="general",
    custom_instructions="""
    You are a capability-loader reviewer.
    Focus on ignored fields, backward-compatibility paths, and stale documentation.
    Return findings only.
    """,
)

Use custom_instructions when the built-in profile is close but not specific enough.

What You Need To Define Yourself

The code does not define a reusable child-agent registry. You still need to define:

• the parent agent instructions
• when delegation should happen
• which tools the child should inherit by leaving them on parent.tools
• how the parent should merge subagent output back into the final answer

Limits

• run_in_background exists on SubAgentToolset, but background execution is not implemented
• subagents cannot recursively spawn more subagents because the toolset is filtered out of the child tool list
• the helper does not define a separate child-only model, hooks list, or tool list
• this is runtime orchestration, not a manifest authoring feature

What To Prefer

• start with the documented v1 manifest in Custom Capabilities
• add multi-agent behavior at runtime with SubAgentToolset
• keep delegation rules in Python and parent-agent instructions, where they are explicit and testable