Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

Python authoring package and CLI launcher for Managed Deep Agents.

[!IMPORTANT] Public beta. Managed Deep Agents is in public beta. The PyPI package API and managed runtime contract may change. See the docs for getting started and updates.

managed-deepagents is the PyPI package for authoring Managed Deep Agents in Python. It includes:

  • define_deep_agent, the Python authoring contract for managed agents.
  • define_schedule, the Python contract for managed cron schedules.
  • mda, the CLI used to build and deploy your agent to LangSmith.
  • managed_deepagents.runtime, the runtime helper used by generated managed entry modules.

Install

uv tool install managed-deepagents

[!NOTE] Private beta: dev releases only. We currently publish only PEP 440 pre-release (dev) versions and no stable version yet. uv skips pre-releases by default unless they are allowed explicitly:

uv tool install --prerelease allow managed-deepagents

This package requires Python 3.9 or newer. Each platform wheel bundles the prebuilt mda binary for its OS and CPU architecture and exposes it through the mda console script. This PyPI-installed CLI scaffolds and compiles Python projects only and vendors the Python runtime bundled with this wheel.

To start a new project, run mda init. In a terminal, the CLI asks you to name the agent:

mda init

Run mda init -i to initialize your agent interactively and optionally hand it off to a coding agent to build:

mda init -i

Choose a coding agent to continue in the new project, or select View raw prompt to copy the setup instructions.

For coding agents and other headless use, pass the project name:

mda init my-agent

mda init can shape the project up front — --instructions "..." (or --instructions-file <path>) writes the system prompt, --model <spec> picks the model, --memory agent opts into deployment-shared durable memory, --no-sandbox leaves out the sandbox, and -c slack (also --channel / --channels) writes channels/slack.py. Every new project includes an identity.py that explicitly selects auth.langsmith_api_key() authentication.

mda init my-agent --gateway runs the agent on LangSmith Gateway — a model LangSmith hosts, billed to your workspace's Gateway Credits, authenticated with a LangSmith API key instead of a model provider key of your own. It is mutually exclusive with --model, which names a provider you hold the key for.

Evaluate

Managed Deep Agent evals run in Harbor. Install uv and Docker before running them.

  1. From the project root, initialize the eval workspace:

    mda evals init -i
    
  2. Follow the coding-agent prompt to author tasks directly under evals/<task>/. The CLI creates the user-owned evals/harbor-job.json once and preserves later edits. .mda/evals/ is generated. A task may include an authored evals/<task>/identity.json fixture. It requires a non-empty user.id; user.kind, user.email, and top-level groups, claims, and source.provider are optional. Keep it with the task, not in generated .mda/evals/.

  3. Export LANGSMITH_API_KEY, LANGSMITH_WORKSPACE_ID when your credentials require it, and the model or tool credential variables used by the agent.

  4. From the same project root, run the pinned Harbor 0.21.0 command included at the end of the coding-agent prompt. The command loads MDAJobPlugin and LangSmithPlugin. It uses POSIX syntax on macOS/Linux and PowerShell on native Windows.

  5. From the same project root, inspect results:

    uv run --python 3.12 --with 'harbor[langsmith]==0.21.0' harbor view .mda/evals/jobs
    

MDAJobPlugin compiles a fresh eval artifact at every Harbor job start. This POC keeps MDA's custom Harbor adapter; migration to Harbor's built-in LangGraph agent is deferred.

Define an Agent

Create an agent.py that defines an agent:

from managed_deepagents import define_deep_agent

# The system prompt comes from instructions.md next to this file.
agent = define_deep_agent(
    name="research-assistant",
    model="openai:gpt-5.5",
    tools=[query_db],
)

define_deep_agent requires a static name (LangGraph assistant id and default LangSmith deployment name) and otherwise accepts the create_deep_agent keyword surface minus the managed keys: backend, store, checkpointer, memory, skills, and system_prompt. Those are provided by the managed runtime when your agent is deployed. Write the system prompt in instructions.md next to agent.py; the CLI embeds it at deploy time.

