agent_tool - Sub-Agent Management

Overview

The agent_tool creates and manages specialized sub-agents for complex task delegation with controlled tool access and context isolation. Sub-agents are independent AI instances with specific capabilities and expertise that can handle particular types of tasks.

Tool Name

• Internal Name: agent_tool
• Display Name: Agent Tool
• Icon: Users

Parameters

Required Parameters

Parameter	Type	Description
agentType	string	Type of sub-agent to create. See available types below.
task	string	Specific task for the sub-agent to complete. Be clear and detailed about what you want accomplished.

Optional Parameters

Parameter	Type	Default	Description
context	string	"partial"	Level of context sharing. "partial" shares relevant context, "full" shares complete conversation, "minimal" shares only the task.
maxTurns	number	15	Maximum conversation turns for the sub-agent. Higher values allow more complex tasks but use more resources. Range: 1-50.
priority	string	"normal"	Priority level for resource allocation. Options: "high", "normal", "low".
timeoutMs	number	300000	Timeout in milliseconds for sub-agent execution. Range: 30000-1800000 (30s-30min).

Available Agent Types

1. Architect

• Type: "architect"
• Use: When repository is large/unknown or you need a structural map before acting
• Deliverable: docs/architecture.md with repo map (directories, key modules, data flows, dependency hotspots)
• Tools: read_file, search_file_content, glob, write_file
• Note: Does not modify code; writes single architecture artifact and stops

2. SpecFlow

• Type: "specflow"
• Use: End-to-end feature/bug work with Plan → Review → Execute workflow
• Deliverable: Concrete plan, minimal safe diffs, and verification notes; avoids shell by default
• Tools: read_file, search_file_content, glob, write_file

3. Refactor

• Type: "refactor"
• Use: Pattern-wide changes across many files with strict consistency and small batches
• Deliverable: Set of precise edits with rationale and rollback notes
• Tools: read_file, search_file_content, glob, write_file

4. Researcher

• Type: "researcher"
• Use: When external knowledge is required (APIs, libraries, benchmarks)
• Deliverable: docs/research/<topic>.md with sources and syntheses
• Tools: web_search, web_fetch, read_file, write_file

5. Debug Analyzer

• Type: "debug-analyzer"
• Use: Systematic problem investigation, error analysis, and troubleshooting
• Deliverable: Comprehensive debugging report with root cause analysis and solution verification
• Tools: read_file, search_file_content, glob, write_file
• Focus: Evidence-based analysis and maintaining system stability during investigation

Orchestration Patterns

Large/Unknown Repo

1. Call Architect to create docs/architecture.md
2. Hand off to SpecFlow with concrete plan referencing that artifact

Pattern-wide Change

Use Refactor with crisp spec and examples; prefer batched changes with verification between batches

External Knowledge Needed

Call Researcher first; archive findings, then proceed with SpecFlow/Refactor

Natural Stop

• Stop when plan is fully executed or after two consecutive no-op steps
• If task grows large, save current stage artifact and stop with next steps

Usage Examples

Create Architecture Documentation

{
  "agentType": "architect",
  "task": "Analyze this Node.js project structure and create architecture documentation including main modules, dependencies, and data flows",
  "context": "partial",
  "maxTurns": 20
}

Implement New Feature

{
  "agentType": "specflow",
  "task": "Implement user authentication feature including login, registration, and password reset. Follow existing code style and architecture patterns",
  "context": "full",
  "maxTurns": 30,
  "priority": "high"
}

Refactor Code

{
  "agentType": "refactor",
  "task": "Refactor all components from class components to function components using React Hooks. Maintain functionality and add appropriate tests",
  "context": "partial",
  "maxTurns": 25
}

Research Technical Solution

{
  "agentType": "researcher",
  "task": "Research React state management solutions (Redux, MobX, Zustand, Recoil), compare pros/cons, and recommend best fit for our project",
  "context": "minimal",
  "maxTurns": 15
}

Debug Issue

{
  "agentType": "debug-analyzer",
  "task": "Investigate why the application occasionally experiences memory leaks in production. Analyze logs, code, and configuration to find root cause and provide solution",
  "context": "full",
  "maxTurns": 20,
  "priority": "high"
}

Return Value

The tool returns an object containing:

• llmContent: Sub-agent execution results
• returnDisplay: User-friendly display information
• summary: Operation summary
• artifacts: Generated documents or files (if any)

Context Levels

Minimal

• Only shares task description
• Suitable for independent tasks
• Fastest execution
• Least resource usage

Partial

• Shares relevant context information
• Balances performance and context understanding
• Recommended for most tasks

Full

• Shares complete conversation history
• Best context understanding
• Suitable for complex tasks
• Uses more resources

Best Practices

1. Choose Right Agent Type: Select based on task nature
2. Clear Task Description: Provide detailed expectations and constraints
3. Reasonable Parameters: Adjust maxTurns and timeout based on complexity
4. Context Management: Use minimal for independent tasks, full for complex ones
5. Monitor and Adjust: Check output and adjust parameters as needed

Related Tools

• read_file: Commonly used by sub-agents for file reading
• write_file: Commonly used by sub-agents for file writing
• search_file_content: Commonly used by sub-agents for searching
• run_shell_command: May be used by some agents for command execution