How to scaffold and deploy a Managed Deep Agent with the mda CLI

Managed Deep Agents (MDA) is the simplest way to build and deploy production agents: you write what the agent does, and MDA runs it. There are no servers to operate and no infrastructure to wire together. You author the intelligence in a project folder—instructions, tools, skills, and the model. MDA supplies the Deep Agents harness (the loop that plans, calls tools, manages a filesystem, and delegates to subagents) plus a managed runtime on LangSmith Deployment’s Agent Server, including sandboxes and schedules.

MDA is in public beta on LangSmith Cloud, and only in the US region. This walkthrough follows the official Python quickstart: scaffold with the mda CLI, configure a research assistant with web search, chat with it in LangSmith Studio, then deploy.

What you author vs what MDA runs

A managed deep agent is a project folder of business logic. Upload that folder with the mda CLI and it runs on managed LangSmith infrastructure.

You provide

Instructions
Tools
Skills
Model

MDA provides

Deep Agents harness: agent loop, filesystem, subagents
Managed runtime: Agent Server, sandboxes, schedules

Capabilities map to files. agent.py is required (model and core options). Add the rest only if you need them: instructions.md, skills/, tools/, connectors/, middleware/, sandbox/, memory.py, identity.py, channels/, schedules/, and evals/.

Prerequisites

To follow the quickstart you need:

Python and uv
An API key for your model provider of choice
A LangSmith account and API key—the same key authenticates mda dev, mda deploy, and LangSmith Studio so you can chat and inspect traces

Optional: add the coding-agent skill

The managed-deep-agents skill walks a coding agent through building, testing, and deploying with the mda CLI. To add it to the current project:

npx skills add langchain-ai/langchain-skills --skill managed-deep-agents --yes

Scaffold the project

Install the CLI, create a project, and enter it:

uv tool install managed-deepagents
mda init research-assistant
cd research-assistant

That gives you the scaffolding. The agent name is also the default deployment name.

Put keys in `.env`

Add your model provider key. The quickstart uses OpenAI by default:

OPENAI_API_KEY=<OPENAI_API_KEY>
# ANTHROPIC_API_KEY=<ANTHROPIC_API_KEY>
# GOOGLE_API_KEY=<GOOGLE_API_KEY>

If you choose Google or Anthropic in the next step, set that provider’s API key instead. mda deploy adds the provider key to the deployment. You can also use other chat providers documented for LangChain. Do not commit .env; it contains secrets.

Then add LangSmith. Create an API key under Settings → API Keys, and put it in .env:

LANGSMITH_API_KEY=<LANGSMITH_API_KEY>

Write the instructions

Open instructions.md and describe how the agent should behave. The official research-assistant example:

# Research assistant

You are a careful research assistant. Use internet search to find sources,
keep notes, and return concise answers with citations.

On deploy, Managed Deep Agents syncs these instructions to LangSmith Context Hub, where you can update them without redeploying the agent.

Configure the model and search

Edit agent.py. Google, OpenAI, and Anthropic offer server-side search with no extra package or API key. Pass the provider tool dict that matches your model. If search never appears, confirm the provider tool dict.

OpenAI (quickstart default):

from managed_deepagents import define_deep_agent

# OpenAI's built-in web search — no extra install or API key needed
agent = define_deep_agent(
 name="research-assistant",
 model="openai:gpt-5.5",
 tools=[{"type": "web_search"}],
)

Google:

from managed_deepagents import define_deep_agent

# Google's built-in web search — no extra install or API key needed
agent = define_deep_agent(
 name="research-assistant",
 model="google_genai:gemini-3.6-flash",
 tools=[{"google_search": {}}],
)

Anthropic:

from managed_deepagents import define_deep_agent

agent = define_deep_agent(
 name="research-assistant",
 model="anthropic:claude-sonnet-4-6",
 tools=[{"type": "web_search_20260209", "name": "web_search"}],
)

Prefer Tavily instead? Refer to official documentation for exact syntax.

Run locally in LangSmith Studio

Install project dependencies and start the agent:

uv sync
mda dev .

mda dev loads API keys from .env, starts a local Agent Server, and opens the agent in LangSmith Studio. Send:

What were the main announcements from the latest LangChain release?

You should see the agent call the web search tool, then return a concise answer with citations.

Deploy to LangSmith Agent Server

mda deploy .

Managed Deep Agents packages the project and runs it as a hosted deployment on LangSmith Agent Server. When deployment finishes, the CLI prints the deployment dashboard URL. Open that URL, confirm the deployment is in a ready state, and send the same research question. The hosted agent should return an answer with a search tool call. Use LangSmith observability after a run if you need to inspect execution.

Next step

On the same project, follow the official Managed Deep Agents tutorial linked from the quickstart’s next-steps section. It adds a custom Tavily search tool, durable memory, and a daily schedule—the natural extension once mda deploy has a ready research assistant.