Skip to main content

Working with the agent

Kiro Web's default mode is collaborative. You work with the agent interactively, iterating on a problem together. The agent helps you think through approaches, write code, and open pull requests when you're ready.

For tasks where you want the agent to own the outcome end-to-end, see autonomous mode.

For structured planning, where you want requirements, a design, and a task list before any code is written, use Specs.

For reusable multi-step orchestration that runs in the background while the main conversation stays available, use Workflows. Workflows are opt-in: turn on Enable workflows in Agent Config > Workflows. A workflow can coordinate isolated agents, loops, reviews, and external waits; inspect or message its individual steps under Workflows in the session details.

Start a session

  1. Go to app.kiro.dev and click New session
  2. Select one or more repositories using Select repo at the bottom of the chat input. To work from a branch other than the default, choose it in the branch selector
  3. Optionally, select Add to group to choose or create a group for the session
  4. Describe what you want to work on

If you don't select repositories upfront, you'll be prompted to choose them when you ask the agent to work on something.

How it works

In the default mode, you drive the conversation. Chat with the agent to:

  • Discuss implementation approaches and trade-offs
  • Ask questions about your codebase
  • Get the agent to write or modify code
  • Iterate on the implementation with feedback
  • Ask the agent to open a pull request when you're satisfied

The agent has access to web search, context from your repositories, and learnings from previous code reviews to provide informed responses.

Reading the conversation timeline

Consecutive reasoning steps and tool calls appear in one collapsible block while the agent works. Expand the block to inspect the details.

Startup actions are grouped under Session setup. Steering, Configuration Sync, and task lists present their results as readable summaries.

Opening a pull request

When you're happy with the changes, ask the agent to open a pull request. The agent creates a feature branch, commits the changes, and opens a PR with a description of what was done.

You can continue to provide feedback on the PR. The agent responds to your comments and pushes updates.

Reviews

When a session has reviews, open Summary, where Reviews appears alongside Files and Artifacts. Expand Reviews to see the list in place; selecting Files or Artifacts switches to that tab instead.

Select a review to inspect its details, including its changed files, commits, and review comments. Back returns to the review list.

Selecting repositories

You can work across multiple repositories in a single session. When you select repos, the agent clones them into its sandbox and can coordinate changes across all of them.

Chat and session behavior

Each session has a single conversation thread. You can:

  • Steer the agent on implementation approach at any time
  • Provide additional requirements or constraints
  • Ask the agent to do more work after reviewing results

To work on a different topic, start a new session.

Choose a fallback model

A fallback model takes over when your selected model can't complete a request. To set one, open Agent Config > Model fallback, choose a model from the list, and pick its fallback.

What the fallback does depends on why the request failed:

  • If the selected model is unavailable, the fallback answers that turn, and Kiro returns to the selected model on the next turn.
  • If the selected model refuses the request, the session stays on the fallback.

To remove the fallback you set, remove its entry in Agent Config > Model fallback. A vendor-recommended fallback, if available, can still apply to refusals.

Background tabs and reconnecting

If your machine sleeps or your network changes while a session is in a background tab, returning to the tab reconnects the session and replays any activity that arrived while you were disconnected. You don't need to send another message to refresh the session. A session whose connection stayed open has nothing to replay, so returning to it changes nothing.

When you reopen a session whose sandbox has stopped, Kiro shows a preview of the saved conversation while the sandbox starts. Once the sandbox is ready, the complete history replaces the preview.

Organize sessions into groups

As your list of sessions grows, you can sort them into groups to keep related work together. Groups are optional; a session that isn't in a group stays under Ungrouped.

Before starting a session, select Add to group in the composer to choose an existing group or create one. You can also organize sessions later from the sidebar or Sessions page.

In the sidebar's Sessions panel, switch to the group view and select Create group to add one. Name it and confirm, and the empty group appears right away, before you add any sessions to it.

To move a session into a group, open the session's menu and select a group under Move to Group, or select New group to create one and move the session in a single step. To take a session out of a group, open its menu and select Remove from group; it returns to Ungrouped.

From a group's menu you can:

  • Rename group. The group's sessions move to the new name.
  • Delete group. Kiro asks you to confirm, then removes the group and moves its sessions to Ungrouped. Deleting a group never deletes the sessions in it.

On the Sessions page, you can act on several sessions at once. Select the sessions you want, then use Move to group to move them all into the same group. To narrow the list instead, use Filter by group to show only the sessions in the groups you pick; filtering works on its own and doesn't require selecting any sessions first.

Name and rename sessions

Kiro generates a title for each session from your task and shows it in the session header and the sidebar. If you rename a session yourself, Kiro keeps your title and does not overwrite it with a generated one.

Data retention

Sessions expire 90 days after their last activity. Opening a session or sending a message restarts the 90-day period. Pull requests, merge requests, code changes, and conversations on GitHub or GitLab are not affected.

Kiro Web can search the web to access current information in real-time, enabling up-to-date answers about topics that may have changed since the model's training data was created.

Web search is designed to not reproduce meaningful chunks of text and works with publicly accessible pages. Web searches are logged in the session with citations, so you can see what sources the agent referenced.

Learn more

Page updated: November 16, 2026