Lesson 8
Sub-agents
What Sub-agents Are
A sub-agent is a separate agent instance that Kiro spawns to handle a focused task. It runs in its own isolated context window - meaning it doesn't share the main conversation's history, and its work doesn't pollute the main agent's context.
When it finishes, it returns its results to the main agent, which incorporates them into the conversation.
Why They Exist
Two problems they solve:
- Context preservation - if Kiro needs to read 20 files to answer a question, doing that in the main conversation eats your context budget. A sub-agent does the exploration in its own window, then returns a concise summary. Your main context stays lean.
- Parallelism - Kiro can run multiple sub-agents at the same time. "Update the tests AND update the docs" can happen concurrently rather than sequentially.
The Built-in Sub-agents
Kiro has several built-in sub-agents in the IDE. The two you'll encounter most often:
| Sub-agent | Purpose | When Kiro uses it |
|---|---|---|
| Context gatherer | Explores the codebase to find relevant files and understand structure | When it needs to understand an unfamiliar area before making changes |
| General purpose | Executes any task - code changes, file operations, research | When parallelising independent tasks |
There are also specialised built-in sub-agents for tasks like creating custom agent configurations and performing semantic code reviews. Each has its own context window, tools, and decision-making. They can read files, run commands, and make changes - same capabilities as the main agent.
Automatic vs Manual Launch
Automatic
Kiro decides on its own when to use sub-agents. For complex tasks, it may spin up a context gatherer to explore before acting, or launch parallel general-purpose agents to work on independent parts simultaneously. You don't need to ask - it happens transparently.
You'll see sub-agent activity in the chat as collapsible sections showing what each agent did.
Manual
You can explicitly instruct Kiro to use sub-agents:
- "Run subagents to update the unit tests and the documentation in parallel"
- "Use a subagent to explore how the auth service works, then come back and fix this bug"
- "Investigate files X, Y, and Z in parallel"
When you say "in parallel" or "use subagents", Kiro takes the hint and delegates accordingly.
Context Isolation: The Key Mechanic
This is the important part to understand. Each sub-agent gets:
- Its own fresh context window
- Access to the same tools (file read/write, bash, MCP tools, etc.)
- A prompt describing what it needs to do
- Optionally, specific files pre-loaded for reference
What it does NOT get:
- The main conversation's history
- Results from other sub-agents running in parallel
- Awareness of what the main agent is doing at the same time
Custom Sub-agents
Beyond the two built-in ones, you can create custom sub-agents for specialised tasks. This is where it connects to Custom Agents (covered in Lesson 9) - you define an agent configuration with specific tools, MCP servers, and prompts, then Kiro can spawn it as a sub-agent when relevant.
Example use cases for custom sub-agents:
- A frontend agent that knows about your Angular components and browser tooling
- A backend agent that has access to your database MCP server and API docs
- A test agent that specialises in writing and running tests
- A docs agent that updates documentation following your team's format
Each stays focused on its domain, managing its own context efficiently.
When Sub-agents Help vs. When They Don't
| Good use cases | Don't bother when |
|---|---|
| Exploring unfamiliar code before making changes | The task is simple and linear |
| Independent tasks that can run in parallel | Tasks are tightly dependent on each other |
| Keeping main context clean during research | You need to see every step interactively |
| Large-scale changes across many files | You're editing one file |
| Different domains (frontend + backend) simultaneously | Everything is in one domain |
What You See in the UI
When sub-agents run, you'll see:
- A collapsible section in the chat showing each sub-agent's work
- Real-time updates as sub-agents read files, run commands, and make changes
- The final result integrated into the main conversation when they complete
Sub-agents are only available in Autopilot mode - they don't run in Supervised mode (where you approve each action individually).
Practical Example
You ask: "Refactor the user service to use signals instead of BehaviorSubjects"
Kiro might:
- Launch a context gatherer sub-agent to find all files that use
UserServiceand understand the dependency graph - Based on the gathered context, plan the refactor
- Launch parallel general-purpose sub-agents to:
- Update the service itself
- Update the components that consume it
- Update the related tests
- Synthesize the results back into the main conversation
You see one coherent result, but the work was distributed across multiple agents with isolated contexts.
Your Tangible Win
You now understand what sub-agents are, why context isolation matters, how to trigger them manually, and when they're worth using. You know the two built-in types (context gatherer and general purpose) and that custom sub-agents are possible for specialised domains.