Invoking as sub-agents - Custom agents - Features - Docs - Kiro Loading image... Product * About Kiro * IDE * CLI * Web * Mobile * Crew * Pricing * Downloads For * Enterprise * Startups * Students Community * Overview * Ambassadors * Discord * Events * Powers * Shop * Showcase Resources * Docs * Blog * Changelog * FAQs * Report a bug * Suggest an idea * Billing support Social * * * * * * * English Site Terms License Responsible AI Policy Legal Privacy Policy Cookie Preferences English Loading image... * Apps * CLI * Web * Enterprise * Pricing * Docs * Community * Resources SIGN IN DOWNLOADS Loading image... Get Started Installation Authentication Your first project Models Overview Available models Reasoning effort Features How Kiro works Specs Steering Hooks MCP Permissions Custom agents Built-in agents Creating custom agents Configuration reference Invoking as sub-agents Examples Troubleshooting Agent Skills Powers Cloud sessions Compaction Kiroignore Checkpoints and rewind Built-in tools Configuration scopes IDE 1.x What's new in 1.0 Setup & First Run Editor Chat Experimental Troubleshooting 0.x reference CLI What's new in 3.0 Setup & First Run Terminal UI Chat Voice mode Headless mode ACP Auto complete Experimental 2.x reference Crew Quick start Installation Running 24/7 Chat Agent Capabilities Features Interfaces Apps System & storage Configuration Security Troubleshooting Web Setup & First Run Identity Center Connect your repositories Working with the agent Autonomous mode Automations Memory Configuration Sync Sandbox Mobile - Preview Overview Commands and Reference CLI commands Slash commands Built-in tools Exit codes Settings Billing Overview Managing your subscription Upgrading your plan Downgrading your plan Cancelling your plan Purchasing add-on credits Managing your payments Managing usage notifications Managing your taxes Contacting billing support Deleting your account Related questions Enterprise Concepts Onboarding quickstart Connecting your identity provider Deployment options Subscribe your team Manage subscriptions Governance Monitor and track Settings Managed updates Billing IAM Supported regions Privacy and Security Overview Data protection Code references Compliance validation Infrastructure security IAM permissions Firewalls, proxies, and data perimeters VPC endpoints (AWS PrivateLink) Guides Overview Language support Learn by playing Migration Migrating from Q Developer Migrating from VSCode Upgrading from Q CLI * Docs * * Features * * Custom agents * * Invoking as sub-agents Copy page View as Markdown Invoking as sub-agents Copy page View as Markdown 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. Capability IDE CLI Web Mobile Automatic sub-agent invocation ✓ ✓ ✓ ✓ Explicit sub-agent invocation ✓ ✓ ✓ ✓ Custom agents as sub-agents ✓ ✓ ✓ — Parallel execution ✓ ✓ ✓ ✓ On Web, custom agents committed to .kiro/agents/ can be invoked as sub-agents, along with Kiro's built-in sub-agents . Mobile uses built-in sub-agents only. How sub-agents work * Task assignment - You describe a task (or the main agent identifies one that benefits from delegation) * Agent selection - Kiro selects the appropriate agent configuration based on the task and available agents * Isolated execution - The sub-agent runs with its own context window, tools, and permissions * 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 What sub-agents inherit Sub-agents share the workspace environment but run with isolated conversation context: Shared with main agent Isolated per sub-agent Steering files Conversation history MCP servers Context window Workspace file access Spec state Permissions configuration Hook triggers Built-in sub-agents 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. Parallel execution 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 Task dependencies 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 │ └──────────────┘ Info Task graphs are planned upfront and cannot be modified during execution. The agent determines the full DAG before any sub-agent starts running. Review loops 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 Tool availability 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. Custom orchestrator agents need the subagent tool If you're building a custom agent that will spawn sub-agents, include subagent in its tools array (or use @builtin ). Without it, the agent can't delegate. Configuring sub-agent access Control which agents can be spawned and which run without approval prompts using toolsSettings.subagent in your agent configuration : json { "toolsSettings" : { "subagent" : { "availableAgents" : [ "reviewer" , "tester" , "docs-*" ] , "trustedAgents" : [ "reviewer" , "tester" ] } } } Field Description availableAgents Glob patterns for agents this agent can spawn. Omit to allow all. trustedAgents Agents that run without permission prompts. To restrict the tools a sub-agent can use, configure tools in the sub-agent's own config file rather than in the parent. Surface-specific behavior IDE CLI Web Sub-agents run in parallel and the main agent waits until all complete before proceeding. Each sub-agent has its own context window. You can speed up development by leveraging sub-agents to perform multiple tasks simultaneously - for example, fetching and analyzing several tickets in parallel. Best practices * Use for complex tasks - Most valuable for multi-step operations that benefit from isolation or parallelism * Provide clear instructions - Specific task descriptions lead to better agent selection and results * Monitor progress - In CLI, use Ctrl+G to check on long-running sub-agents * Configure access - Use availableAgents and trustedAgents for orchestrator agents that spawn many sub-agents Troubleshooting Issue Solution Sub-agent not starting Verify the task description is clear and actionable Missing tool access Check the agent configuration's tools field Approval prompts blocking Add the agent to trustedAgents , or trust the subagent tool Main agent can't spawn sub-agents Add subagent to the orchestrator agent's tools array Incomplete results Provide more specific instructions or break into smaller tasks Page updated: September 2, 2026 Configuration reference Examples