Skip to main content
Deploying a Managed Deep Agent compiles a code-first project into a managed LangGraph app, syncs deploy-owned context to Context Hub, uploads the compiled source, and triggers a LangSmith hosted deployment build. The result is an Agent Server deployment, including the Agent Server API and MCP endpoint.
Managed Deep Agents is in public beta on LangSmith Cloud.
This page covers secrets routing and deploy options. To test the agent before deploying, see Develop locally with LangSmith Studio. For command flags, the deploy step list, and troubleshooting, see the CLI reference.

​
Prerequisites

Before you deploy, make sure you have:
  • A workspace with Managed Deep Agents public beta access.
  • A LangSmith API key for that workspace, in .env or your shell environment. On an interactive terminal, mda deploy prompts for a key or signs you in through the browser instead.
  • The mda CLI installed from managed-deepagents.
  • Project dependencies installed with uv sync for generated Python projects.
  • Model provider credentials, such as OPENAI_API_KEY, in .env, your shell environment, or LangSmith workspace secrets.

​
Select a SaaS region

LANGSMITH_ENDPOINT selects the LangSmith region the CLI deploys to. The CLI targets GCP US by default. Set LANGSMITH_ENDPOINT in your project’s .env or your shell environment before your first deploy: For example, to deploy to GCP EU:
.env
Credentials must belong to the target region. Set LANGSMITH_ENDPOINT before the first deploy, because it also selects the region that browser sign-in authenticates against. A non-interactive run cannot fall back to browser sign-in, so in CI set LANGSMITH_API_KEY for the target region. For more information on regions, see the Regions FAQ.
LangSmith managed tools are available in GCP US only.

​
Deploy to LangSmith

Deploy the local project:
mda deploy routes local project inputs to different managed surfaces:
Set the deployment name explicitly when the directory name is not the name you want:
Use --deployment-type prod when creating a production deployment:
Use --no-wait to trigger the build without polling for completion:
When --no-wait is set, schedule reconciliation is skipped for that deploy invocation because the CLI exits before the deployment reaches DEPLOYED. On success, the CLI prints the LangSmith deployment dashboard URL. For the full deploy step list, see the CLI reference.

​
Set the Python version

Configuring the Python version requires managed-deepagents>=0.8.0.
MDA builds the deployment image on Python 3.11, 3.12, 3.13, or 3.14, and by default selects the newest that requires-python allows. To pin a version, add the optional [tool.mda] table to pyproject.toml:
pyproject.toml
When set, python-version takes a quoted major.minor string, with no patch version. MDA writes the resolved version to python_version in the generated langgraph.json and selects the matching Agent Server image. requires-python remains the project’s own compatibility requirement. Pin it to stay on the same minor version when MDA adds support for a newer Python. To override it for a single build, set MDA_PYTHON_VERSION:
A target that requires-python excludes fails the build. One that depends on the image’s exact patch version warns instead, because image tags do not pin patch versions. python-version controls the deployment image only. Local builds, mda dev, Harbor task images, and execution sandboxes select their interpreters separately.

​
Secrets and environment files

mda deploy reads project .env values before shell environment variables. Use .env for the LangSmith API key that authenticates the deploy and for runtime secrets the hosted deployment needs:
.env
MDA_INGRESS_SECRET is required only when the project declares backend identity. Deploy fails preflight when that declaration is present and the value is missing. LANGSMITH_API_KEY, LANGGRAPH_HOST_API_KEY, LANGCHAIN_API_KEY, and other platform variables are reserved. They can authenticate the deploy, but they are not uploaded as user-managed deployment secrets. Non-reserved .env entries, such as model provider keys, MCP tokens, and custom tool credentials, are forwarded as hosted deployment secrets when mda deploy creates or updates the deployment. If the configured model requires a provider key, deploy fails before upload unless that key is available from .env, the shell environment, or LangSmith workspace secrets. When the provider key is only in the shell environment, mda deploy forwards it as a secret for that deploy. Reserved platform variables, empty values, .env, and .env.* files are not copied into the compiled build archive. For authentication key order and reserved variables, see the CLI reference.

​
Troubleshoot a deploy

For deploy troubleshooting, see the CLI reference. If a deployment reaches BUILD_FAILED or DEPLOY_FAILED, open the printed deployment URL in LangSmith and inspect the revision logs.

​
Next steps

Agent Server

Explore the runtime that hosts the deployment.

MCP endpoint

Expose the deployed agent as a tool to MCP clients.

Identity

Authenticate callers and provide private threads.

Schedules

Run agents on managed cron schedules.

Custom tools

Add authored LangChain tools to the agent definition.

CLI reference

Look up every mda command and flag.
Connect these docs to your agent of choice via MCP for real-time answers.
Edit this page on GitHub or file an issue.