> ## Documentation Index
> Fetch the complete documentation index at: https://langchain-5e9cc07a-preview-docscl-1783712772-37c510e.mintlify.site/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 tests and deploys code-first [Managed Deep Agents](/langsmith/managed-deep-agents-overview). It is included with the `managed-deepagents` npm and Python packages.

<Note>
  Managed Deep Agents is in **private [beta](/langsmith/release-stages)**, available on [LangSmith Cloud](/langsmith/cloud) in the US region only. [Join the waitlist](https://www.langchain.com/langsmith-managed-deep-agents-waitlist) to request access.
</Note>

For the fastest end-to-end path, see the [quickstart](/langsmith/managed-deep-agents-quickstart). For workflow guidance, see [Custom tools](/langsmith/managed-deep-agents-tools), [Custom middleware](/langsmith/managed-deep-agents-middleware), [Connect MCP tools](/langsmith/managed-deep-agents-mcp), [Schedules](/langsmith/managed-deep-agents-schedules), and [Deploy an agent](/langsmith/managed-deep-agents-deploy).

## Install

Install the package for the language you use to author your agent. Both packages expose the `mda` binary. For npm, install globally or run the binary with `npm exec`.

<CodeGroup>
  ```bash pip theme={null}
  pip install --pre managed-deepagents
  ```

  ```bash npm theme={null}
  npm install -g managed-deepagents@dev
  ```
</CodeGroup>

For Python, `pip install --pre managed-deepagents` installs the `mda` CLI. A Python 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 TypeScript package provides `defineDeepAgent`, `defineMcpServers`, and `defineSandbox`. The Python package provides `define_deep_agent`, `define_sandbox`, the `managed_deepagents.connectors` module, and 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={null}
LANGSMITH_API_KEY=<LANGSMITH_API_KEY>
OPENAI_API_KEY=<OPENAI_API_KEY>
```

To deploy with an organization-scoped key, set `LANGSMITH_TENANT_ID` or pass `--tenant-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_TENANT_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 TypeScript or Python Managed Deep Agents project.        |
| `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. |

## Initialize projects

Use `mda init` to create a new project directory:

```bash theme={null}
mda init my-agent
```

| Argument | Use                                                                                   |
| -------- | ------------------------------------------------------------------------------------- |
| `name`   | Required project directory name. The command fails if the destination already exists. |

The command detects the language from the current directory:

| Current directory contains | Result                       |
| -------------------------- | ---------------------------- |
| `package.json` only        | TypeScript scaffold.         |
| `pyproject.toml` only      | Python scaffold.             |
| Both or neither            | Interactive language prompt. |

The scaffold creates:

| File                               | Description                                                                   |
| ---------------------------------- | ----------------------------------------------------------------------------- |
| `agent.py` or `agent.ts`           | Named `agent` export from `define_deep_agent(...)` or `defineDeepAgent(...)`. |
| `instructions.md`                  | Managed system prompt.                                                        |
| `pyproject.toml` or `package.json` | 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.                     |

## Develop locally

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

```bash theme={null}
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.                              |
| `--browser`           | Open a browser when the dev server starts. By default, no browser opens. |
| `--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                                         |
| ---------------- | ---------------------------------------------------------- |
| TypeScript       | `npx --yes @langchain/langgraph-cli dev`                   |
| Python           | `uv run --with langgraph-cli[inmem]>=0.4.30 langgraph dev` |

For Python projects, 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 connector tokens.

## Deploy projects

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

```bash theme={null}
mda deploy .
```

| Argument or flag              | Use                                                                                                             |
| ----------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `path`                        | Project directory. Defaults to the current directory.                                                           |
| `--name NAME`                 | Deployment name. Defaults to the project directory name, normalized to lowercase letters, numbers, and hyphens. |
| `--deployment-type dev\|prod` | Deployment type when creating a deployment. Defaults to `dev`.                                                  |
| `--tenant-id TENANT_ID`       | Workspace or tenant ID. Overrides `LANGSMITH_TENANT_ID`.                                                        |
| `--host-url URL`              | Host backend API URL override. Defaults to US LangSmith Cloud.                                                  |
| `--no-wait`                   | Trigger the remote build and exit without polling for deployment completion.                                    |

Deploy runs these steps:

1. Validate the project directory and load the agent entry file.
2. Resolve the LangSmith API key and optional tenant 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.

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

## Project file reference

Managed Deep Agents projects use a code-first layout:

```text theme={null}
my-agent/
  agent.py | agent.ts | agent.tsx         # Required: exports the named agent
  instructions.md                         # Managed system prompt, synced to Context Hub
  pyproject.toml | package.json           # Project dependencies
  .env                                    # Deploy auth and runtime secrets (never archived)
  tools/                                  # Authored LangChain tools the agent imports
  middleware/                             # Authored middleware the agent imports
  connectors/mcp.py | connectors/mcp.ts   # Remote MCP server declarations
  schedules/<name>.py | <name>.ts         # Managed cron schedules
  skills/<name>/SKILL.md                  # Deploy-owned skills, synced to Context Hub
  sandbox/__init__.py | sandbox/index.ts  # Managed sandbox configuration
  sandbox/setup.sh                        # Sandbox provisioning script
```

The only required file is the agent entry: `agent.py`, `agent.ts`, or `agent.tsx`. It must export a named `agent` definition created with `define_deep_agent` or `defineDeepAgent`. The `tools/` and `middleware/` folders are conventions, not special registries: Managed Deep Agents packages regular project files, so any local module the agent imports works. When present, the CLI treats the remaining files as the managed system prompt (`instructions.md`), MCP connectors (`connectors/mcp.*`), cron schedules (`schedules/**`), skills (`skills/**`), and sandbox configuration (`sandbox/`).

Only a project-root `agent.ts`, `agent.tsx`, or `agent.py` is required. The CLI detects the first available entry in that order.

### Agent entry

The agent entry must export a named `agent` definition created with `define_deep_agent` or `defineDeepAgent`. For a minimal example, see the [quickstart](/langsmith/managed-deep-agents-quickstart#edit-the-agent).

The definition accepts the Deep Agents `createDeepAgent` configuration surface except managed keys. Setting a managed key is an error.

### Authored tools and middleware

Put project-owned tools and middleware in local modules such as `tools/` and `middleware/`, import them from the agent entry, and pass them through the `tools` and `middleware` fields. The CLI copies those files into the compiled build without rewriting them.

For examples, see [Custom tools](/langsmith/managed-deep-agents-tools) and [Custom middleware](/langsmith/managed-deep-agents-middleware).

### Instructions

Put the system prompt in `instructions.md` next to the project-root agent entry file.

`mda dev` embeds the prompt in the generated entry. `mda deploy` syncs the prompt to Context Hub and the deployed runtime reads it from there.

### Skills

Put deploy-owned skills under `skills/` next to the project-root agent entry file. Deploy syncs every UTF-8 file under `skills/**` into Context Hub and deletes stale deployed skills that no longer exist locally.

### Memory

Managed memory lives in the same Context Hub repo as the deployed instructions and skills, at `/memories/AGENTS.md`. Deploy creates that file if memory is enabled and it does not exist. Deploy syncs `instructions.md` and `skills/**`, but does not overwrite local or existing Context Hub `memories/**` files.

### Connectors

Declare remote MCP servers in `connectors/mcp.ts` or `connectors/mcp.py`. The module must export a named `mcp` declaration.

Connectors support remote `http` and `sse` MCP servers. Stdio MCP servers are rejected. When connectors are present, `mda` injects `@langchain/mcp-adapters` or `langchain-mcp-adapters` into the compiled build and appends loaded MCP tools to authored tools.

For examples, server options, and connector defaults, see [Connect MCP tools](/langsmith/managed-deep-agents-mcp).

### Schedules

Declare managed cron schedules under `schedules/`. Each direct child schedule file must export a named `schedule` declaration from `defineSchedule(...)` or `define_schedule(...)`.

Deploy extracts schedule declarations from static literals, arrays, objects, and top-level literal constants. After the deployment reaches `DEPLOYED`, `mda deploy` replaces the existing managed LangSmith cron jobs with the current local schedule declarations. For examples and constraints, see [Schedules](/langsmith/managed-deep-agents-schedules).

### Sandbox

To configure a managed sandbox, export `sandbox` from `sandbox/index.ts` for TypeScript or `sandbox/__init__.py` for Python. Sandboxes are scoped per thread. `sandbox/setup.sh`, when present, runs once when a new managed sandbox is provisioned for a thread.

For configuration examples and lifecycle behavior, see [Configure a sandbox](/langsmith/managed-deep-agents-deploy#configure-a-sandbox).

### Ignored paths

The project loader skips these directories:

```text theme={null}
node_modules, .git, .mda, .deepagents, memories, dist, build
```

It also skips `.env` and `.env.*` files when copying files into the compiled build. `mda dev` stages the root `.env` into `.mda/build/.env` for local development only; deploy still forwards non-reserved `.env` entries as hosted secrets instead of archiving the file.

## Agent definition reference

`define_deep_agent` and `defineDeepAgent` accept the full Deep Agents `create_deep_agent` configuration surface except the managed keys. Set author-owned fields to configure behavior.

### Author-set fields

| Field (Python / TypeScript)          | Purpose                                                        |
| ------------------------------------ | -------------------------------------------------------------- |
| `model`                              | The chat model instance or `{provider}:{model_id}` identifier. |
| `tools`                              | Authored tools imported into the agent entry.                  |
| `middleware`                         | Ordered list of middleware around model and tool calls.        |
| `subagents`                          | Subagent definitions the agent can delegate to.                |
| `permissions`                        | Tool permission rules.                                         |
| `interrupt_on` / `interruptOn`       | Tool calls that pause for human review before running.         |
| `response_format` / `responseFormat` | Structured output format.                                      |
| `context_schema` / `contextSchema`   | Schema for per-run runtime context.                            |
| `name`                               | Agent name.                                                    |
| `cache`                              | Model cache configuration.                                     |
| `debug`                              | Enable debug behavior.                                         |
| `disable_memory` / `disableMemory`   | Disable only the managed agent memory.                         |

### Managed fields

The managed runtime owns `backend`, `store`, `checkpointer`, `memory`, `skills`, and the system prompt. Do not set those fields in the agent definition.

| Concern                                         | Owner                                  | Where you configure it                                              |
| ----------------------------------------------- | -------------------------------------- | ------------------------------------------------------------------- |
| `backend`, `store`, `checkpointer`              | Managed runtime                        | Not configurable.                                                   |
| `memory`                                        | Managed runtime, backed by Context Hub | `disableMemory` / `disable_memory` to turn off agent-scoped memory. |
| `skills`                                        | Managed runtime, backed by Context Hub | `skills/**` in the project.                                         |
| System prompt                                   | Managed runtime, backed by Context Hub | `instructions.md` in the project.                                   |
| Model, tools, middleware, subagents, interrupts | You                                    | The agent definition and imported modules.                          |

For the full field list, see the [agent definition reference](/langsmith/managed-deep-agents-cli#agent-definition-reference).

## 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.ts`, `agent.tsx`, or `agent.py` at the project root.                                                                      |
| `mda dev` cannot find `uv`                           | For Python projects, 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>