Invoking as sub-agents

Sub-agents let you hand off focused tasks to agents that run in their own isolated context. The main agent spawns sub-agents when a task benefits from parallelism, specialized tools, or context isolation - then aggregates the results when they finish.

On Web and Mobile, the agent delegates to Kiro's built-in sub-agents only; custom agents defined in .kiro/agents/ can be invoked as sub-agents from the IDE and CLI.

1. Task assignment - You describe a task (or the main agent identifies one that benefits from delegation)
2. Agent selection - Kiro selects the appropriate agent configuration based on the task and available agents
3. Isolated execution - The sub-agent runs with its own context window, tools, and permissions
4. Result return - When finished, the sub-agent returns findings to the main agent

Any custom agent can be invoked as a sub-agent. The main agent automatically selects agents based on their description field, or you can request one explicitly:

Use the code-reviewer agent to analyze src/auth/ for security issues

Sub-agents share the workspace environment but run with isolated conversation context:

Kiro includes two internal sub-agents used automatically when appropriate:

• Context gathering - Explores your project structure and gathers relevant files and context
• General purpose - Handles parallelized tasks of any kind using the default agent configuration

You don't need to configure these - the main agent uses them as needed.

Sub-agents run in parallel, each working independently. This is useful for:

• Refactoring multiple files simultaneously
• Researching several topics in parallel
• Running independent analysis tracks

Refactor these three services to use the new auth middleware - do them in parallel

Sub-agents support directed acyclic graphs (DAGs) where tasks depend on each other. The main agent plans the full task graph upfront, then executes in the right order - running independent tasks in parallel and waiting for dependencies before starting dependent ones.

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

A stage can loop back to an earlier stage when its output signals that more work is needed - for example, a reviewer sends work back to an implementer for revisions.

Implement the feature, then have a reviewer check it and send it back for fixes until it passes

The agent builds a looping pipeline with:

• target - the stage to re-run when the loop triggers
• trigger - text in the stage output that fires the loop (e.g., NEEDS_CHANGES)
• max_iterations - safety cap (between 1 and 10)

Constraints:

• A stage cannot loop back to itself
• Mutual loops (A → B → A) are rejected
• The trigger must be at least four characters

The default sub-agent has the same built-in tools as the main agent - read, write, shell, web_search, web_fetch, and any configured MCP tools.

When you delegate to a custom agent, the sub-agent uses that agent's tools and permissions configuration. Tools not listed in the custom agent's config won't be available to the sub-agent.

Control which agents can be spawned and which run without approval prompts using toolsSettings.subagent in your agent configuration:

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

To restrict the tools a sub-agent can use, configure tools in the sub-agent's own config file rather than in the parent.

1. Use for complex tasks - Most valuable for multi-step operations that benefit from isolation or parallelism
2. Provide clear instructions - Specific task descriptions lead to better agent selection and results
3. Monitor progress - In CLI, use Ctrl+G to check on long-running sub-agents
4. Configure access - Use availableAgents and trustedAgents for orchestrator agents that spawn many sub-agents