Subagent Tool

​

subagent

​

Input Parameters

​

Response

Subagent task completed:
Label: {label}
Iterations: {iteration_count}
Result: {full_output}

​

Usage Examples

{
  "task": "Read the package.json file and list all dependencies"
}

{
  "task": "Analyze the /src directory and create a summary of the code structure",
  "label": "code-analysis"
}

{
  "task": "1. Search the web for the latest Python best practices. 2. Create a checklist based on the findings. 3. Save the checklist to checklist.md",
  "label": "python-checklist"
}

​

Execution Flow

1. Task initialization:
   • Subagent receives task description
   • System prompt configures independent operation
   • Full tool registry access granted
2. Tool loop execution:
   • Maximum iterations: 10 (configurable)
   • LLM model: Same as parent agent
   • Tools: Full access to all registered tools
   • Options: max_tokens: 4096, temperature: 0.7
3. Result aggregation:
   • Final output captured from last iteration
   • Iteration count tracked
   • Results formatted for LLM and user
4. Synchronous return:
   • Main agent waits for completion
   • Full results returned in ToolResult

​

System Prompt

You are a subagent. Complete the given task independently and provide a clear, concise result.

• Independent operation without parent context pollution
• Focus on task completion
• Clear result communication

​

Tool Access

• Filesystem tools (read_file, write_file, list_dir)
• Shell execution (exec)
• Web tools (web_search, web_fetch)
• Hardware tools (i2c, spi) if available
• Image generation (generate_image) if configured
• Recursive subagent spawning (use with caution)

​

Error Conditions

• task is required - Missing task parameter (with error object)
• Subagent manager not configured - Manager is nil (with error object)

• Subagent execution failed: {error} - Tool loop failed or timed out (with error object)

• IsError: true flag
• Err field set with error object
• Error message in both ForLLM and ForUser (truncated for user)

​

Response Format

{
  "ForLLM": "Subagent task completed:\nLabel: code-analysis\nIterations: 5\nResult: Found 23 files in /src directory. Main components: auth/ (3 files), api/ (8 files), utils/ (12 files). All files use TypeScript with strict mode enabled.",
  "ForUser": "Found 23 files in /src directory. Main components: auth/ (3 files), api/ (8 files), utils/ (12 files). All files use TypeScript with strict mode enabled.",
  "Silent": false,
  "IsError": false,
  "Async": false
}

{
  "ForLLM": "Subagent execution failed: context deadline exceeded",
  "ForUser": "Subagent execution failed: context deadline exceeded",
  "Silent": false,
  "IsError": true,
  "Async": false,
  "Err": "context deadline exceeded"
}

​

Performance Characteristics

• Depends on task complexity and tool calls
• Maximum iterations: 10 (can complete earlier)
• Each iteration: ~1-10 seconds (model-dependent)
• Typical range: 5-60 seconds

• Creates new conversation context (isolated from parent)
• LLM tokens: ~500-4000 per iteration
• Memory: Minimal overhead per subagent
• Concurrent subagents: Limited by system resources

​

Comparison: Subagent vs Parent Execution

​

Best Practices

• ✅ Isolated, well-defined subtasks
• ✅ Tasks requiring multiple tool calls
• ✅ Parallel execution of independent operations
• ✅ Complex multi-step procedures

• ❌ Simple single-tool operations (use tool directly)
• ❌ Tasks requiring user interaction
• ❌ Operations needing conversation context
• ❌ Recursive or deeply nested tasks

{"task": "Read config.json, extract the database connection string, and validate it's in correct format"}
{"task": "Search for TypeScript best practices published in 2024 and summarize top 5 recommendations"}
{"task": "List all .go files in /src, count total lines of code, and save report to stats.txt"}

{"task": "Help me"}
{"task": "Do something with the files"}
{"task": "Figure out what to do"}

• Use kebab-case: code-analysis, web-research
• Keep short: 2-4 words
• Descriptive: dependency-check not task1

​

Advanced Usage

// Parent agent spawns 3 subagents for parallel analysis
[
  {"task": "Analyze /src for TypeScript files", "label": "ts-analysis"},
  {"task": "Analyze /src for test coverage", "label": "test-analysis"},
  {"task": "Analyze /src for documentation", "label": "doc-analysis"}
]

1. Spawn subagent for task A → Get result A
2. Spawn subagent for task B → Get result B
3. Synthesize final answer from A + B

​

Implementation Details

• Manages subagent lifecycle
• Tracks active tasks (ID, status, result)
• Provides tool registry to subagents
• Handles message bus communication

manager := NewSubagentManager(
  provider,      // LLM provider
  "claude-4.5", // Model name
  "/workspace",  // Workspace directory
  messageBus,    // Optional message bus
)

tool := NewSubagentTool(manager)
tool.SetContext("cli", "session-123")

ToolLoopConfig{
  Provider:      manager.provider,
  Model:         manager.defaultModel,
  Tools:         manager.tools,
  MaxIterations: 10,
  LLMOptions: {
    "max_tokens":  4096,
    "temperature": 0.7,
  },
}

​

Testing

• ✅ Name and description verification
• ✅ Parameter schema validation
• ✅ Context setting
• ✅ Successful task execution
• ✅ Execution without label (unnamed)
• ✅ Missing task parameter error
• ✅ Nil manager error handling
• ✅ Context passing verification
• ✅ ForUser truncation (500 char limit)

"Task completed: {task_description}"

• Subagent receives correct task
• Results are properly formatted
• Error handling works correctly