Managed Deep Agents CLI reference

The mda CLI compiles and deploys code-first Managed Deep Agents. It is included with the managed-deepagents Python package.

Managed Deep Agents is in public beta and available on LangSmith Cloud in the US region only.

For the fastest end-to-end path, see the quickstart. For workflow guidance, see Identity, Memory, Evals, Custom tools, Custom middleware, Sandboxes, Channels, Schedules, and Deploy an agent.

Install

Install the package for the language you use to author your agent. The package exposes the mda binary.

uv tool install managed-deepagents

uv tool install managed-deepagents installs the mda CLI. A project generated by mda init has its own pyproject.toml; run uv sync inside that project to install project dependencies before local development or deploy. The package provides agent, identity, schedule, and sandbox authoring APIs with snake-case names, plus the mda console script.

Authentication

mda deploy reads API keys in this order:

LANGGRAPH_HOST_API_KEY
LANGSMITH_API_KEY
LANGCHAIN_API_KEY

The CLI reads those values from the project .env file first, then from the process environment. If no key is found in an interactive terminal, mda deploy prompts for a LangSmith API key and saves it to the project .env file.

.env

LANGSMITH_API_KEY=<LANGSMITH_API_KEY>
OPENAI_API_KEY=<OPENAI_API_KEY>

To deploy with an organization-scoped key, set LANGSMITH_WORKSPACE_ID or pass --workspace-id to mda deploy. The LangSmith API key authenticates the deploy. The agent’s model provider also needs credentials at runtime. Set the provider key in .env, export it in your shell, or configure it as a LangSmith workspace secret. For example, openai:gpt-5.5 requires OPENAI_API_KEY. mda deploy forwards non-reserved .env entries, such as OPENAI_API_KEY, MCP tokens, and custom tool credentials, as hosted deployment secrets. Reserved platform variables, including LANGSMITH_API_KEY, LANGGRAPH_HOST_API_KEY, LANGCHAIN_API_KEY, and LANGSMITH_WORKSPACE_ID, are used for CLI authentication and deploy routing but are not uploaded as user-managed deployment secrets.

Command overview

Command	Use
`mda --help`	Show CLI help.
`mda --version`	Show the installed CLI version.
`mda init <name>`	Scaffold a Python Managed Deep Agents project.
`mda build [path]`	Compile a project into a managed LangGraph app without deploying.
`mda eval …` / `mda evals …`	Initialize a Harbor workspace and continue eval authoring in a coding agent.
`mda dev [path]`	Compile a project and run it on the local LangGraph dev server.
`mda deploy [path]`	Compile, sync Context Hub context, upload, and deploy to LangSmith.
`mda channel init slack`	Add a Slack channel declaration to the current project.
`mda logs [path]`	Tail Agent Server logs for a deployed agent.
`mda delete [path]` / `mda destroy [path]`	Delete a deployed agent and the LangSmith resources it created.

Initialize projects

Use mda init to create a new project directory:

mda init my-agent

Argument or flag	Use
`name`	Required project directory name. The command fails if the destination already exists.
`--instructions TEXT`	System prompt to write into `instructions.md`.
`--instructions-file PATH`	Read the system prompt for `instructions.md` from a file, or from stdin when set to `-`.
`--identity`	Add managed authentication with user-owned threads.
`--memory agent\|none`	Optionally write a root memory declaration. If omitted, no memory file is created and durable memory is off.
`--model SPEC`	Model the agent runs on, as `provider:model`.
`--no-sandbox`	Leave out the managed sandbox declaration.
`--channel slack`	Initialize the agent with a Slack channel declaration. Repeatable; `--channels` is an alias.

To include Slack in a new project:

mda init my-agent --channel slack

The command detects the language from the current directory:

Current directory contains	Result
`pyproject.toml` only	Python scaffold.
Both or neither	Interactive language prompt.

The scaffold creates:

