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. It is included with the managed-deepagents npm and Python packages.

Managed Deep Agents is in private beta, available on LangSmith Cloud in the US region only. Join the waitlist to request access.

For the fastest end-to-end path, see the quickstart. For workflow guidance, see Custom tools, Custom middleware, Connect MCP tools, Schedules, and Deploy an agent.

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.

pip

pip install --pre managed-deepagents

npm install -g managed-deepagents@dev

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.

.env

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:

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:

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:

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.

Project file reference

Managed Deep Agents projects use a code-first layout:

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.

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 and Custom 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.

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.

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.

Ignored paths

The project loader skips these directories:

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.

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.

---

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

Edit this page on GitHub or file an issue.