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. It is for developers and team leads who want that work finished without watching every step.
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. In a V3 session, Kiro shows the proposed plan for your approval before any step runs. You can review its steps and agents before starting it. In Kiro CLI 2.33.1 or later, enabling Workflows no longer starts a workflow on its own; one runs only when you explicitly ask for it.
In Kiro CLI V3, selecting a recipe from the /workflow run picker opens a confirmation form with a plan preview. The same approval step appears when Kiro creates a workflow from your prompt.
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.
In Kiro CLI 2.33 or later, when a workflow asks you to approve its plan, the approval shows a compact step tree: each step with its agent, plus model and effort where the plan sets them. Press Tab to move into the tree, Enter to show or hide a step's details, and Tab again to return to the choices. In Kiro CLI 2.34 or later, type suggested changes directly into the approval to revise the plan before it starts. Nothing runs until you answer. With /tools trust-all on, Kiro answers a workflow plan with its one-time Allow option and saves no rule. To confirm, start a workflow from the chat and wait for the approval: it lists the steps before anything runs.
In Kiro CLI 2.33 or later, a workflow still starts when your organization has turned off the Auto model, instead of failing.
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. It is the global switch: when it is off, Kiro does not start new workflows, and existing workflow runs and recipes stay available. Changes apply to new sessions. If Workflows is absent, it is not available for your account yet.
In Kiro IDE 1.4.26 or later, each eligible top-level chat also has a Use workflows control, at the bottom of Workflows above the parent chat, next to Share feedback for workflows. The global setting decides whether workflows are available at all; Use workflows decides how readily Kiro starts one on its own in that session. The choices:
Prefer Only when asked when you want to decide each delegation yourself; prefer Only for large tasks when multi-step work should run in the background while small tasks stay in the chat; prefer As much as possible when you want most of a session's work to run as workflows and accept the extra token use.
The control changes how Kiro decides, not what it may do: no choice refuses a launch, and you can still manage running workflows. Your most recent choice in a local session is remembered for new chat sessions. A choice made in a cloud session applies to that session only and does not change the local default. The control appears only in a top-level chat with workflows enabled; a Workflow step tab does not show it, and neither does a session created before the control existed.
To confirm, start a new chat, open Workflows above it, and check that Use workflows shows Only when asked if you have not chosen another option, or the choice you last made in a local session.
When Kiro asks you to approve proposed workflow steps, the IDE shows them in a permission card where you can choose Allow or Deny, or send feedback. A saved permission decision can handle a later proposal without showing the card. See Review proposed steps in Kiro IDE.
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.
Workflows add run_workflow for reusable recipes and single-agent background delegation. To run one custom agent in the background, the main agent 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. In Kiro CLI 2.34 or later, Workflow use controls when the main chat starts Workflows.
| Situation | Delegation behavior |
|---|---|
| Main session with Workflows disabled | Kiro handles work in the active session and can use direct sub-agents |
| Only when asked (default) | Kiro starts a Workflow only when you request one |
| Only for large tasks | Kiro can start a Workflow for multi-step work or work needing more context |
| As much as possible | Kiro tries to route most code reading, implementation, testing, and review through Workflows |
| 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, or use /workflow-run to pick a saved recipe and complete its inputs | 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 |
In the IDE, Kiro tells a workflow that changes repository files to use the branch checked out when the run starts. If the workflow uses a worktree, Kiro tells it to create the worktree from that branch and rebase onto the same branch at the end.
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.
A workflow runs agents on your behalf in background sessions that keep going while you work on something else; each step's session stays available to inspect, pause, resume, or steer. Depending on the agents a recipe names, its steps can edit files, run shell commands and tests, commit, and open or respond to a pull request, and a command watch runs a program you supply once per poll. The agent definition selects the tools a step can see, through its tools and excludedTools settings, so review a recipe and the agents it names before launching it; a workflow does not make an agent read-only by itself.
Tool visibility is separate from permission. Every step session goes through the same permission checks and approval prompts as any other session: the user, administration, workspace, preset, and session rules of the session that launched the run apply to each step together with the agent's own rules, and the most restrictive applicable rule wins. The agent's own allow rules don't grant anything the launching session doesn't allow. See Sub-agent permissions. A command watch runs its program through the permission policy of the session that launched the run: a rule that asks sends the prompt to that session, and a denial fails the watch node. Remote actions such as pushing a branch or commenting on a pull request use your own repository credentials, and your repository's branch protection, required checks, and approval policy still govern them along with Kiro's permission prompts. The bundled publish-and-respond pattern hands you a green, approved pull request and does not merge it; see Publish and respond. When a workflow asks you to approve its plan, Kiro shows the plan and nothing runs until you answer; with /tools trust-all on, Kiro answers with the one-time Allow option only and saves no rule. In an untrusted workspace, Kiro does not load Workflow files from the workspace's .kiro/workflows/ directory; your home, cloud, bundled, and generated Workflows stay available. See Workspace trust.
To narrow a workflow, set tools and excludedTools on the custom agents its steps use, put a finite maxIterations on every repeat, and give watches an idleTimeoutSec. To stop a run, use Stop in your client. Removing a recipe file from .kiro/workflows/ or ~/.kiro/workflows/ stops offering that local recipe, but a lower-precedence recipe with the same name can take its place; to stop all workflows, disable the setting described under Turn it on. To confirm a recipe's reach before you rely on it, read the agent definitions it names and run it on a small input first.
Workflows