> ## 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.

# Create an agent

> The four ways an agent is created in LangSmith, what each route decides about the agent it makes, and the rules an identifier must follow.

You can create an [agent](/langsmith/agents) through four routes. The route you choose sets how the agent gets its identifier and how many [environments](/langsmith/agent-environments) the agent starts with.

Pick a route based on where the agent runs. If you build the agent in LangSmith, LangSmith creates the agent as you build it. If the agent runs on your own machines, LangSmith can create the agent when the agent sends its first trace.

<Note>
  **Beta.** Agent-based workspaces are in [beta](/langsmith/release-stages). LangChain enables the change for an organization, and it applies to workspaces created after that. An existing [project-based](/langsmith/observability-concepts#tracing-projects) workspace does not convert automatically, but LangChain can convert it. To ask about access, [contact our sales team](https://www.langchain.com/contact-sales).
</Note>

## Compare the four routes

Not every agent can have a [deployment](/langsmith/deployment). An agent created by deploying a project has a deployment from the start. An agent created by a trace, by the Observability option in the [**New Agent** panel](#start-from-the-new-agent-panel), or by the **Create a new agent** dialog has no deployment at first, but you can [deploy to it](/langsmith/deploy-to-agent-environment) later. An agent built in the UI cannot have a deployment, because it runs on a Studio runtime. After a deployment, the agent's Overview shows a **Deployments** section.

| Route | Use it when | Identifier | Environments at creation |
| - | - | - | - |
| [Build tab](/langsmith/build-an-agent) | LangSmith runs the agent for you | Generated for you | Production alone |
| **Create a new agent** dialog | You want the agent named before its first run | You set it | All four |
| [Tracing](/langsmith/log-traces-to-agent) to an identifier that does not exist | The agent already runs somewhere else | The value you send | All four |
| [Deploying a project](/langsmith/deploy-to-agent-environment) | You deploy the agent from a project | The agent ID you pass, or derived from the deployment name | All four |

An agent created in the UI gains its other environments the first time a trace is addressed to one. For what the four are, see [Agent environments](/langsmith/agent-environments#the-four-environments).

## Identifier rules

An identifier is 1 to 63 characters, using lowercase letters, digits, and hyphens. It must start with a letter and end with a letter or digit, so `support-agent` and `billing-v2` are valid. Anything else is rejected.

The rules apply wherever you supply the value: in the **Agent ID** field, in the identifier you trace to, and in the agent ID you deploy to. The Build tab generates an identifier instead. A deployment without an agent ID derives one from the deployment name, appending a suffix when that value is already taken, so a deployed agent can end up with an identifier close to the deployment name rather than equal to it.

An identifier cannot be changed after the agent is created. The display name can. For which value is which, see [Identifiers and display names](/langsmith/agents#identifiers-and-display-names).

## Start from the New Agent panel

Four controls open the **New Agent** panel: **+ Agent** above the agent list, **+ Create new agent** and **Trace existing agent** on a creation card at the end of the list, also titled **New Agent**, and the **+** button beside the search box in the agent switcher, which shows a **New agent** tooltip on hover. **Trace existing agent** opens the panel on the Observability option, and the other three open it on its grid of options. An **All options** button returns to the grid.

The panel hands off to four flows. Only Observability creates the agent inside the panel:

* **Builder**, "Build and configure inside LangSmith". Leaves the panel for the **Build** tab, where submitting the form creates the agent. See [Build an agent in the UI](/langsmith/build-an-agent).
* **Managed Deep Agent**, "Build locally and deploy". The agent is created when you deploy. See [Managed Deep Agents](/langsmith/python/managed-deep-agents-overview). This route requires a paid plan.
* **Open Source**, "Build an agent with our open source frameworks". The agent is created by the first trace. See [LangChain](/oss/python/langchain/overview).
* **Observability**, "Trace an existing agent". Name the agent in the panel, and LangSmith creates it and opens its tracing page, which holds the setup steps. See the [tracing quickstart](/langsmith/observability-quickstart).

## Name an agent traced from outside LangSmith

To create the agent before any trace arrives, name it in either of two places:

* The Observability option in the **New Agent** panel.
* The **Create a new agent** dialog, opened from **+ New agent** below the agent list on Tracing when no agent is selected.

Both take an **Agent name** and, in its own field, an **Agent ID**, with a note that the ID is used in URLs and API calls and cannot be changed later. Both require permission to create projects. The agent switcher has the same **+** button, beside its search box, for users with the same permission, wherever the switcher appears, and it opens the **New Agent** panel rather than the dialog.

Creating the agent first is optional. [Tracing to an identifier that does not exist](/langsmith/log-traces-to-agent#addressing-an-agent-that-does-not-exist) creates the agent under the value you sent, so the dialog is for naming an agent ahead of its first run.

## See also

* [Agents](/langsmith/agents)
* [Agent environments](/langsmith/agent-environments)
* [Build an agent in the UI](/langsmith/build-an-agent)
* [Deploy to an agent environment](/langsmith/deploy-to-agent-environment)
* [Log traces to an agent](/langsmith/log-traces-to-agent)

***

<div className="source-links">
  <Callout icon="terminal-2">
    [Connect these docs](/use-these-docs) to your agent of choice via MCP for real-time answers.
  </Callout>

  <Callout icon="edit">
    [Edit this page on GitHub](https://github.com/langchain-ai/docs/edit/main/src/langsmith/create-an-agent.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).
  </Callout>
</div>