File	Description
`agent.py`	Named `agent` export from `define_deep_agent(...)`.
`instructions.md`	Managed system prompt.
`pyproject.toml`	Minimal language-specific manifest.
`README.md`	Local project instructions.
`.env`	Deploy auth and runtime secrets. Do not commit real secrets.
`.gitignore`	Ignores `.env`, `.env.*`, `.mda/`, and dependency caches.

Eval tasks are opt-in and are not created by mda init. Run mda evals init -i from the project root to initialize the Harbor workspace and continue in a coding agent with the eval-engineering skill.

Initialize a Slack channel

Run the following command from the root of an existing managed deep agent project:

mda channel init slack

The command creates a Slack channel declaration in the channels/ directory. The next mda deploy sets up the resources the agent needs to appear in Slack. For the complete workflow, see Connect a Managed Deep Agent to Slack.

Build projects

Use mda build to compile a project into a managed LangGraph app without deploying it:

mda build .

Argument or flag	Use
`path`	Project directory. Defaults to the current directory.
`--out OUT`	Output directory for the compiled app. Defaults to `<path>/.mda/build`. The directory is emptied before the build, so it must be missing, empty, or a directory a previous build wrote.

Evaluate projects

Use mda evals init to initialize a Harbor workspace. The command is also available as mda eval. Use the interactive handoff to develop complete tasks with a coding agent and the eval-engineering skill.

mda evals init -i

Command or flag	Use
`mda evals init`	Create `evals/harbor-job.json` when missing and generate the Harbor adapter and runtime settings under `.mda/evals/`. Run this command from the project root.
`-i`, `--interactive`	Start a detected coding agent with the eval-engineering prompt, or copy the prompt for another agent.

The handoff asks the coding agent to install the eval-engineering skill, inspect the managed agent, and write complete Harbor tasks under evals/<task>/. It also includes the pinned Harbor command that loads the MDA job plugin and LangSmith plugin. mda evals compile is an internal command used by the Harbor job plugin. The plugin runs it when a Harbor job starts, so you do not compile eval artifacts separately. For workflow guidance, see Evals.

Develop locally

Use mda dev to compile a project and run the local LangGraph dev server:

mda dev .

Argument or flag	Use
`path`	Project directory. Defaults to the current directory.
`--port PORT`	Forward a port to the LangGraph dev server.
`--hostname HOSTNAME`	Forward a host to the LangGraph dev server.
`--no-browser`	Prevent the dev server from opening Studio in a browser when it starts.
`--no-reload`	Disable the dev server’s hot reload.

mda dev compiles into .mda/build, then starts the language-specific LangGraph dev server from that directory:

Project language	Dev server command
Python	`uv run --with langgraph-cli[inmem]>=0.4.30 langgraph dev`

Install uv before running mda dev. The CLI resolves the local LangGraph dev server automatically, so you do not need to install langgraph-cli[inmem] yourself. When a sandbox is configured, mda dev tries the configured provider. If provider credentials are unavailable or provider creation fails, it falls back to a local temp-directory sandbox and prints the chosen path. For local development, mda dev stages the project .env file into .mda/build/.env so LangGraph can load model provider keys and other runtime credentials.

Deploy projects

Use mda deploy to compile and deploy a project to LangSmith:

mda deploy .

Argument or flag	Use
`path`	Project directory. Defaults to the current directory.
`--name NAME`	Deployment name. Defaults to the agent `name` from `define_deep_agent`.
`--deployment-type dev\|prod`	Deployment type when creating a deployment. Defaults to `dev`.
`--workspace-id WORKSPACE_ID`	Workspace ID to deploy into. Overrides `LANGSMITH_WORKSPACE_ID`.
`--no-wait`	Trigger the remote build and exit without polling for deployment completion.

Deploy runs these steps:

