/managed-deep-agents

name: managed-deep-agents
description: "INVOKE THIS SKILL when building, testing, or deploying Managed Deep Agents in LangSmith with the mda CLI. Walks a user through their first agent end to end — interviewing them about what they want to build, mapping it onto what MDA can actually do, then scaffolding and deploying it. Covers the file-based project layout; define_deep_agent / defineDeepAgent; instructions, skills, memory, identity, tools, middleware, sandboxes, schedules, channels, and evals; mda init/build/dev/deploy/logs/delete; and Context Hub."

Managed Deep Agents

Overview

Managed Deep Agents (MDA) is a hosted runtime for code-first Deep Agents in LangSmith. You author an agent in Python or TypeScript, test it locally with `mda dev`, and ship it with `mda deploy`. It pairs the open-source Deep Agents harness (see [[deep-agents-core]]) with managed infrastructure: durable runs, sandboxes, Context Hub-backed instructions and skills, memory, traces, and hosted LangGraph deployment.

The core idea is that **an agent is a directory**. A file's location determines its role, and the CLI compiles that directory into a managed LangGraph app.

MDA is in **public beta** and runs on **US LangSmith Cloud only**.

When to use

Use this skill when the user wants to build a Deep Agent in code and run it on LangSmith without operating their own server, or to add tools, middleware, memory, identity, schedules, channels, skills, sandboxes, or evals to one.

Use a standard LangSmith Deployment instead (see [[langgraph-cli]], `langgraph deploy`) when the user needs custom application code, custom HTTP routes, authentication beyond a LangSmith key or Supabase, stronger isolation, maximum scalability, or a region other than US.

---

Guide the user through their first agent

When a user is new to MDA, or says anything like "help me build an agent", **do not scaffold immediately**. Run this flow. It costs two questions and prevents building something the platform cannot host.

ask what they want to build -> check it against the limits -> confirm the shape
-> scaffold -> wire the smallest thing that runs -> mda dev -> deploy

1. Ask what they want to build

Ask in plain language, not in MDA vocabulary. The user does not yet know what a "channel" or a "sandbox" is.

Ask these two things first:

• **What should the agent do?** ("Answer questions about our docs", "triage incoming bugs", "post a summary every morning".)
• **Who or what talks to it, and from where?** (Them in a browser, their app's users, a Slack workspace, nobody — it runs on a timer.)

Then ask only the follow-ups that the answers actually raise:

• Does it need to remember anything between separate conversations?
• Does it need to reach a private API, database, or internal service?
• Should anything require a human to approve before it happens?
• Does it need to write files or run code?

Stop asking once you can name the capabilities. Two or three questions is usually enough.

2. Check the answer against the limits

Before you promise anything, check the request against **[What MDA cannot do](#what-mda-cannot-do)** below. If part of the request is out of scope, say so in one sentence, offer the nearest supported thing, and keep going with the rest. Do not quietly build a smaller agent and present it as what they asked for.

The common redirect: if they need custom HTTP routes, their own auth, or non-US hosting, tell them MDA is the wrong layer and point at `langgraph deploy` ([[langgraph-cli]]).

3. Map the answer onto capabilities

| What the user describes | What to reach for | Where it lives | | --- | --- | --- | | How it should behave, its tone, its rules | Instructions | `instructions.md` | | Calls our API / database / internal service | Authored tools | `tools/` | | A procedure it should follow for certain tasks | Skills | `skills/<name>/SKILL.md` | | Remembers things across conversations | Durable memory (read the warning) | `memory.py` | | Runs on a timer, no user message | Schedules | `schedules/<name>.py` | | Lives in Slack | Channels | `channels/slack.py` | | Writes files, runs code or shell commands | Sandbox | `sandbox/__init__.py` | | Ask me before it does X | Human-in-the-loop | `interrupt_on=` | | Users must not see each other's chats | Supabase identity | `identity.py` | | Must return structured data, not prose | Structured output | `response_format=` | | Hand off specialized work | Subagents | `subagents=` | | PII redaction, call limits, retries, logging | Middleware | `middleware/` | | Prove it still works as we change it | Harbor evals | `evals/tasks/` |

4. Confirm the shape before writing files

State the plan back in one short block and get agreement. Name the model, and list only the capabilities you are actually going to create:

research-assistant, Python, on anthropic:claude-sonnet-4-6
  instructions.md   how it researches and cites
  tools/search.py   web search
  schedules/        weekday 8am digest
  no memory, no sandbox, no channel

5. Scaffold and wire the smallest thing that runs

Scaffold with the flags that match the plan, so the project starts correct instead of being edited into shape:

mda init research-assistant --model anthropic:claude-sonnet-4-6
cd research-assistant
uv sync

Then add **one** capability at a time and confirm each one works before adding the next. A first agent that answers with good instructions and one real tool is a better starting point than a scaffold with every directory filled in.

Do not create directories the plan did not call for. Empty or unused `skills/`, `channels/`, or `schedules/` directories are noise, and a `sandbox/` directory the user does not need turns on a sandbox they will pay attention to for no reason (`mda init --no-sandbox` skips it).

6. Handle keys without touching their secrets

`mda init` writes a `.env` with empty placeholders. Fill in the *names* the project needs and let the u