To authenticate SDK and API requests with a LangSmith workspace key while retaining MDA's thread and store authorization, declare it explicitly:

identity = define_identity(auth=auth.langsmith_api_key())

Clients send the key as x-api-key. LangSmith Cloud supplies the verification endpoint and tenant configuration; do not add those platform-owned values to the project .env.

On deploy, Context Hub stores harness files (instructions.md, skills/**). A root memory.py declaring define_memory(scope="agent") additionally mounts one deployment-shared memory tree at /memories/agent/. /memories/agent/AGENTS.md is injected every turn; other files are read on demand. Deploy never overwrites existing memories. Memory is independent of identity, and a project without memory.py mounts no durable memory.

Project Shape

my-agent/
  agent.py              # named `agent` variable
  identity.py           # managed authentication (included by `mda init`)
  instructions.md       # managed system prompt
  pyproject.toml
  .env                  # local deploy secrets, never committed
  schedules/            # optional managed cron schedules
  tools/                # optional custom tools
  middleware/           # optional middleware
  skills/               # optional skills synced to Context Hub
  sandbox/              # LangSmith sandbox (`mda init` includes this; delete to opt out)
  connectors/mcp.py     # optional MCP server declaration

The CLI copies your project files into the managed build and generates the entry module that connects your definition to the hosted runtime.

The agent entry must live at the project root as agent.py.

Define a Schedule

Create one file per schedule under schedules/ and define a named schedule:

# schedules/daily_digest.py
from managed_deepagents import define_schedule

schedule = define_schedule(
    cron="0 8 * * 1-5",
    timezone="America/Los_Angeles",
    prompt="Write the daily digest.",
)

mda deploy reconciles schedules as LangSmith cron jobs after the deployment is live. Declarations must be statically serializable literals or top-level constants; prompt schedules become user-message input, and stateless runs clean up their temporary thread after completion.

Sandbox

mda init scaffolds sandbox/__init__.py with a LangSmith sandbox. MDA only enables the sandbox when that declaration is present — delete sandbox/ to opt out:

from managed_deepagents import define_sandbox

sandbox = define_sandbox(
    idle_ttl_seconds=600,
)

If sandbox/setup.sh exists, mda deploy / mda dev bake it into a recipe snapshot once; thread sandboxes clone that snapshot and do not re-run setup. MDA owns sandbox naming, image/snapshot selection, reuse, and lifecycle.

Private published images can declare registry credentials by environment variable name; MDA creates or updates the deployment-owned Host registry:

sandbox = define_sandbox(
    docker_image="ghcr.io/acme/agent-base:1",
    registry={
        "url": "ghcr.io",
        "username": "octocat",
        "password_env": "GHCR_TOKEN",
    },
)

Put GHCR_TOKEN in the project .env or process environment. Its value is used only to reconcile the registry and never enters the build or snapshot.

MCP Connectors

Add connectors/mcp.py to attach MCP servers. The file must define a module-level connector. By default, MDA exposes every tool loaded from each declared server. In mda dev, an agent-owned connection reads from MDA_DEV_<SLUG> with the slug uppercased and hyphens changed to underscores. Hosted deployments resolve workspace connections from Agent Auth:

from managed_deepagents import connectors, connections

connector = connectors.mcp(
    mcp_servers={
        "langchainDocs": {
            "transport": "http",
            "url": "https://docs.langchain.com/mcp",
            "include_tools": ["search", "fetch"],
            "connection": connections.get("docs-token", {"type": "agent"}),
        },
    },
)

For this example, set MDA_DEV_DOCS_TOKEN.

A user-owned connection — connections.get(slug, {"type": "user"}) — resolves per caller (OAuth or opaque). The runtime maps the verified ingress identity to an Agent Auth principal, then the pre-run credential gate interrupts the run when a grant is missing. That path works in mda deploy and mda dev when LANGSMITH_API_KEY and LANGSMITH_WORKSPACE_ID are set and the workspace connection rows exist — use a person principal (for example a Supabase JWT), not Studio’s synthetic service user. OAuth completes on LangSmith’s platform callback URL; the local UI must surface credential_authorization_required and resume after the user connects.

Deploy the project first, then provision its connections with mda connections create. Agent-owned opaque secrets are scoped to that deployment, so the command refuses to create one before mda deploy. mda connections check verifies manifest slugs exist in the workspace.

Use include_tools or exclude_tools inside a server config to select a subset. Tool names are raw MCP tool names before the managed {server}__ prefix is applied, so "include_tools": ["search"] on server langchainDocs exposes langchainDocs__search when prefixing is enabled.

CLI

Create a new project:

mda init my-agent

Build locally:

mda build ./my-agent

Run on the local LangGraph dev server:

mda dev ./my-agent

mda dev requires uv on PATH, but it resolves the local LangGraph dev server automatically; you do not need to install a global langgraph command.

Deploy to LangSmith:

mda deploy ./my-agent

The generated build is written to <root>/.mda/build by default.

Common deploy options:

mda deploy ./my-agent --name my-agent-dev --deployment-type dev
mda deploy ./my-agent --workspace-id "$LANGSMITH_WORKSPACE_ID"
mda deploy ./my-agent --no-wait

Read the deployed agent's server logs:

mda logs ./my-agent
mda logs ./my-agent --lines 200 --level error
mda logs ./my-agent > agent.log

In a terminal mda logs streams new output until you press Ctrl-C. When the output is piped or redirected it prints the most recent lines (1000 by default) and exits.

Tear it down again:

mda delete ./my-agent

mda delete (alias mda destroy) removes the LangSmith deployment, the tracing project created alongside it, the deployment's Context Hub repo (plus any legacy per-user or org child memory repos left from older runtimes), and the managed sandboxes the deployment created. It asks for confirmation first; pass --yes to skip the prompt in scripts. Agent memory and thread history are not recoverable afterwards.

Sandboxes are matched by name: the runtime names each one {deployment}--{digest} of the thread id, which also lets a restarted deployment re-adopt its existing sandbox instead of stranding it. Recipe changes (setup.sh or bake base) produce a new deploy-time snapshot; live threads keep their boxes until reclaim. Sandboxes created before this behavior existed are unnamed and are left to LangSmith's idle-stop and retention window.

Before deploying, make sure your model provider key such as OPENAI_API_KEY or ANTHROPIC_API_KEY is available in the project .env or LangSmith workspace secrets; a value exported in your shell is not deployed. For LangSmith itself, set LANGSMITH_API_KEY in .env or your shell, or run interactively and press Enter at the prompt to sign in with your browser (the CLI creates a key and writes it to .env). Use LANGSMITH_WORKSPACE_ID or --workspace-id when your credentials require a workspace selection.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

managed_deepagents-0.6.2.dev44-py3-none-win_arm64.whl (2.0 MB view details)

Uploaded Python 3Windows ARM64

managed_deepagents-0.6.2.dev44-py3-none-win_amd64.whl (2.1 MB view details)

Uploaded Python 3Windows x86-64

managed_deepagents-0.6.2.dev44-py3-none-macosx_11_0_arm64.whl (2.1 MB view details)

Uploaded Python 3macOS 11.0+ ARM64

managed_deepagents-0.6.2.dev44-py3-none-macosx_10_12_x86_64.whl (2.2 MB view details)

Uploaded Python 3macOS 10.12+ x86-64

File details

Details for the file managed_deepagents-0.6.2.dev44-py3-none-win_arm64.whl.

File metadata

File hashes

Hashes for managed_deepagents-0.6.2.dev44-py3-none-win_arm64.whl
Algorithm Hash digest
SHA256 8d714a303a25ace965b1ecda1a1c43167385bb65403207473ea1955b02f6aa56
MD5 964f485b80d7cf9521df84ec064f1451
BLAKE2b-256 ffdf94e08bdbd9cb30cdf68c9afd47b8fe73d45fc5d087824fbf6557e0820159

See more details on using hashes here.

Provenance

The following attestation bundles were made for managed_deepagents-0.6.2.dev44-py3-none-win_arm64.whl:

Publisher: release.yml on langchain-ai/managed-deepagents-sdk

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file managed_deepagents-0.6.2.dev44-py3-none-win_amd64.whl.

File metadata

File hashes

Hashes for managed_deepagents-0.6.2.dev44-py3-none-win_amd64.whl
Algorithm Hash digest
SHA256 1f775a791e2dfcbe8da54fb56d6568c8ee5688e0bfcc63573fe64d847a924eee
MD5 0192501d53ebd4feb44f69d2ac281154
BLAKE2b-256 032842dc0e01e3676a8fc4b6792fd60f742c8ff0dfe8fc7e7ec522c747652fd0

See more details on using hashes here.

Provenance

The following attestation bundles were made for managed_deepagents-0.6.2.dev44-py3-none-win_amd64.whl:

Publisher: release.yml on langchain-ai/managed-deepagents-sdk

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file managed_deepagents-0.6.2.dev44-py3-none-manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for managed_deepagents-0.6.2.dev44-py3-none-manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 c9153646bb03c0d874d336b939c3937cd31949d7df299dcbc019e326400630e5
MD5 584f4ac1e7c34a2031cfa843212578af
BLAKE2b-256 d70707fce4226fee04fe2c229c6a0d9ae36a3094d0352f11cf5863b0320786c0

See more details on using hashes here.

Provenance

The following attestation bundles were made for managed_deepagents-0.6.2.dev44-py3-none-manylinux2014_x86_64.whl:

Publisher: release.yml on langchain-ai/managed-deepagents-sdk

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file managed_deepagents-0.6.2.dev44-py3-none-manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for managed_deepagents-0.6.2.dev44-py3-none-manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 8176157b7953b072e2c73ed68c8336162ccdfba55efe7cd5efb12632cf4e8176
MD5 ea7fcdcda583444a02bf7b2c7195f340
BLAKE2b-256 279c5cc98e50c9c7114cac7a740c7be980b5e3241360abf3d37c0b25fa779f16

See more details on using hashes here.

Provenance

The following attestation bundles were made for managed_deepagents-0.6.2.dev44-py3-none-manylinux2014_aarch64.whl:

Publisher: release.yml on langchain-ai/managed-deepagents-sdk

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file managed_deepagents-0.6.2.dev44-py3-none-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for managed_deepagents-0.6.2.dev44-py3-none-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 a52171e7b6408f60b7f2c66b439ccb77c1c7c45fea72ceb47bc9e1e4baeede29
MD5 3b1a50b354b5b35b7d9a09c4957a56a2
BLAKE2b-256 c3de727ceb18197268f401e5907890d194b6c322f43463a20d1c1beadc2634c1

See more details on using hashes here.

Provenance

The following attestation bundles were made for managed_deepagents-0.6.2.dev44-py3-none-macosx_11_0_arm64.whl:

Publisher: release.yml on langchain-ai/managed-deepagents-sdk

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file managed_deepagents-0.6.2.dev44-py3-none-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for managed_deepagents-0.6.2.dev44-py3-none-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 bce58040547135f5052c56bc503a6a8c2abb12ea926a9f63ed0370b834baa2a7
MD5 0d507eb1e80c7aacf2fdc0c769e2aefe
BLAKE2b-256 2cf59f624bab1ea017f36e373f8722ede0dca2ce25057ad799c7e1e557a50edd

See more details on using hashes here.

Provenance

The following attestation bundles were made for managed_deepagents-0.6.2.dev44-py3-none-macosx_10_12_x86_64.whl:

Publisher: release.yml on langchain-ai/managed-deepagents-sdk

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

0.7.2

6 files

0.7.1

6 files

0.7.0

6 files

This release

0.6.2.dev44 This release

6 files

0.6.1

6 files

0.6.0

6 files

0.5.3

6 files

0.5.2

6 files

0.5.1

6 files

0.5.0

6 files

0.4.3

6 files

0.4.2

6 files

0.4.1

6 files

0.4.0

6 files

0.3.1

6 files

0.3.0

6 files

0.2.0

6 files

0.1.2

2 files

0.1.1

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page