Workflows: Background Agent Teams
Sub-agents (v2) run inside your session. A workflow runs a graph of agent steps in the background, each in its own fresh session, while your main chat stays free. A reviewer step does not inherit the coder's reasoning, which is the real point.
Turn it on
Workflows are opt-in. Set chat.enableWorkflows and restart the CLI:
kiro-cli settings chat.enableWorkflows true
Then ask in plain language ("Investigate how auth works here, in the background, and give me a cited summary") or run /workflow run. In V3 you approve the proposed plan before any step runs. Nothing starts on its own unless you ask.
Five ideas
| Idea | Meaning |
|---|---|
| Step | One agent, own session. Cannot read other steps' sessions |
| Handoff | Output or a declared artifact passes to a later step |
| Branch and join | Independent agents judge the same work; a policy combines results |
| Loop | Repeat until evidence matches or a cap is reached |
| Wait | Watch an external system without spending model turns |
Kiro ships three recipes: investigate (read-only), feature-pipeline and publish-pr. Recipe precedence: project .kiro/workflows/, then ~/.kiro/workflows/, then synced, then bundled.
A minimum recipe
{
"name": "plan-and-implement",
"description": "Plan a change, then implement it",
"inputs": { "task": "prompt" },
"steps": [
{ "type": "step", "id": "plan", "agent": "wf-planner",
"prompt": "Create an implementation plan for: {{task}}. Do not edit files." },
{ "type": "step", "id": "implement", "agent": "wf-coder",
"prompt": "Implement this plan, then run tests:\n\n{{previous.output}}" }
]
}
Save as .kiro/workflows/plan-and-implement.workflow.json, ask Kiro to run validate_workflow on it, then /workflow run plan-and-implement --task "...".
Every step goes through the same permission checks as any session, and the launching session's rules apply too, so an agent's own allow never grants more than you do. This is the lesson 1 sub-agent rule again. Workflows use more tokens than one session; keep small tasks in chat. Set a finite maxIterations on every repeat.
Retrieval check
Why does each workflow step run in its own fresh session?
Right. Fresh context gives independent judgment; steps pass only explicit handoffs.
Steps cannot read each other's sessions. Isolation lets a reviewer evaluate work without inheriting the coder's reasoning.
A step agent has an allow rule for git push, but your session does not. What happens?
Right. An agent's own allow never grants more than the launching session allows.
The launching session's policy still applies, and the most restrictive rule wins, so the agent rule grants nothing extra.
In the recipe above, how does implement receive the plan?
Right. The final message of the previous step is passed via a template.
Steps cannot read each other's sessions; handoffs travel through templates such as {{previous.output}}.
Practice
- Run the setting command above, restart
kiro-cli, and open a scratch repo. - Ask: "Use the investigate workflow to explain how this repo is built. Do not modify anything." Review the plan before approving.
- While it runs, keep chatting in the main thread. Open the monitor and select a step (Ctrl+G is the sub-agent monitor shortcut; check
/workflowfor yours). - Save the recipe above, validate it, and run it on a tiny task.