> ## Documentation Index
> Fetch the complete documentation index at: https://langchain-5e9cc07a-preview-cbdocs-1784316992-3f2f380.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 [Identity](/langsmith/managed-deep-agents-identity), [Custom tools](/langsmith/managed-deep-agents-tools), [Custom middleware](/langsmith/managed-deep-agents-middleware), [Connectors](/langsmith/managed-deep-agents-connectors), [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`, `defineIdentity`, `defineMcpServers`, `defineSchedule`, and `defineSandbox`. The Python package provides `define_deep_agent`, `define_identity`, `define_schedule`, `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
  identity.py | identity.ts               # Optional: caller identity and scoping
  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
  connectors/langsmith.py | langsmith.ts  # Optional: constrained LangSmith capabilities
  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`), identity (`identity.*`), connectors (`connectors/**`), 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).

### Identity

Optionally export a named `identity` declaration from a project-root `identity.ts` or `identity.py` created with `defineIdentity` / `define_identity` (or `.preset(...)`).

When present, `mda` generates the custom auth handler, injects it into the compiled app, and scopes threads, memory, and store access from the declaration. Projects without identity keep the previous compile output. For presets, ingress modes, guest tokens, and `runtime.identity`, see [Identity](/langsmith/managed-deep-agents-identity).

### 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. The runtime remounts a scoped tree as `/memories/user/` (hot `/memories/user/AGENTS.md` plus optional cold files) and optional org facts as `/memories/org/` (read-only). Deploy seeds agent memory when needed and syncs `instructions.md` and `skills/**`, but does not overwrite existing Context Hub `memories/**` files. For hot/cold tiers, identity remounts, org memory, and `disableMemory`, see [Memory](/langsmith/managed-deep-agents-memory).

### Connectors

Declare connectors as modules directly under `connectors/`. Discovery is name-agnostic: each file is a connector module (package `__init__.py` files are ignored).

* **MCP:** `connectors/mcp.ts` or `connectors/mcp.py` must export a named `mcp` declaration. Supports remote `http` and `sse` servers; stdio is rejected. When present, `mda` injects `@langchain/mcp-adapters` or `langchain-mcp-adapters` and appends loaded MCP tools to authored tools.
* **LangSmith:** `connectors/langsmith.ts` or `connectors/langsmith.py` declares constrained LangSmith capabilities for untrusted callers. Requires [identity](/langsmith/managed-deep-agents-identity). The browser never receives `LANGSMITH_API_KEY`.

For examples and defaults, see [Connectors](/langsmith/managed-deep-agents-connectors).

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