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

# Deploy to an agent environment

> How the LangGraph and Managed Deep Agents CLIs bind a deployment to an agent and an environment, which values each flag takes, and which CLI versions accept them.

Deploying to an agent environment binds a [deployment](/langsmith/deployment) to one [agent](/langsmith/agents) and one of that agent's [environments](/langsmith/agent-environments). Two flags carry the binding, and the LangGraph CLI and the `mda` CLI both accept them.

Use it to keep a staging build and a production build of the same agent apart, so each one reports into its own environment.

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

## Prerequisites

Both CLIs need the following:

* A [LangSmith API key](/langsmith/create-account-api-key) in `.env` or your shell environment.
* A project folder holding `langgraph.json`. Run the CLI from that folder.
* An agent-based workspace, because the flags require agent mode on the workspace.

An org-scoped API key also needs the workspace, and each CLI reads it from a different variable: `LANGSMITH_TENANT_ID` for the LangGraph CLI, and `LANGSMITH_WORKSPACE_ID` for the `mda` CLI. A workspace-scoped key needs neither. The LangGraph CLI prompts for the value when the key is org-scoped. In a script or CI job, set `LANGSMITH_TENANT_ID` ahead of time, and pass `--no-input` so the LangGraph CLI fails instead of waiting for input. Both the Python and the TypeScript LangGraph CLI accept `--no-input`.

## Addressing flags

Both CLIs take the same two flags:

* **`--agent-id`**: The agent to deploy to. The value is the agent's identifier, not its display name. For which value is which, see [Identifiers and display names](/langsmith/agents#identifiers-and-display-names).
* **`--agent-environment`**: The environment the deployment reports into, and one of `development`, `staging`, or `production`. A deployment cannot take `local`. That environment [does not display on deployments](/langsmith/agent-environments#select-an-environment) at all, which is the one way this set differs from the four values [agent addressing](/langsmith/log-traces-to-agent#addressing-variables) accepts.

The flags name the same pair that [agent addressing](/langsmith/log-traces-to-agent) names on the tracing side. The LangGraph CLI also reads the flags from the same two variables, `LANGSMITH_AGENT_ID` and `LANGSMITH_AGENT_ENVIRONMENT`. The `mda` CLI does not read those variables, so pass the flags to it directly.

## Deploy with the LangGraph CLI

These flags require `langgraph-cli` v0.4.32 or later in Python, and `@langchain/langgraph-cli` 1.5.2-dev.0 in TypeScript. The TypeScript version is a prerelease build. Install it exactly, because the current stable release, 1.5.1, does not accept the flags. To deploy:

1. Install the CLI:

   <CodeGroup>
     ```bash Python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
     uv tool install --force "langgraph-cli>=0.4.32"
     ```

     ```bash TypeScript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
     npm install -g "@langchain/langgraph-cli@1.5.2-dev.0"
     ```
   </CodeGroup>

2. Deploy, naming the agent and the environment:

   <CodeGroup>
     ```bash Python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
     langgraph deploy --agent-id my-agent --agent-environment staging --remote
     ```

     ```bash TypeScript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
     langgraphjs deploy --agent-id my-agent --agent-environment staging --remote
     ```
   </CodeGroup>

Pass both flags or neither, because either one on its own is rejected. Do not combine them with `--name` or `--deployment-id`, which name a deployment directly and are rejected alongside an agent.

`--remote` forces a remote build. Without it, the CLI builds locally whenever Docker is available. For the rest of the flags, see [`langgraph deploy`](/langsmith/cli#deploy).

## Deploy with the mda CLI

These flags require `managed-deepagents` 0.7.5.dev4 in Python, or 0.7.5-dev.4 in TypeScript. Both are prerelease builds. Install that version exactly, because 0.8.0 and later do not accept the flags and a version range resolves to a build that rejects them. To deploy:

1. Install the CLI:

   <CodeGroup>
     ```bash Python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
     uv tool install --force --prerelease allow "managed-deepagents==0.7.5.dev4"
     uv add --prerelease allow "managed-deepagents==0.7.5.dev4"
     ```

     ```bash TypeScript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
     npm install "managed-deepagents@0.7.5-dev.4"
     ```
   </CodeGroup>

2. Deploy the project in the current folder:

   <CodeGroup>
     ```bash Python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
     mda deploy . --agent-id my-agent --agent-environment staging
     ```

     ```bash TypeScript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
     npx mda deploy . --agent-id my-agent --agent-environment staging
     ```
   </CodeGroup>

In Python, installing the CLI as a tool and pinning the same version as a project dependency keeps the global `mda` binary and the project's own dependency on one version. For the rest of the flags, see [Deploy projects](/langsmith/python/managed-deep-agents-cli#deploy-projects), and for deploying without the agent flags, see [Deploy a Managed Deep Agent](/langsmith/python/managed-deep-agents-deploy).

## Confirm the binding

Open the agent and read the **Deployments** section of its [Overview](/langsmith/navigate-agents#read-the-agent-overview). The new deployment appears as a row there as soon as the deploy succeeds, and the row links to the deployment.

If the new deployment has no row, or the Overview has no **Deployments** section, the deployment is not bound to the agent. This usually happens when you set the `LANGSMITH_AGENT_ID` and `LANGSMITH_AGENT_ENVIRONMENT` variables and deploy with the `mda` CLI, which ignores them. Add `--agent-id` and `--agent-environment` to the deploy command instead.

## See also

* [Agents](/langsmith/agents)
* [Agent environments](/langsmith/agent-environments)
* [Log traces to an agent](/langsmith/log-traces-to-agent)
* [Deployment](/langsmith/deployment)

***

<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/deploy-to-agent-environment.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).
  </Callout>
</div>