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

# What changes in LangSmith v0.18

> How self-hosted LangSmith v0.18 moves existing tracing projects to agents and environments, the migration timeline, and what changes in each workspace.

Self-hosted LangSmith v0.18 organizes every workspace by [agent](https://docs.langchain.com/langsmith/agent-registry.md#agent) instead of by tracing project. Each agent divides its traces across [environments](https://docs.langchain.com/langsmith/agent-environments.md) drawn from a fixed set: **Production**, **Staging**, **Development**, and **Local**. Each trace records the agent that produced it and the environment it ran in, so alerts, dashboards, and evaluators can target one environment without filtering for it. When you upgrade an existing installation, LangSmith migrates your tracing projects to agents automatically.

This page is for administrators of a self-hosted installation. For the upgrade itself, see [Upgrade an installation](https://docs.langchain.com/langsmith/self-host-upgrades.md). New installations on v0.18 or later start with agents, so there is nothing to migrate.

## Before you upgrade

> [!WARNING]
>
> The migration cannot be undone. Once it has run, do not downgrade to a LangSmith version from before the migration. If you downgrade, tracing projects that the older version creates may never be migrated to agents.

* **Upgrade one major version at a time**: Upgrade to the latest 0.17 chart before you upgrade to 0.18. See [Upgrade an installation](https://docs.langchain.com/langsmith/self-host-upgrades.md).
* **Installations without authentication**: LangSmith does not migrate an installation that has neither basic auth nor SSO enabled. Its workspace keeps the tracing-project experience after the upgrade. To move it to agents, configure [basic auth](https://docs.langchain.com/langsmith/self-host-basic-auth.md) or [SSO](https://docs.langchain.com/langsmith/self-host-sso.md), and LangSmith then runs the migration.

## How the migration runs

The Helm chart value `config.agentMigration.enabled` controls the migration and defaults to `true`. It needs no extra infrastructure or permissions. The time it takes depends on how many workspaces and tracing projects the installation has.

1. About 10 minutes after the upgraded services start, the migration begins on its own. Restarts do not reset this delay.
2. LangSmith migrates each workspace separately. A workspace switches to agents as soon as its own migration finishes, without waiting for the rest of the installation.
3. While the migration is active, LangSmith checks migrated workspaces for tracing projects created after their migration and migrates those too.
4. After 24 hours with no new tracing projects to migrate, the migration stops. Later upgrades do not run it again.

Tracing keeps working throughout the migration. Until their workspace migrates, a user sees the tracing-project experience.

To pause the migration, set the `enabled` value to `false`:

```yaml theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
config:
  agentMigration:
    enabled: false
```

Apply the change with `helm upgrade`, which restarts the LangSmith pods that read the setting. To resume, set the value back to `true`. The migration continues from where it stopped. Pausing does not end the migration. After you resume, the migration stops for good only when a full check finds nothing left to migrate and no migration work has happened for the previous 24 hours, including time spent paused.

## Check whether a workspace has migrated

A migrated workspace shows the [agent switcher](https://docs.langchain.com/langsmith/navigate-agents.md) in the top bar, and the control at the top left becomes a workspace switcher that names your workspace. A workspace that has not migrated yet still shows the tracing-project experience.

## How tracing projects map to agents

LangSmith does not re-ingest, move, or rename your traces. Each tracing project keeps its ID, name, and history:

* **One agent per tracing project**: Each tracing project becomes its own agent, with a **Production** environment. That environment is the original tracing project. The migration does not create **Staging**, **Development**, or **Local** environments.
* **No merging by name**: Tracing projects named `checkout`, `checkout-prod`, and `checkout-staging` become three separate agents, not one agent with three environments.
* **Agent identifier**: LangSmith derives the identifier from the project name, converted to lowercase letters, digits, and hyphens. When a [deployment](https://docs.langchain.com/langsmith/deploy-overview.md) owns the tracing project, the identifier and display name come from the deployment's name instead. If the identifier is already taken, or a tracing project already uses a name that one of the agent's future environments needs (such as `checkout-staging` for `checkout`), LangSmith adds a hyphen and eight digits, for example `checkout-12345678`. To find an agent's final identifier, open it in [Agent Registry](https://docs.langchain.com/langsmith/agent-registry.md).
* **Projects that stay as they are**: LangSmith does not convert experiments, projects that LangSmith creates for its own features, or tracing projects that belong to preview deployments to agents.

A new environment that you add later gets a tracing project named after the agent identifier, a hyphen, and the environment. For example, an agent whose identifier is `billing` has its staging traces in `billing-staging`. A tracing project created after the migration, for example by code that sends traces to a new project name, becomes a new agent with a **Production** environment.

## What changes in each workspace

Your traces, datasets, prompts, and experiments stay the same records. Code that sends traces to an existing tracing project by name keeps working, because that project is now the agent's **Production** environment. See [Configure integrations that require a project name](https://docs.langchain.com/langsmith/create-an-agent.md#use-an-environment-project).

After a workspace migrates, these parts of LangSmith are scoped to an agent and environment instead of a tracing project:

* **Traces**: Grouped under an agent and one of its environments instead of under a tracing project you named.
* **Prebuilt dashboards**: Generated for every agent environment rather than for a named project. See [Dashboards](https://docs.langchain.com/langsmith/dashboards.md).
* **Alerts**: Apply to one environment of an agent. See [Alerts](https://docs.langchain.com/langsmith/alerts.md).
* **Evaluators**: Attach to an environment. See [Manage evaluators](https://docs.langchain.com/langsmith/evaluators.md).
* **Datasets**: Attach to one or more agents rather than to a project, and to no environment, so one dataset can serve several agents. See [Create and manage datasets in the UI](https://docs.langchain.com/langsmith/manage-datasets-in-application.md).
* **Navigation**: Gains an agent switcher in the top bar, which moves between the agent list and a single agent's Overview. See [Navigate agents](https://docs.langchain.com/langsmith/navigate-agents.md).

## See also

* [Agent Registry](https://docs.langchain.com/langsmith/agent-registry.md)
* [Agent environments](https://docs.langchain.com/langsmith/agent-environments.md)
* [Navigate agents](https://docs.langchain.com/langsmith/navigate-agents.md)
* [Create an agent](https://docs.langchain.com/langsmith/create-an-agent.md)
* [Self-hosted changelog](https://docs.langchain.com/langsmith/self-hosted-changelog.md)
* [Administration overview](https://docs.langchain.com/langsmith/administration-overview.md#agents)

***

[Connect these docs](https://docs.langchain.com/use-these-docs.md) to your agent of choice via MCP for real-time answers.

[Edit this page on GitHub](https://github.com/langchain-ai/docs/edit/main/src/langsmith/self-host-agent-migration.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).
