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

# Deploy a Managed Deep Agent

> Test and deploy a Managed Deep Agent with the mda CLI.

Deploying a Managed Deep Agent compiles a code-first project into a managed LangGraph app, syncs deploy-owned context to [Context Hub](/langsmith/use-the-context-hub), uploads the compiled source, and triggers a LangSmith hosted deployment build.

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

This page covers secrets routing, local development behavior, sandbox configuration, and deploy tips. For command flags, the deploy step list, and troubleshooting, see the [CLI reference](/langsmith/managed-deep-agents-cli).

<Tip>
  For a conceptual walkthrough of compilation, the deploy lifecycle diagram, Context Hub, threads, and sandboxes, see [How Managed Deep Agents work](/langsmith/managed-deep-agents-how-it-works).
</Tip>

## Prerequisites

Before you deploy, make sure you have:

* A workspace with Managed Deep Agents [private beta access](https://www.langchain.com/langsmith-managed-deep-agents-waitlist).
* A [LangSmith API key](/langsmith/create-account-api-key) for that workspace, either in `.env` or your shell environment.
* The `mda` CLI installed from `managed-deepagents`.
* Project dependencies installed with `npm install` for TypeScript projects or `uv sync` for generated Python projects.
* Model provider credentials, such as `OPENAI_API_KEY`, in `.env`, your shell environment, or LangSmith workspace secrets.

The CLI targets US LangSmith Cloud by default.

## Project files

A Managed Deep Agents project starts with an agent entry and optional project folders. Create a project with `mda init`, or adapt an existing TypeScript or Python project by adding `agent.ts`, `agent.tsx`, or `agent.py` at the project root.

For the full file layout and packaging rules, see the [CLI project file reference](/langsmith/managed-deep-agents-cli#project-file-reference). To define the agent entry, tools, middleware, and interrupts, see the [quickstart](/langsmith/managed-deep-agents-quickstart#edit-the-agent).

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

## Configure instructions, skills, and memory

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

```markdown instructions.md theme={null}
# Assistant

You are a careful assistant. Use available tools when needed and cite sources.
```

Put deploy-owned skills under `skills/` next to the project-root agent entry file. Deploy syncs `instructions.md` and `skills/**` to the Context Hub repo associated with the deployment.

Managed memory is stored in the same Context Hub repo under `memories/**` and remounted for the agent as `/memories/user/` (hot `/memories/user/AGENTS.md`). Deploy syncs `instructions.md` and `skills/**`, but preserves memory and does not overwrite `memories/**`. To disable managed memory, set `disableMemory: true` or `disable_memory=True` in the agent definition.

## Add tools, connectors, and middleware

Add authored tools and middleware directly in the agent source. Managed Deep Agents copies your project files into the compiled build, so imports from `tools/`, `middleware/`, or other local modules work like they do in a normal Python or TypeScript project.

* Use [custom tools](/langsmith/managed-deep-agents-tools) for business logic, private APIs, database access, and other project-owned code.
* Use [custom middleware](/langsmith/managed-deep-agents-middleware) for cross-cutting behavior around model calls, tool calls, lifecycle hooks, retries, limits, and data handling.
* Declare remote MCP servers in `connectors/mcp.ts` or `connectors/mcp.py`; Managed Deep Agents loads those connector tools and appends them to the authored tools at runtime. For examples and guidance, see [Connectors](/langsmith/managed-deep-agents-connectors).
* Optionally declare [identity](/langsmith/managed-deep-agents-identity) in `identity.ts` or `identity.py` to authenticate callers and scope threads and memory.

To pause for human approval before sensitive tool calls, set `interrupt_on` in the agent definition. See [Human-in-the-loop](/langsmith/managed-deep-agents-middleware#human-in-the-loop).

## Add schedules

Add managed cron schedules under `schedules/` when the agent should run on a recurring cadence. Each schedule file exports a named `schedule` declaration created with `defineSchedule` or `define_schedule`.

For examples and schedule constraints, see [Schedules](/langsmith/managed-deep-agents-schedules).

## Configure a sandbox

Use a sandbox when the agent needs isolated code execution or filesystem work. Export `sandbox` from `sandbox/index.ts` or `sandbox/__init__.py`.

<CodeGroup>
  ```python sandbox/__init__.py theme={null}
  from managed_deepagents import define_sandbox
  from deepagents.backends import LangSmithSandbox

  sandbox = define_sandbox(
      LangSmithSandbox,
      scope="thread",
      idle_ttl_seconds=600,
      default_timeout=600,
  )
  ```

  ```ts sandbox/index.ts theme={null}
  import { defineSandbox } from "managed-deepagents";
  import { LangSmithSandbox } from "deepagents";

  export const sandbox = defineSandbox(LangSmithSandbox, {
    scope: "thread",
    idleTtlSeconds: 600,
    defaultTimeout: 600,
  });
  ```
</CodeGroup>

Sandboxes are scoped per thread. Each durable thread or conversation gets its own sandbox.

If `sandbox/setup.sh` exists, Managed Deep Agents runs it once when a new managed sandbox is provisioned. Use it to install packages, seed files, or prepare workspace state.

For sandbox scope and lifecycle during local development, see [How Managed Deep Agents work](/langsmith/managed-deep-agents-how-it-works#sandboxes).

## Run locally

Run the local LangGraph dev server:

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

`mda dev` compiles into `.mda/build` and starts the matching LangGraph dev server from that directory. Pass `--port`, `--hostname`, `--browser`, or `--no-reload` to forward local dev server options.

For local development, `mda dev` stages the project `.env` file into `.mda/build/.env` so LangGraph can load model provider keys and connector tokens.

For Python projects, `mda dev` requires `uv` on `PATH` and resolves the local LangGraph dev server automatically.

When a sandbox is configured, `mda dev` tries the configured provider and falls back to a local temp-directory sandbox when provider credentials are unavailable. The local fallback is intended only for development.

For all `mda dev` flags, see the [CLI reference](/langsmith/managed-deep-agents-cli#develop-locally).

## Deploy to LangSmith

Deploy the local project:

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

<Tip>
  `mda deploy` routes local project inputs to different managed surfaces:

  ```text theme={null}
  instructions.md + skills/**  -> Context Hub deploy-owned context
  memories/**                  -> ignored; existing Context Hub memory is preserved
  .env                         -> deploy auth + non-reserved hosted secrets, not archived
  project source files         -> .mda/build source archive -> hosted deployment
  schedules/**                 -> LangSmith cron jobs after the deployment is live
  ```
</Tip>

Set the deployment name explicitly when the directory name is not the name you want:

```bash theme={null}
mda deploy . --name research-assistant
```

Use `--deployment-type prod` when creating a production deployment:

```bash theme={null}
mda deploy . --deployment-type prod
```

Use `--no-wait` to trigger the build without polling for completion:

```bash theme={null}
mda deploy . --no-wait
```

When `--no-wait` is set, schedule reconciliation is skipped for that deploy invocation because the CLI exits before the deployment reaches `DEPLOYED`.

On success, the CLI prints the LangSmith deployment dashboard URL. For the full deploy step list, see the [CLI reference](/langsmith/managed-deep-agents-cli#deploy-projects).

## Secrets and environment files

`mda deploy` reads project `.env` values before shell environment variables. Use `.env` for the LangSmith API key that authenticates the deploy and for runtime secrets the hosted deployment needs:

```text .env theme={null}
LANGSMITH_API_KEY=<LANGSMITH_API_KEY>
OPENAI_API_KEY=<OPENAI_API_KEY>
GITHUB_MCP_TOKEN=<GITHUB_MCP_TOKEN>
DATABASE_URL=<DATABASE_URL>
```

`LANGSMITH_API_KEY`, `LANGGRAPH_HOST_API_KEY`, `LANGCHAIN_API_KEY`, and other platform variables are reserved. They can authenticate the deploy, but they are not uploaded as user-managed deployment secrets.

Non-reserved `.env` entries, such as model provider keys, MCP tokens, and custom tool credentials, are forwarded as hosted deployment secrets when `mda deploy` creates or updates the deployment. If the configured model requires a provider key, deploy fails before upload unless that key is available from `.env`, the shell environment, or LangSmith workspace secrets. When the provider key is only in the shell environment, `mda deploy` forwards it as a secret for that deploy.

Reserved platform variables, empty values, `.env`, and `.env.*` files are not copied into the compiled build archive.

For authentication key order and reserved variables, see the [CLI reference](/langsmith/managed-deep-agents-cli#authentication).

## Troubleshoot a deploy

For deploy troubleshooting, see the [CLI reference](/langsmith/managed-deep-agents-cli#troubleshooting).

If a deployment reaches `BUILD_FAILED` or `DEPLOY_FAILED`, open the printed deployment URL in LangSmith and inspect the revision logs.

## Next steps

<CardGroup cols={2}>
  <Card title="Identity" icon="fingerprint" href="/langsmith/managed-deep-agents-identity">
    Authenticate callers and scope threads and memory.
  </Card>

  <Card title="Connectors" icon="plug" href="/langsmith/managed-deep-agents-connectors">
    Attach MCP servers or constrained LangSmith capabilities.
  </Card>

  <Card title="Schedules" icon="calendar" href="/langsmith/managed-deep-agents-schedules">
    Run agents on managed cron schedules.
  </Card>

  <Card title="Custom tools" icon="tool" href="/langsmith/managed-deep-agents-tools">
    Add authored LangChain tools to the agent definition.
  </Card>

  <Card title="CLI reference" icon="terminal" href="/langsmith/managed-deep-agents-cli">
    Look up every `mda` command and flag.
  </Card>
</CardGroup>

***

<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-deploy.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).
  </Callout>
</div>