TypeScript authoring package and CLI launcher for Managed Deep Agents.
> [!IMPORTANT]
> **Public beta.** Managed Deep Agents is in public beta. The npm package API
> and managed runtime contract may change. See the
> [docs](https://docs.langchain.com/langsmith/python/managed-deep-agents-overview)
> for getting started and updates.
`managed-deepagents` is the npm package for authoring Managed Deep Agents in
TypeScript and Node.js. It includes:
- `defineDeepAgent`, the TypeScript authoring contract for managed agents.
- `defineSchedule`, the TypeScript 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
```bash
npm install managed-deepagents
```
> [!NOTE]
> **Private beta: dev releases only.** We currently publish under the `dev`
> dist-tag and have no stable `latest` version yet. Install the dev channel
> explicitly:
>
> ```bash
> npm install managed-deepagents@dev
> ```
This package requires Node.js 22 or newer. The `mda` binary is delivered through
per-platform optional dependencies, so install only downloads the binary for your
OS and CPU architecture. This npm-installed CLI scaffolds and compiles TypeScript
projects only and vendors the TypeScript runtime bundled with this package.
To start a new project, run `mda init`. In a terminal, the CLI asks you to name
the agent:
```bash
mda init
```
Run `mda init -i` to initialize your agent interactively and optionally hand it
off to a coding agent to build:
```bash
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:
```bash
mda init my-agent
```
`mda init` can shape the project up front — `--instructions "..."` (or
`--instructions-file `) writes the system prompt, `--model ` 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.ts`. Every new project includes an
`identity.ts` that explicitly selects `auth.langsmithApiKey()` authentication.
`mda init my-agent --gateway` runs the agent on
[LangSmith Gateway](https://docs.langchain.com/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:
```bash
mda evals init -i
```
2. Follow the coding-agent prompt to author tasks directly under
`evals//`. 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//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:
```bash
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.ts` that exports a named `agent` definition:
```ts
import { defineDeepAgent } from "managed-deepagents";
import { queryDB } from "./tools/query-db";
// The system prompt comes from instructions.md next to this file.
export const agent = defineDeepAgent({
name: "research-assistant",
model: "openai:gpt-5.5",
tools: [queryDB],
});
```
`defineDeepAgent` requires a static `name` (LangGraph assistant id and default LangSmith deployment name) and otherwise accepts the [`createDeepAgent`](https://reference.langchain.com/javascript/deepagents/agent/createDeepAgent) configuration surface minus the managed keys: `backend`, `store`, `checkpointer`, `memory`, `skills`, and `systemPrompt`. Those are provided by the managed runtime when your agent is deployed. Write the system prompt in `instructions.md` next to `agent.ts`; 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:
```ts
export const identity = defineIdentity({
auth: auth.langsmithApiKey(),
});
```
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.ts` declaring `defineMemory({ 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.ts` mounts no durable memory.
## Project Shape
```text
my-agent/
agent.ts # named `agent` export
identity.ts # managed authentication (included by `mda init`)
instructions.md # managed system prompt
package.json
.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.ts # 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.ts` or `agent.tsx`.
## Define a Schedule
Create one file per schedule under `schedules/` and export a named `schedule`:
```ts
// schedules/daily-digest.ts
import { defineSchedule } from "managed-deepagents";
import prompt from "./daily-digest.md" with { type: "text" };
export const schedule = defineSchedule({
cron: "0 8 * * 1-5",
timezone: "America/Los_Angeles",
prompt,
});
```
```md
Write the daily digest.
```
`mda` inlines `import … with { type: "text" }` into a string constant at compile
time. The package also ships ambient `*.md` typings, so TypeScript accepts the
import once you depend on `managed-deepagents` — no project-local
`declare module "*.md"` needed.
`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/index.ts` with a LangSmith sandbox. MDA only
enables the sandbox when that declaration is present — delete `sandbox/` to opt
out:
```ts
import { defineSandbox } from "managed-deepagents";
export const sandbox = defineSandbox({
idleTtlSeconds: 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:
```ts
export const sandbox = defineSandbox({
dockerImage: "ghcr.io/acme/agent-base:1",
registry: {
url: "ghcr.io",
username: "octocat",
passwordEnv: "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.ts` to attach MCP servers. The file must export a named
`connector`. By default, MDA exposes every tool loaded from each declared
server. Supply your own auth via static `headers` when the server requires
credentials:
```ts
import { connectors } from "managed-deepagents";
export const connector = connectors.mcp({
mcpServers: {
langchainDocs: {
transport: "http",
url: "https://docs.langchain.com/mcp",
includeTools: ["search", "fetch"],
},
},
});
```
Use `includeTools` or `excludeTools` inside a server config to select a subset.
Tool names are raw MCP tool names before the managed `{server}__` prefix is
applied, so `includeTools: ["search"]` on server `langchainDocs` exposes
`langchainDocs__search` when prefixing is enabled.
## CLI
Create a new project:
```bash
mda init my-agent
```
Build locally:
```bash
mda build ./my-agent
```
Run on the local LangGraph dev server:
```bash
mda dev ./my-agent
```
Deploy to LangSmith:
```bash
mda deploy ./my-agent
```
The generated build is written to `/.mda/build` by default.
Common deploy options:
```bash
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:
```bash
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:
```bash
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`). TypeScript deploys also require
`npm` on `PATH` because the CLI generates a lockfile for the remote build.
