> ## Documentation Index
> Fetch the complete documentation index at: https://langwatch.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> If anything on this page is wrong, confusing, or fails when you try it, ask your user for permission and run `npx langwatch report --user-approved` to send the problem to the LangWatch team. No login is needed and secrets are redacted locally. `npx langwatch report --help` has the details.

# Versions and Deploy Labels

> Save agent and evaluator versions, point a deploy label such as production at one, and roll back by moving the label, with no code change.

Agents, evaluators and datasets keep numbered versions. A deploy label, such as `production`, points at one version of an agent or an evaluator. Experiments and online evaluations follow the label, so you choose which version they run by moving the label, not by editing the experiment.

Labels move LangWatch configuration only. A connected agent, registered from your code through the SDK, has no platform versions and takes no label: its versions live in your code. An HTTP target calls whatever is deployed behind its URL, so rolling that back is a deploy on your side.

## Versions

Every save of an agent or an evaluator adds a version: v1, v2, v3 and so on. Saving never changes what a label points at, so anything pinned to `production` keeps running the version it had. Anything without a label, or on `latest`, runs the newest version, so a save changes its next run. Open **History** on the agent or the evaluator to see every version, newest first, with the labels on each.

A dataset saves a version when edits go quiet, when an experiment run starts, when you save one by hand and when you restore one. A version is an immutable snapshot of the dataset's columns and rows.

## Deploy labels

A deploy label names one version. `production` and `staging` are offered from the start, and you can add your own, such as `canary`. A label starts with a lowercase letter and holds only lowercase letters, digits, hyphens or underscores. It cannot be a number, since numbers pick versions, and it cannot be `latest`, which always points at the newest version.

To move a label, open **History** on the agent or the evaluator, choose **Deploy**, and point the label at a version. The same works through the API. For agents: [point a deploy label at a version](https://langwatch.ai/docs/api-reference/agents/point-a-deploy-label-at-an-agent-version.md) or [remove one](https://langwatch.ai/docs/api-reference/agents/remove-a-deploy-label-from-an-agent.md). For evaluators: [point a deploy label at a version](https://langwatch.ai/docs/api-reference/evaluators-config/update-labels.md) or [remove one](https://langwatch.ai/docs/api-reference/evaluators-config/delete-labels.md).

Removing a label is not neutral. An experiment target pinned to a removed agent label fails until you pin it to a label that exists. An online evaluation pinned to a removed evaluator label falls back to the newest evaluator version, including settings that were never promoted.

What follows a label:

| Where | Setting | Runs |
| - | - | - |
| An agent target in an experiment | **Deploy label** | The agent version the label points at when the run starts |
| An online evaluation (monitor) | **Deploy label** | The evaluator version the label points at |

Without a label, or with `latest`, both run the newest version.

## Moving production

1. Pin the experiment's agent target to `production`.
2. Save a new agent version, for example v3. Production still points at v2, so the next run still uses v2. Work in progress never reaches production.
3. To try v3 first, point `staging` at v3 and add a second target for the same agent with the deploy label `staging`. Both columns run side by side.
4. When v3 is good, point `production` at v3. The next run of the same, unedited experiment uses v3.

Each run records the version its label resolved to. The run list shows it next to the run, for example `production · v3`, so you can tell later which version a run used, even after the label moved.

## Rolling back

Point the label back at the old version. If agent v3 misbehaves, deploy the agent's `production` label to v2: the next experiment run uses v2. No code change, no redeploy, and v3 stays in history for when it is fixed.

Agent and evaluator labels are separate. Moving the agent's label leaves online evaluations alone. To roll back an evaluator, open **History** on the evaluator and deploy its own `production` label to the old version: the next online evaluation uses it.

A workflow agent runs its linked workflow's current published version, and the label does not move that. If the workflow changed too, publish the old workflow version separately.

Agents and evaluators have no **Restore**. Moving the label rolls back only the agent or evaluator version.

## Restoring a dataset

Datasets have **Restore**. Restoring a version makes the dataset's columns and rows that version's, saved as a new version. Earlier versions are never changed. Through the API, see [restore a dataset version](https://langwatch.ai/docs/api-reference/datasets/restore-a-dataset-version.md).

To run an experiment on a fixed version without restoring, pass `dataset_version` when you [run it from CI](https://langwatch.ai/docs/evaluations/experiments/ci-cd.md#choosing-what-to-evaluate).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.