> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.ada.cx/docs/optimization/change-sets/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ada.cx/_mcp/server.

# Change sets

The **Change sets** page lists every change set on your AI Agent, and the detail view shows the entities each one changes. Use it to review what an [`edit_agent_behavior`](/mcp/tools/edit-agent-behavior) session staged, is rolling out, promoted, or reverted, before deciding what happens next.

> **Tip**
>
> You can rename, roll out, promote, and delete change sets from the dashboard. Use the [`edit_agent_behavior`](/mcp/tools/edit-agent-behavior) MCP tool to create change sets, edit staged changes, or revert promoted changes.

## Overview

A change set is a bundle of edits to your AI Agent. It stays off the live Agent until it is rolled out or promoted. Each change set is created and managed through the [`edit_agent_behavior`](/mcp/tools/edit-agent-behavior) MCP tool. The dashboard **Change sets** page adds a place to see what has been staged and what has shipped, without leaving Ada.

Two views are available:

* The **list view** at **Config > AI AGENT > Change sets** shows every change set on the Agent, with filters and search.
* The **detail view** opens when you click a change set. It shows each entity the change set touches and what changed on it.

## Limitations

The Change sets page has the following constraints:

* **Dashboard actions**: Renaming, rollouts, promotion, and deletion require write access and a change set with **Testing** status.
* **Rollout percentage**: Percentages across active rollouts on the same Agent cannot exceed 100%.
* **Change sets only**: The page shows change sets created through `edit_agent_behavior`. Direct edits made in the dashboard (for example, from the Knowledge or Playbooks pages) do not appear here.
* **90-day retention**: A promoted change set stays revertible for 90 days after it is promoted, then is automatically deleted. A testing change set is automatically deleted 90 days after it is created.

## Use cases

The Change sets page helps AI Managers keep track of in-flight and shipped edits.

* **Review a pending change set**: See what an MCP assistant staged before you promote or roll out the change set.
* **Audit what shipped**: Read the entities and field-level changes on a promoted change set to confirm what went live.
* **Track a rollout**: See which change sets are sampling live traffic and the share they cover.
* **Investigate a regression**: Filter promoted change sets by date to find the change that landed around when a behavior shift started.

## Capabilities & configuration

The list view provides the following controls:

* **Search**: Find a change set by name or ID.
* **Status filter**: Narrow the list to one status (Testing, Promoting, Promoted, or Reverted).
* **Date range**: Restrict the list to change sets last edited within a window.
* **Sort**: Sort the list by Status or Rollout.
* **Pagination**: Move through pages of results.

The detail view provides:

* **Entities changed**: One row per entity, with the entity's icon and name on the left and a summary of what changed on the right (for example, `2 edits`, `article added`, `article deleted`).
* **Field-level diff**: For an edited entity, each changed field is shown side by side, with only the differing words highlighted in each line. Below 960px width, the two columns collapse into a single column.
* **Last updated**: The timestamp of the most recent change to the change set.

## Quick start

Find and review a change set in a few steps. See [Implementation & usage](#implementation--usage) for more detail.

Go to **Config > AI AGENT > Change sets**.

Use the search field or the Status filter to narrow the list.

Click a change set to open its detail view and see the entities it changes.

## Implementation & usage

Use the list and detail views to see what is staged, what is live, and what shipped.

### List view

The list view is the landing page at **Config > AI AGENT > Change sets**. Each row represents one change set on the Agent.

| Column          | Description                                                                                                      |
| --------------- | ---------------------------------------------------------------------------------------------------------------- |
| **Name**        | The label given to the change set when it was created or last renamed.                                           |
| **ID**          | The change set's unique identifier. Copy it to pass into an MCP call, for example when promoting or rolling out. |
| **Last edited** | The most recent time the change set was modified, promoted, or reverted.                                         |
| **Edited by**   | The MCP client or user that made the most recent change.                                                         |
| **Status**      | The current lifecycle state (see [Statuses](#statuses)). Sortable.                                               |
| **Rollout**     | The rollout state for the change set, blank when no rollout is active. Sortable.                                 |

**To filter the list:**

1. On the Ada dashboard, go to **Config > AI AGENT > Change sets**.
2. Use any combination of the toolbar controls:
   * Enter a name or ID in the **Search** field.
   * Select a status from the **Status** filter.
   * Set a **Date range** to restrict the list to change sets last edited within the window.
3. Click a column header to sort by **Status** or **Rollout**.
4. Move through pages using the pagination controls at the bottom of the list.

#### Statuses

Change sets move through the following statuses:

* **Testing**: Staged and not yet promoted. Can be tested with simulations, rolled out to a sample of new conversations, or promoted.
* **Promoting**: Promotion is in progress. This is a short-lived state that resolves to Promoted when the promotion completes.
* **Promoted**: Live on the AI Agent. A promoted change set stays revertible for 90 days.
* **Reverted**: The change set has been reversed by a revert change set that promoted successfully.

### Detail view

Click a change set in the list to open its detail view. The page is titled **Managing changeset** and shows the last-updated timestamp. The **Details** and **Entities changed** sections appear below.

Each row in **Entities changed** represents one entity the change set touches:

* The left side shows the entity's icon and name.
* The right side summarizes what the change set does to that entity. For example, a knowledge article with two field changes reads `2 edits`, a newly created article reads `article added`, and a deleted article reads `article deleted`.

Expand a row to see the field-level diff. Each changed field is shown with the previous value on the left and the new value on the right. Only the differing words on a modified line are highlighted, so a one-word edit stays readable rather than tinting the entire value. Below 960px width, the two columns collapse into a single unified column.

#### Manage a change set

With write access, you can use these controls while the change set has **Testing** status:

* **Name**: The change set's label. Click **Save** after editing it.
* **Live customer test**: Enable this toggle to try changes on a percentage of new conversations. **Set rollout** controls the percentage, and **Set limit** controls the maximum number of conversations. Disable the toggle to stop a rollout. After changing these settings, click **Save**. Confirm with **Save changes**.
* **Promote change set**: An option in the actions menu that applies staged changes to your live AI Agent. Promotion requires confirmation.
* **Delete change set**: An option in the actions menu that discards the change set and its staged changes. Deletion requires confirmation.

Changing the rollout percentage or conversation limit, or restarting a rollout, resets progress to zero. Renaming a change set or stopping a rollout preserves progress.

## Related features

* [`edit_agent_behavior`](/mcp/tools/edit-agent-behavior): The MCP tool that creates, edits, promotes, reverts, and rolls out change sets.
* [`list_agent_changesets`](/mcp/tools/list-agent-changesets): The MCP tool the dashboard list view reads.
* [Data Export API conversation object](/data-export-conversation-object): The `changeset_id` field records the change set each conversation ran against.

---

Have any questions? Contact your Ada team, or email us at [](mailto:help@ada.cx?subject=Help%20Docs%20inquiry).