Subagents

Subagents are specialized agents that can autonomously execute complex tasks on your behalf. They have their own context, tool access, and decision-making capabilities, making them ideal for sophisticated multi-step operations.

Key capabilities

• Autonomous execution - Run independently with their own context, with the level of autonomy depending on agent configuration
• Live progress tracking - Monitor real-time status updates as subagents work through tasks
• Core tool access - Read files, execute commands, write files, and use MCP tools
• Parallel execution - Run multiple subagents simultaneously for efficient task execution
• Result aggregation - Results automatically returned to the main agent when complete

Default subagent

Kiro includes a default subagent that can handle general-purpose tasks. When you assign a task to a subagent, the default subagent is used unless you specify a custom agent configuration.

Custom subagents

You can spawn subagents using your own agent configurations. This allows you to create specialized subagents tailored to specific workflows:

> Use the backend agent to refactor the payment module

To use a custom agent as a subagent, reference it by name when assigning tasks. The subagent will inherit the tool access and settings from that agent's configuration.

How subagents work

1. Task assignment - You describe a task, and Kiro determines if a subagent is appropriate
2. Subagent initialization - The subagent is created with its own context and tool access based on its agent configuration
3. Autonomous execution - The subagent works through the task independently, though it may pause to request user approval for certain tool permissions
4. Progress updates - You receive live progress updates showing current work
5. Result return - When complete, results are returned to the main agent

Tool availability

Subagents run in a separate runtime environment. Some tools available in normal chat are not yet implemented in subagents.

Available tools:

• read - Read files and directories
• write - Create and edit files
• shell - Execute bash commands
• MCP tools

Not available:

• web_search - Web research
• web_fetch - Fetch URLs
• introspect - CLI info
• thinking - Reasoning tool
• todo_list - Task tracking
• use_aws - AWS commands
• grep - Search file contents
• glob - Find files by pattern

Configuring trusted subagent execution

You can configure specific agents to run without permission prompts by adding them to the allowedAgents list in your agent configuration's toolsSettings:

{
  "name": "orchestrator",
  "description": "Agent that coordinates multiple specialized subagents",
  "tools": ["fs_read", "subagent"],
  "toolsSettings": {
    "subagent": {
      "allowedAgents": ["reviewer", "tester", "analyzer"]
    }
  },
  ...
}

With this configuration, the orchestrator agent can spawn the reviewer, tester, and analyzer subagents without requiring user approval each time. This is useful for workflows where certain agents frequently delegate to trusted specialized agents.

Best practices

1. Use for complex tasks - Most valuable for multi-step operations that benefit from isolation
2. Provide clear instructions - Specific task descriptions lead to better results
3. Monitor progress - Check on long-running subagents periodically
4. Review results - Verify subagent output before acting on recommendations

Troubleshooting