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

# Managed Deep Agents CLI reference

> Reference for mda commands, project files, and deploy behavior.

The `mda` CLI compiles and deploys code-first [Managed Deep Agents](/langsmith/python/managed-deep-agents-overview).

It is included with the `managed-deepagents` Python package.

<Note>
  Managed Deep Agents is in **public [beta](/langsmith/release-stages)** and available on [LangSmith Cloud](/langsmith/cloud) in the US region only.
</Note>

For the fastest end-to-end path, see the [quickstart](/langsmith/python/managed-deep-agents-quickstart). For workflow guidance, see [Identity](/langsmith/python/managed-deep-agents-identity), [Memory](/langsmith/python/managed-deep-agents-memory), [Evals](/langsmith/python/managed-deep-agents-evals), [Custom tools](/langsmith/python/managed-deep-agents-tools), [Custom middleware](/langsmith/python/managed-deep-agents-middleware), [Sandboxes](/langsmith/python/managed-deep-agents-sandboxes), [Channels](/langsmith/python/managed-deep-agents-channels), [Schedules](/langsmith/python/managed-deep-agents-schedules), and [Deploy an agent](/langsmith/python/managed-deep-agents-deploy).

## Install

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

```bash uv theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
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:

1. `LANGGRAPH_HOST_API_KEY`
2. `LANGSMITH_API_KEY`
3. `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.

```text .env theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
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 …`               | Scaffold optional Harbor tasks and compile the agent into a Harbor handoff. |
| `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 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:

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
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.                                                                   |

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`. Managed Deep Agents evals are Harbor tasks under `evals/tasks/`. Run `mda evals init <name>` only when you want an optional starter task under `evals/scaffold/`.

## Build projects

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

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
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

`evals/tasks/` is the canonical Harbor dataset. Author complete Harbor tasks there directly. The `mda eval` command, also available as `mda evals`, can scaffold a starter task and package the managed agent for Harbor. MDA prints a `harbor run` command but does not run trials.

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
mda evals init smoke
mda evals compile .
# then run the printed `harbor run` command
```

| Subcommand                 | Use                                                                                                                     |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `mda evals init <name>`    | Create `evals/scaffold/<name>/` with an instruction and a language-native test. Run this command from the project root. |
| `mda evals compile [path]` | Compile the managed agent, copy selected scaffolds into `evals/tasks/`, and write the Harbor handoff under `evals/`.    |

Task names passed to `mda evals init` can contain ASCII letters, numbers, `_`, and `-`.

`mda evals compile` flags:

| Flag                       | Use                                                                                                                                                                                                                                                                              |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--task <name>`            | Select one task. Repeat to select multiple tasks. A selected scaffold refreshes the matching task under `evals/tasks/`. If omitted, all tasks are selected and every scaffold is refreshed. Existing canonical tasks are preserved unless a selected scaffold has the same name. |
| `--model <provider:model>` | Record a model in the artifact manifest. Repeat to record multiple models; the generated job config uses the first value.                                                                                                                                                        |

For Harbor task authoring, optional scaffolding, credentials, and running trials, see [Evals](/langsmith/python/managed-deep-agents-evals).

## Develop locally

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

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
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:

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
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.          |
| `--configure-slack`           | Generate bootstrap and deployed app manifests for the project's single Slack channel. |

Deploy runs these steps:

1. Validate the project directory and load the agent entry file.
2. Resolve the LangSmith API key and optional workspace ID.
3. Collect non-reserved `.env` values as hosted deployment secrets.
4. Verify the model provider API key is available from `.env`, the shell environment, or LangSmith workspace secrets.
5. Sync deploy-owned context to Context Hub.
6. Compile the project into `.mda/build` and extract optional `schedules/` declarations.
7. Create or find a LangSmith hosted deployment by name.
8. Archive the build, upload it, and trigger a remote build.
9. Poll the revision until it reaches `DEPLOYED` unless `--no-wait` is set.
10. Reconcile the managed LangSmith cron jobs for schedules unless `--no-wait` is set.

With `--configure-slack`, deploy requires exactly one Slack channel and a project-root `slack-app-manifest.json`. When the Slack credentials are missing, it writes `.mda/slack/bootstrap-manifest.json` and exits before changing remote state. After you create the app and add its credentials, rerun the waited deployment to write `.mda/slack/app-manifest.json` with the deployed Events URL. For the complete workflow, see [Slack channels](/langsmith/python/managed-deep-agents-channels-slack#create-and-deploy-the-slack-app).

On success, the CLI prints the LangSmith deployment dashboard URL. For secrets routing and deploy tips, see [Deploy an agent](/langsmith/python/managed-deep-agents-deploy).

## Read deployment logs

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

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
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.

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
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.                                                          |

***

<div className="source-links">
  <Callout icon="terminal-2">
    [Connect these docs](/use-these-docs) to Claude, VSCode, and more 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/managed-deep-agents-cli.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).
  </Callout>
</div>