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
• Dedicated execution monitor - View detailed subagent activity, tool calls, and output in a focused monitoring panel
• Core tool access - Read files, execute commands, write files, and use MCP tools
• Parallel execution - Run multiple subagents simultaneously for efficient task execution
• Parallel and sequential execution - Run multiple subagents simultaneously, or chain them with dependencies using task graphs
• Finer permission control - Scope permissions per subagent with granular tool and trust settings
• 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
• code - Code intelligence (search symbols, find references)
• 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 subagent access

You can control which agents are available as subagents and which can run without permission prompts.

Restricting available agents

Use availableAgents to limit which agents can be spawned as subagents:

{
  "toolsSettings": {
    "subagent": {
      "availableAgents": ["reviewer", "tester", "docs-*"]
    }
  }
}

With this configuration, only the reviewer, tester, and agents matching docs-* can be used as subagents. Glob patterns are supported.

Trusting specific agents

Use trustedAgents to allow specific agents to run without permission prompts:

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

With this configuration, the orchestrator agent can spawn the reviewer, tester, and analyzer subagents without requiring user approval each time. Glob patterns like test-* are supported.

Combining both settings

You can use both settings together for fine-grained control:

{
  "toolsSettings": {
    "subagent": {
      "availableAgents": ["reviewer", "tester", "analyzer", "docs-*"],
      "trustedAgents": ["reviewer", "tester"]
    }
  }
}

This allows four agents to be spawned as subagents, but only reviewer and tester run without prompts.

Subagent execution monitor

Kiro provides a dedicated monitor for tracking subagent activity in real time. Press Ctrl+G to open the monitor. It shows each subagent's current status, tool calls, and output as it works through a task.

When a subagent is running, you can view its execution details — including which files it's reading, commands it's executing, and decisions it's making — without interrupting your main conversation. This is especially useful when running multiple subagents in parallel, as you can track each one independently and intervene if needed.

Inside the monitor, use Ctrl+D and Ctrl+U to navigate between subagents, and press q to return to the main chat.

Task dependencies

Subagents support breaking down complex tasks into a directed acyclic graph (DAG) where tasks can depend on each other. The main agent plans the full task graph upfront, then executes subagents in the right order — running independent tasks in parallel and waiting for dependencies before starting dependent ones.

For example, a refactoring workflow might look like:

  ┌─────────────┐
  │  1. Analyze  │
  │ dependencies │
  └──────┬───────┘
         │
  ┌──────▼───────┐
  │ 2. Refactor  │
  │   modules    │
  └──────┬───────┘
         │
  ┌──────▼───────┐
  │  3. Run and  │
  │  fix tests   │
  └──────────────┘

Step 2 waits for step 1 to complete. Step 3 waits for step 2. Independent tasks at the same level run in parallel.

> Refactor the auth module — analyze dependencies first, then refactor each service, then run tests

Finer permission control

You can now scope permissions at a more granular level per subagent, controlling not just which agents can be spawned but exactly which tools each subagent can use and what actions require approval.

Per-subagent tool restrictions

Restrict specific tools for individual subagents:

{
  "toolsSettings": {
    "subagent": {
      "availableAgents": ["reviewer", "deployer"],
      "trustedAgents": ["reviewer"],
      "agentPermissions": {
        "deployer": {
          "allowedTools": ["read", "shell"],
          "requireApproval": ["shell"]
        }
      }
    }
  }
}

This gives the deployer subagent access to only read and shell tools, and requires user approval before any shell command executes — even if the parent agent is trusted.

agentPermissions fields

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