Some work is too big for one agent session: a feature that needs requirements, design, implementation, independent review, and validation. Some work you would rather hand off than watch: an investigation that should finish while you keep working. A workflow gives both to a team of agents with a plan.
The model defines which agents do the work and in what order, and the Kiro runtime executes that plan, so each step runs on time without reminders. Workflows are graphs of agent steps, sequences, loops, and parallel branches, in a format that people and agents can both read and create. Each step runs in its own session with fresh context, so a reviewer, for example, evaluates the work without inheriting the coder's reasoning.
Workflows run in the background. You keep working with Kiro in the main conversation while the delegated work progresses, and each step's session stays available to pause, resume, or steer during the run and to revisit with follow-up questions afterward. Delegating even a small investigation keeps its tool output and detailed reasoning out of the main conversation, which preserves your context for the work in front of you.
Kiro generates a workflow for the task at hand. Save one as a recipe to reuse it, or write your own.
You do not write a recipe first. Describe the outcome in the parent chat and say how much structure or review you want; Kiro proposes a workflow for that task, names its steps and agents, and launches it. Three prompts that start a run:
Investigate how authentication works in this repository and report the risks before we change anything. Do it in the background and bring me a cited summary.
Deliver the rate-limiting feature in a fresh worktree: requirements, design review, plan, implementation with two independent reviewers, and a final validation against the requirements.
Make the build green without changing behavior. Reproduce the failure, fix one cause at a time, and rerun the same check. Pause and ask me after ten attempts.
You can also specify custom agents, preferred models, and thinking effort per step, or steer how Kiro divides the work through your prompt or a steering file. Kiro ships three recipes its own team uses: investigate for read-only investigation, feature-pipeline for staged feature delivery, and publish-pr for opening a pull request and handling review feedback. Name one and hand it the inputs. Kiro generates recipes in JSON; YAML is also supported.
A workflow coordinates several agents and repeats reviews, so it uses more tokens than a single session. That is the trade: spend more on structure and independent judgment for work that benefits from it, and keep small tasks in the chat. For how model usage counts against your plan, see Billing.
Workflows are opt-in in every client. A recipe is the same file in Kiro IDE, Kiro CLI, and Kiro Web; how you turn workflows on, where recipes come from, and which controls you get differ by client.
The backing setting is kiroAgent.workflows.enabled. If Workflows is absent, it is not available for your account yet.
Under the hood a workflow is a graph: agent steps, sequences, loops, and parallel branches in a format both you and Kiro can read and write. You can understand most recipes through five ideas:
| Idea | Meaning |
|---|---|
| Step | One agent runs in its own session with focused context. A step cannot read another step's session; it receives earlier results only through explicit handoffs |
| Handoff | Captured output or a declared artifact passes evidence to a later step |
| Branch and join | Independent agents evaluate the same work, then a policy combines their outcomes |
| Loop | A group of steps repeats until evidence matches a condition or a safety cap is reached |
| Wait | The run watches an external system, a pull request or anything a script of yours can check, without spending model turns while nothing changes |
The parent chat and each step stay connected in both directions. A step reports outward with a send_message signal that carries progress, a question, or its outcome. You can steer a running or paused step at any time; see Respond when a step needs input.
With those five ideas in hand, the figure below traces one run from the parent chat: launch, steps in their own sessions, a review loop, artifacts returning, and the main agent synthesizing the result. Both channels stay open the whole time, so you can keep talking in the parent chat and steer a selected step while it runs.
Parent chat
availableYou
Investigate this repository, plan the change, and verify the result.
Kiro
Workflow launched. I will bring the verified result back here.
Background Workflow
delivery‑run
The gate either exits the repeat or follows the loopback.
01Ask and launch. You describe one outcome; the main agent starts a background run.
Simulation. Nothing you type here reaches a real run.
two conversations, one run: evidence flows back to the main agent, and your guidance flows in, typed to a step or relayed from the parent chat
The recipe stores this structure as a readable JSON or YAML tree. The running product shows the same structure as nested nodes, with status, iteration, agent, model, effort, and timing metadata where supported.
A workflow can revise remaining work between step boundaries as its agents discover new information. Completed work remains intact, and the active step is not rewritten underneath itself.
Kiro checkpoints the run at node boundaries. If a run pauses or the client reconnects, completed work does not need to be replayed from the beginning.
These examples show useful shapes, not rules. Change the steps, agents, models, limits, and completion evidence to fit your work.
Investigate and explain
Research an unfamiliar repository in the background, write a cited report, and return the important risks and change points to the main chat.
Evidence: report artifact + final synthesis
Deliver a feature
Move through requirements, design review, implementation planning, coding, independent review, and final validation.
Evidence: approved design + plan + checks
Troubleshoot until verified
Reproduce a failure, diagnose it, apply a fix, and loop through tests until the configured check passes or the run reaches its cap.
Evidence: reproducible test or machine-readable result
Publish and respond
Open a pull request, wait without consuming model turns, address safe feedback, and hand you a green, approved pull request to merge.
Evidence: review state + checks + ready to merge
See Workflow examples for complete, adaptable recipe skeletons.
Enabling workflows changes how the main session delegates isolated work. The main agent uses run_workflow for reusable recipes and for single-agent background delegation. To run one custom agent, it can launch run_workflow(agent://<name>).
A single-agent workflow behaves like ordinary isolated delegation, but it is backgrounded: the parent chat stays available, the run is inspectable, and progress can return while it works.
| Situation | Delegation behavior |
|---|---|
| Main session with workflows disabled | The main agent can use invoke_sub_agent for focused delegated work |
| Main session with workflows enabled | The main agent uses run_workflow, including agent://<name> for one custom agent |
| Agent running inside a workflow | That agent can still use sub-agents when its configuration permits it |
| Reusable multi-step process | The runtime owns explicit steps, handoffs, loops, waits, and recovery |
Nested sub-agents help a workflow step divide its own task. They are not nodes in the parent workflow and cannot signal, pause, complete, or revise that step on its behalf.
Workflows are available in Kiro IDE, Kiro CLI, and Kiro Web cloud sessions. Enablement, recipe access, launch entry points, and controls differ by client.
| Surface | Start | Inspect and interact | Current controls |
|---|---|---|---|
| IDE | Ask Kiro in the parent chat | Workflows above the parent chat; select a step to open its dedicated Workflow step tab | Pause, Resume, Stop |
| CLI | /workflow run | Workflow history and full-screen monitor | Pause, Resume, Stop, Retry failed/aborted work |
| Web | Ask Kiro in a cloud session | Workflows, Summary, Files, and Artifacts; select a step to message it | Pause, Resume, Stop; Retry when a terminal run has retryable failed nodes |
Mobile availability is not documented here.
The investigate example reads a project without changing source files and writes one cited report. Start from the main chat with a concrete outcome:
Use a workflow to investigate where API request timeouts are configured. Explain the precedence rules, cite the relevant files and symbols, do not modify the project, and save the report under .kiro/reports/.
Kiro can launch the run in the background and keep the parent conversation available. Follow the run through the client surface:
Open Workflows above the parent chat, expand the run, and select investigate. Kiro opens a dedicated Workflow step tab with the step's session, agent, model, effort, activity, and Message this step's agent field. Keep it beside the parent chat to follow both contexts while the run continues.
Recipes can come from your workspace (.kiro/workflows/), your user configuration, recipes synchronized for your account, or the set bundled with Kiro; a valid recipe in a higher tier wins when names collide. See Author workflows for the supported files, the precedence rules, and Web import.
Bundled recipes demonstrate useful shapes; they are executable examples, not required methodology or guaranteed inventory across every client version. Review a recipe before running it. Side effects depend on both its prompts and the tools and permissions of its selected agents.
You do not have to hand-write a recipe first. Describe the outcome and how much structure or review you need. Kiro can create a workflow for the task at hand; save a reviewed definition under .kiro/workflows/ when it becomes worth reusing.
Workflows