Skip to main content
Self-hosted LangSmith v0.18 organizes every workspace by agent instead of by tracing project. Each agent divides its traces across environments 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. New installations on v0.18 or later start with agents, so there is nothing to migrate.

Before you upgrade

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.
  • 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 or SSO, 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:
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 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 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.
  • 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. 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.
  • Alerts: Apply to one environment of an agent. See Alerts.
  • Evaluators: Attach to an environment. See Manage evaluators.
  • 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.
  • Navigation: Gains an agent switcher in the top bar, which moves between the agent list and a single agent’s Overview. See Navigate agents.

See also