Deploy to an agent environment

Deploying to an agent environment binds a deployment to one agent and one of that agent’s 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.

​

Prerequisites

Both CLIs need the following:

• A LangSmith 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.
• --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 at all, which is the one way this set differs from the four values agent addressing accepts.

The flags name the same pair that agent addressing 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:
   Python

   TypeScript

   uv tool install --force "langgraph-cli>=0.4.32"
   
2. Deploy, naming the agent and the environment:
   Python

   TypeScript

   langgraph deploy --agent-id my-agent --agent-environment staging --remote
   

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.

​

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

   TypeScript

   uv tool install --force --prerelease allow "managed-deepagents==0.7.5.dev4"
   uv add --prerelease allow "managed-deepagents==0.7.5.dev4"
   
2. Deploy the project in the current folder:
   Python

   TypeScript

   mda deploy . --agent-id my-agent --agent-environment staging
   

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, and for deploying without the agent flags, see Deploy a Managed Deep Agent.

​

Confirm the binding

Open the agent and read the Deployments section of its 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
• Agent environments
• Log traces to an agent
• Deployment

---