Validate the project directory and load the agent entry file.
Resolve the LangSmith API key and optional workspace ID.
Collect non-reserved .env values as hosted deployment secrets.
Verify the model provider API key is available from .env, the shell environment, or LangSmith workspace secrets.
Sync deploy-owned context to Context Hub.
Compile the project into .mda/build and extract optional schedules/ and channels/ declarations.
Create or find a LangSmith hosted deployment by name.
Archive the build, upload it, and trigger a remote build.
Poll the revision until it reaches DEPLOYED unless --no-wait is set.
Reconcile the managed LangSmith cron jobs for schedules unless --no-wait is set.
Provision the declared Slack channel. If Slack authorization or workspace approval is required, display the action and continue after you complete it.

A project with a Slack channel cannot use --no-wait because Slack provisioning requires the deployed Agent Server URL. For the complete workflow, see Connect a Managed Deep Agent to Slack. On success, the CLI prints the LangSmith deployment dashboard URL. For secrets routing and deploy tips, see Deploy an agent.

Read deployment logs

Use mda logs to tail Agent Server logs for a deployed agent:

mda logs .

Argument or flag	Use
`path`	Project directory. Defaults to the current directory.
`--name NAME`	Deployment name. Defaults to the agent `name` from the project.
`--lines LINES`	Number of recent log lines to fetch. Defaults to `1000`.
`--level LEVEL`	Only show entries at or above the given severity: `debug`, `info`, `warning`, `error`, or `critical`.
`--follow`	Keep streaming new logs. This is the default in an interactive terminal.
`--no-follow`	Print recent logs and exit. This is the default when output is piped.
`--workspace-id WORKSPACE_ID`	Workspace ID to read from. Overrides `LANGSMITH_WORKSPACE_ID`.

Delete deployments

Use mda delete to delete a deployed Managed Deep Agent and the LangSmith resources it created. mda destroy is an alias.

mda delete .

Argument or flag	Use
`path`	Project directory. Defaults to the current directory.
`--name NAME`	Deployment name. Defaults to the agent `name` from `define_deep_agent`.
`--workspace-id WORKSPACE_ID`	Workspace ID the deployment lives in. Overrides `LANGSMITH_WORKSPACE_ID`.
`--yes`	Delete without asking for confirmation.

Troubleshooting

Symptom	Cause and fix
`project root ... is not a directory`	Pass a directory path to `mda dev` or `mda deploy`.
`no agent entry file found`	Add `agent.py` at the project root.
`mda dev` cannot find `uv`	Install `uv` so `mda dev` can resolve the local LangGraph dev server.
`No LangSmith API key found`	Set `LANGSMITH_API_KEY` or add it to the project `.env`.
Deploy fails with 401 or 403	Confirm the API key belongs to a workspace with beta access.
Deploy reports a missing model provider API key	Add the provider key, such as `OPENAI_API_KEY`, to `.env`, export it in your shell, or configure it as a LangSmith workspace secret.
Deploy reports a Context Hub conflict	The Context Hub repo changed during deploy. Re-run `mda deploy`.
The build exceeds 200 MB	Remove generated artifacts or large files from the project before deploying.
Deployment reaches `BUILD_FAILED` or `DEPLOY_FAILED`	Open the printed deployment URL in LangSmith and inspect the revision logs.

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Edit this page on GitHub or file an issue.

Get started

Agent definition

Build and deploy

Managed Deep Agents CLI reference

Install

Authentication

Command overview

Initialize projects

Initialize a Slack channel

Build projects

Evaluate projects

Develop locally

Deploy projects

Read deployment logs

Delete deployments

Troubleshooting

​Install

​Authentication

​Command overview

​Initialize projects

​Initialize a Slack channel

​Build projects

​Evaluate projects

​Develop locally

​Deploy projects

​Read deployment logs

​Delete deployments

​Troubleshooting

Install

Authentication

Command overview

Initialize projects

Initialize a Slack channel

Build projects

Evaluate projects

Develop locally

Deploy projects

Read deployment logs

Delete deployments

Troubleshooting