Skip to main content
Deploy a hosted Deep Agent without setting up infrastructure. This quickstart scaffolds a code-first project, runs the agent locally, edits the managed system prompt, and deploys it with mda. To build a fuller agent step by step, follow the tutorial. For the full deploy workflow and all CLI flags, see Deploy an agent and the CLI reference.
Managed Deep Agents is in private beta, available on LangSmith Cloud in the US region only. Join the waitlist to request access.

​
Prerequisites

Before you start, make sure you have:
  • An organization with Managed Deep Agents private beta access.
  • A LangSmith API key.
  • Python and uv for Python projects, or Node.js and npm for TypeScript projects.
  • An API key for your model provider of choice.

​
Create and deploy an agent

1

Install the package

Install managed-deepagents for the language you want to author in. Both packages include the mda CLI.
pip install --pre managed-deepagents

npm install -g managed-deepagents@dev
For Python, the pip command installs the mda CLI. After you scaffold a project, run uv sync inside that project to install the dependencies from its generated pyproject.toml.
2

Create a project

Create a Managed Deep Agents project:
mda init research-assistant
cd research-assistant
The CLI detects pyproject.toml or package.json in the current directory. If it cannot infer a language, it prompts you to choose Python or TypeScript.The scaffold creates:
FilePurpose
agent.py or agent.tsThe named agent definition compiled by mda.
instructions.mdManaged system prompt embedded locally and synced to Context Hub on deploy.
pyproject.toml or package.jsonMinimal project manifest with managed-deepagents.
README.mdLocal project notes and deploy command.
.envDeploy auth and runtime secrets. Do not commit real secrets.
.gitignoreIgnores .env, .env.*, .mda/, and dependency caches.
For the full project layout, see the CLI project file reference.
3

Add API keys to `.env`

Open the generated .env file and add your LangSmith API key plus the provider key for the model you plan to use:
.env
LANGSMITH_API_KEY=<LANGSMITH_API_KEY>
OPENAI_API_KEY=<OPENAI_API_KEY>
LANGSMITH_API_KEY authenticates mda deploy. Provider keys, MCP tokens, database URLs, and other non-reserved .env values are sent to the hosted deployment as secrets when you deploy. The .env file itself is not uploaded in the source archive.The CLI targets US LangSmith Cloud by default. To deploy with an organization-scoped key, set LANGSMITH_TENANT_ID in .env or pass --tenant-id to mda deploy.
If a request returns 401 or 403, confirm the key belongs to a workspace with beta access.
4

Edit the agent

Open the generated agent.py or agent.ts and configure the model, tools, middleware, and interrupts in code.
from managed_deepagents import define_deep_agent

agent = define_deep_agent(
    model="openai:gpt-5.5",
)

import { defineDeepAgent } from "managed-deepagents";

export const agent = defineDeepAgent({
  model: "openai:gpt-5.5",
});
The managed runtime owns backend, store, checkpointer, memory, skills, and the system prompt. Do not set those fields in the agent definition.
ConcernOwnerWhere you configure it
backend, store, checkpointerManaged runtimeNot configurable.
memoryManaged runtime, backed by Context HubdisableMemory / disable_memory to turn off agent-scoped memory.
skillsManaged runtime, backed by Context Hubskills/** in the project.
System promptManaged runtime, backed by Context Hubinstructions.md in the project.
Model, tools, middleware, subagents, interruptsYouThe agent definition and imported modules.
For the full field list, see the agent definition reference.The generated model uses OpenAI. If you use another provider, change the model identifier and set the API key required by that provider in .env, your shell environment, or LangSmith workspace secrets.
5

Edit the instructions

Open instructions.md and replace the generated prompt with the behavior you want:
instructions.md
# Research assistant

You are a careful research assistant. Search for sources, keep notes, and return
concise answers with citations.
mda dev embeds this file into the generated local entry module. mda deploy syncs it to Context Hub and the deployed runtime reads it from there.
6

Run locally

Install the generated project dependencies, then start the local LangGraph dev server:
uv sync
mda dev .

npm install
mda dev .
For TypeScript projects, mda dev runs npx --yes @langchain/langgraph-cli dev. For Python projects, it uses uv to resolve and run the local LangGraph dev server automatically. You do not need to install langgraph-cli[inmem] yourself.mda dev loads the project .env file from the compiled local build so model provider keys and connector tokens are available during local development.
7

Deploy the agent

Deploy the local project:
mda deploy .
On success, the CLI prints the LangSmith deployment dashboard URL:
Deployment live
Deployment dashboard
https://smith.langchain.com/o/<tenant-id>/host/deployments/<deployment-id>
Deployed 'research-assistant' to LangSmith.
Open the printed URL in LangSmith to inspect build status, revisions, and traces.

​
Next steps

Quickstart

Deploy a first code-first agent with the mda CLI.

Tutorial

Build a scheduled research agent from an empty directory.

How it works

Understand compilation, the deploy lifecycle, and Context Hub.

Custom tools

Add authored LangChain tools from your project source.

Custom middleware

Add built-in or custom middleware around model and tool calls.

Connect MCP tools

Declare remote MCP servers with Managed Deep Agents connectors.

Schedules

Run agents on managed cron schedules.

Deploy an agent

Test and deploy Managed Deep Agents with mda.

Examples

Explore a complete project that uses every primitive.

CLI reference

Review mda init, mda dev, and mda deploy.
Connect these docs to Claude, VSCode, and more via MCP for real-time answers.
Edit this page on GitHub or file an issue.