Using Sub Agents with Kiro CLI

If you already use Kiro CLI daily, you know it handles direct tasks well: editing files, running commands, analyzing code. But what about when the task is complex, with several independent steps? That's where sub agents come in.

In this post I'll explore in depth how they work, when they make sense, orchestration patterns and the precautions you need to take to get the most out of this feature.

What are Sub Agents?

Sub agents are specialized agents that Kiro CLI can invoke to execute subtasks in an isolated and parallel manner. Think of them as "workers" that the main agent recruits on demand.

Each sub agent has:

• Its own context: it can't see the main conversation or other sub agents
• Specialized toolset: it can have different tools from the main agent
• Independent execution: runs in parallel without blocking the flow

The main agent works as an orchestrator. It decides what to delegate, fires off the sub agents, waits for results and consolidates everything into a coherent response for you.

How it works under the hood

The lifecycle of a call with sub agents follows this flow:

1. Agent discovery

Before delegating, the main agent runs a ListAgents to find out which specialized agents are available and what tools each one offers. This is important because not every sub agent is suited for every task.

2. Parallel invocation

With the agents mapped out, the main agent uses InvokeSubagents passing an array of up to 4 simultaneous sub agents. Each invocation receives:

• query: the task the sub agent needs to execute
• agent_name (optional): which specific agent to use
• relevant_context (optional): additional context to help the sub agent understand the task

3. Isolated execution

Each sub agent runs with its own context. It doesn't know other sub agents exist, has no access to the main conversation and can't communicate with the others. This isolation is intentional: it avoids conflicts, keeps the context clean and enables real parallelism.

4. Consolidation

When all sub agents finish, the results return to the main agent. It analyzes each response, resolves possible conflicts and assembles the final response.

When to use Sub Agents

Ideal scenarios

Independent parallel analyses: you ask Kiro to analyze a Dockerfile's security, review IAM permissions and validate a CloudFormation template. These are 3 tasks with no dependency between them, perfect for running in parallel. Multi-source research: you need to search for information in different parts of the codebase at the same time. Each sub agent can explore a different directory or module. Independent artifact generation: creating a deploy script, an IAM policy and a configuration file at the same time. Each sub agent generates an artifact without depending on the others. Tools the main agent doesn't have: sometimes the sub agent has access to specific tools that the main agent doesn't. Delegating is the only way to access those capabilities.

When NOT to use

Sequential tasks with dependencies: if task B needs the result of task A, there's no point firing both together. Sub agent B won't have A's output because they don't communicate. Simple and quick tasks: for trivial things, the overhead of creating sub agents isn't worth it. The main agent solves it faster on its own. When shared context is essential: if the subtasks need to "talk" to each other or share intermediate state, sub agents aren't the right tool.

Orchestration patterns

Fan-out / Fan-in

The most common pattern. The main agent splits the task into N parts, fires N sub agents in parallel (fan-out), waits for all to finish and consolidates the results (fan-in).

Example: "Review all infrastructure files in the project"

1. The main agent lists the relevant files
2. Fires a sub agent for each file (up to 4 at a time)
3. Collects the reviews and presents a consolidated summary

Pipeline with parallel stages

When you have a sequence of steps, but within each step there are parallelizable tasks.

Example: "Analyze the project and then generate the documentation"

1. Stage 1 (parallel): sub agents analyze different project modules
2. The main agent consolidates the analysis
3. Stage 2 (parallel): sub agents generate docs for each module based on the consolidated analysis

On-demand specialist

The main agent identifies that it needs a specific capability that only a sub agent has and delegates on the spot.

Example: the main agent doesn't have access to a semantic search tool, but a sub agent does. It delegates the search and uses the result to continue the work.

Practical example: AWS security audit

Let's look at a real scenario. You have a project with AWS infrastructure and want a complete audit. The request would be something like:

"Run a security audit: review the IAM policies, analyze the security groups, check the S3 configurations and validate the CloudFormation."

Kiro CLI can solve this like so:

Round 1 (4 sub agents in parallel):

• Sub agent 1: analyzes IAM policies looking for excessive permissions
• Sub agent 2: reviews security groups looking for unnecessarily open ports
• Sub agent 3: checks S3 configurations (encryption, public access, versioning)
• Sub agent 4: validates CloudFormation against best practices

Consolidation: the main agent receives the 4 reports, identifies the most critical findings, cross-references information (e.g., a permissive policy + a public bucket = high risk) and delivers a unified report with prioritization.

Without sub agents, this would be sequential and take much longer. With them, all 4 analyses run at the same time.

Combining with the Planner Agent

Kiro CLI has another powerful feature: the Planner Agent, activated with Shift + Tab. It's read-only, meaning it only helps you think and structure, without making changes.

An efficient workflow combines both:

1. Planner Agent: you describe what you want to do and it breaks it into a structured plan with clear steps
2. Parallelism identification: looking at the plan, you (or the main agent) identify which steps are independent
3. Sub agents: the independent steps are delegated in parallel
4. Consolidation: results come back and feed into the next steps

This combination transforms Kiro from a reactive assistant into a parallel planning and execution tool.

Tips and best practices

Provide relevant context: use the relevant_context field to give the sub agent the information it needs. Remember it doesn't have access to the main conversation, so be explicit. Respect the limit of 4: you can fire at most 4 sub agents at a time. If you have more tasks, do them in rounds. Think about independence: before delegating, ask "does this task depend on the result of another?". If yes, don't put them in the same block. Use it to avoid context bloat: tasks that generate a lot of output (large file analysis, extensive searches) are great candidates for sub agents. The heavy context stays isolated and only the relevant result returns to the main agent. Don't force parallelism: not every task needs sub agents. If it's something simple and straightforward, let the main agent handle it. The overhead of creating sub agents only pays off for tasks that truly benefit from parallelism.

Conclusion

Sub agents are one of the most powerful features of Kiro CLI for those dealing with complex tasks. They transform the assistant from a sequential executor into a parallel orchestrator, capable of splitting work among specialized agents and consolidating results intelligently.

For those working with AWS infrastructure, this is especially useful: audits, security analyses, artifact generation and code reviews can run simultaneously, saving time without losing depth.

The key is understanding when parallelizing makes sense and when sequential flow is more appropriate. With that clarity, sub agents become a real productivity multiplier in your workflow.