Skip to main content
The spawn tool allows agents to delegate complex or time-consuming tasks to background subagents that run independently.

​
Tool Name

spawn

​
Description

Spawn a subagent to handle a task in the background. Use this for complex or time-consuming tasks that can run independently. The subagent will complete the task and report back when done.

​
Parameters

​
task
string
required
The task description for the subagent to complete. Should be clear and self-contained.
​
label
string
Optional short label for the task (used for display and tracking). If not provided, a label is generated from the task description.

​
Return Value

Returns a confirmation message with the subagent ID, or an error message if spawning fails.

​
Configuration

SpawnTool(manager=subagent_manager)

​
Context Management

# Set the origin context for subagent messages
spawn_tool.set_context(
    channel="telegram",
    chat_id="123456"
)
Subagent messages are sent to the origin channel/chat when they complete or need to communicate.

​
Examples

​
Spawn Simple Task

{
  "task": "Analyze the log files in /var/log and create a summary report"
}
Returns: 
Spawned subagent 'Analyze the log files' (ID: sub_abc123)

​
Spawn with Custom Label

{
  "task": "Fetch the latest data from the API, process it, and generate visualizations",
  "label": "Data Pipeline"
}
Returns: 
Spawned subagent 'Data Pipeline' (ID: sub_def456)

​
Spawn Research Task

{
  "task": "Research the latest developments in quantum computing and create a 5-page report with citations",
  "label": "Quantum Research"
}
Returns: 
Spawned subagent 'Quantum Research' (ID: sub_ghi789)

​
Spawn Monitoring Task

{
  "task": "Monitor the server logs for errors every 5 minutes and alert if more than 10 errors occur",
  "label": "Log Monitor"
}
Returns: 
Spawned subagent 'Log Monitor' (ID: sub_jkl012)

​
How It Works

  1. Spawn: Parent agent calls spawn tool with task description
  2. Create: SubagentManager creates new agent instance with own tool access
  3. Execute: Subagent runs independently in background
  4. Report: Subagent sends results/messages to origin channel when complete
  5. Cleanup: Subagent terminates after completion

​
Subagent Lifecycle

┌─────────┐
│ Parent  │
│ Agent   │
└────┬────┘
     │ spawn(task)
     │
     ▼
┌─────────────┐
│  Subagent   │
│  Created    │
└──────┬──────┘
       │
       │ Execute task
       │ independently
       │
       ▼
┌─────────────┐
│  Running    │
│  in         │
│  Background │
└──────┬──────┘
       │
       │ Task complete
       │
       ▼
┌─────────────┐
│  Send       │
│  Results    │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│  Terminated │
└─────────────┘

​
Use Cases

​
Long-Running Operations

Spawn subagents for tasks that take significant time:
  • Large file processing
  • Multiple API calls with rate limits
  • Comprehensive research
  • System monitoring

​
Parallel Execution

Spawn multiple subagents to work in parallel: 
[
  {"task": "Analyze Q1 sales data", "label": "Q1 Analysis"},
  {"task": "Analyze Q2 sales data", "label": "Q2 Analysis"},
  {"task": "Analyze Q3 sales data", "label": "Q3 Analysis"},
  {"task": "Analyze Q4 sales data", "label": "Q4 Analysis"}
]

​
Isolation

Spawn subagents to isolate risky or experimental operations:
  • Testing new approaches
  • Potentially destructive operations
  • Resource-intensive tasks

​
Background Monitoring

Spawn subagents for continuous monitoring:
  • Log file watching
  • System health checks
  • Event detection

​
Best Practices

​
Clear Task Descriptions

Provide complete, self-contained task descriptions: ✅ Good: 
{
  "task": "Read the file /data/logs.txt, count errors by type, and create a CSV report at /data/error_summary.csv"
}
❌ Bad: 
{
  "task": "Process the logs"
}

​
Meaningful Labels

Use descriptive labels for tracking: 
{
  "task": "...",
  "label": "Sales Report Q1 2026"
}

​
When to Use

Spawn subagents when:
  • Task takes > 30 seconds
  • Parent agent has other work to do
  • Task is independent and self-contained
  • Need parallel execution

​
When NOT to Use

Don’t spawn subagents when:
  • Task is quick (< 10 seconds)
  • Result is needed immediately
  • Task requires interactive back-and-forth
  • Task depends on parent agent state

​
Subagent Capabilities

Subagents have access to:
  • All tools the parent agent has
  • Same configuration and restrictions
  • Own tool execution context
  • Ability to spawn further subagents (nested)

​
Limitations

  • Subagents run with same permissions as parent
  • No direct communication channel between parent and subagent during execution
  • Subagents cannot access parent agent’s conversation history
  • Resource limits apply to each subagent

​
Implementation

See nanobot/agent/tools/spawn.py:11 for the SpawnTool implementation. See nanobot/agent/subagent.py for the SubagentManager implementation.

Build docs developers (and LLMs) love

Get started for freeTalk to us