---
type: study
created: 2026-08-11
updated: 2026-08-11
sensitivity: private
status: active
tags:
  - study
  - langchain
  - managed-deep-agents
  - typescript
  - deployment
topic: Managed Deep Agents TypeScript 本地开发部署与 CLI
sources:
  - https://docs.langchain.com/langsmith/javascript/managed-deep-agents-quickstart
  - https://docs.langchain.com/langsmith/javascript/managed-deep-agents-local-development
  - https://docs.langchain.com/langsmith/javascript/managed-deep-agents-tutorial
  - https://docs.langchain.com/langsmith/javascript/managed-deep-agents-deploy
  - https://docs.langchain.com/langsmith/javascript/managed-deep-agents-cli
last_verified: 2026-08-11
---

# Managed Deep Agents TypeScript：本地开发、部署与 CLI

## 结论先行

TypeScript 最短闭环是：Node/npm 安装依赖，`mda init` 建项目，`mda dev` 在本地 Agent Server 与 Studio 验证，Harbor 评估关键行为，再用 waited `mda deploy` 部署并对账 schedules。

与 Python 版相比，TypeScript 项目由 npm 包提供 authoring API 和 `mda` binary，本地 dev server 实际通过 `npx @langchain/langgraph-cli dev` 启动。Secrets、Context Hub、源码、schedule 和 evals 各走不同数据路径；只有理解这些边界，才能避免把 `.env` 打包、漏传 runtime key 或把 `--no-wait` 误当成完整发布。

## 安装与命令解析

前置条件包括 public beta 权限、LangSmith API key、Node.js、npm 和模型 provider key。

官方页面使用：

```bash
npm install managed-deepagents
```

CLI reference 同时说明：可以全局安装，或通过 `npm exec` 运行 binary。本地 `npm install` 只把可执行文件放进项目的 `node_modules/.bin`；在未全局安装的普通 shell 中，不应假设裸 `mda` 一定可解析。可选择：

- 固定项目依赖，并用 `npm exec mda -- <command>` 或 package script。
- 明确全局安装，再记录和锁定全局版本。

生产与 CI 更适合项目级固定版本，避免开发机全局 CLI 与 `package-lock.json` 中 authoring API 版本不一致。

## 推荐端到端闭环

1. `mda init <name>` 创建 TypeScript 项目。
2. 在 `.env` 配置本地 LangSmith 与 provider credential，确保文件被忽略。
3. 在 `agent.ts` 组合 `defineDeepAgent`，把实现拆到 tools/middleware 等目录。
4. `npm install` 安装并锁定项目依赖。
5. `mda build .` 验证入口、导入、托管声明和静态 schedule 提取。
6. `mda dev .` 在 Studio 验证模型、工具、state 与 interrupts。
7. 编写并运行 Harbor evals；不能只停在 `mda evals compile`。
8. 先部署 development revision，联调 identity、sandbox、memory、channel 和 schedules。
9. 生产首次创建显式使用 `--deployment-type prod`。
10. 等待 `DEPLOYED`，核对 revision、trace、secret、cron 和外部渠道。

Tutorial 中的 `web_search` 只是返回占位字符串的 stub，只能演示工具调用闭环，不能证明真实检索、引用正确性、超时、限流或网络安全已经完成。

## `mda init` 与项目初始化

`mda init` 目标目录已存在时失败。它根据当前目录判断语言：只有 `package.json` 时直接选择 TypeScript；同时存在多语言标志或都不存在时会交互询问。

常用选项：

| 选项 | 作用 |
| --- | --- |
| `--instructions` / `--instructions-file` | 初始化 system prompt |
| `--identity` | 增加托管身份与用户私有 thread 配置 |
| `--memory agent\|none` | 显式创建 memory 声明；省略则关闭 durable memory |
| `--model provider:model` | 设置模型 |
| `--no-sandbox` | 不创建 sandbox 声明 |

脚手架包含 `agent.ts`、`instructions.md`、`package.json`、README、`.env` 与 `.gitignore`。Eval task 不会自动创建，必须显式 `mda evals init`。

## `mda build`

`mda build [path]` 只编译，不部署。默认输出到 `<path>/.mda/build`。

默认 build 会清空输出目录，因此 `--out` 只能指向不存在、空目录，或先前由 MDA build 写入的目录。不要把仓库根、共享目录或含用户文件的目录当作输出目标。

Build 是发现以下问题的最低成本入口：

- `agent.ts` / `agent.tsx` 与命名 `agent` export 是否有效。
- ESM/CJS、`.mts`/`.cts` 与本地模块 import 是否能在托管编译中解析。
- channels/connectors/schedules 的命名 export 是否满足约定。
- schedule 是否能静态提取。
- compiled archive 是否包含意外生成物或逼近 200 MB 限制。

## `mda dev` 的真实边界

`mda dev` 会：

1. 校验并编译到 `.mda/build`。
2. 把项目 `.env` 暂存到本地 build，并按需要增加 local-only identity 配置。
3. 为 instructions、skills 和 memory 建本地 Context Hub mock。
4. 通过 `npx --yes @langchain/langgraph-cli dev` 启动 TypeScript LangGraph dev server。
5. 打开 LangSmith Studio。

可配置端口、hostname、`--no-browser` 与 `--no-reload`。虽然下层 dev server 支持 reload，MDA 文档要求项目文件变化后停止并重新运行 `mda dev` 以重新编译；特别是新增约定文件、改变入口或 schedule 时，不应只依赖热重载。

本地默认值只用于开发便利：

- identity 可由 Studio 提供本地测试用户。
- configured sandbox 创建失败时会回退到临时本地文件夹并打印路径。
- Context Hub 是本地 mock。

这些行为都不能替代 development deployment 上的真实 JWT、thread ownership、managed sandbox、Context Hub 同步和多副本测试。

## Build 与 Deploy 的数据路由

```text
instructions.md + skills/** -> Context Hub deploy-owned context
.env                        -> CLI auth + 合格 hosted secrets，不进 archive
project source              -> .mda/build -> source archive -> hosted deployment
schedules/**                -> DEPLOYED 后的 LangSmith cron reconciliation
evals/**                    -> Harbor workspace，不进 deployment
```

部署前必须把 `.mda/`、`.env*`、dependency cache、Harbor trial outputs 和生成的 Slack manifest 排除版本控制。

## Authentication 与 secrets

部署认证 key 的名称优先级：

1. `LANGGRAPH_HOST_API_KEY`
2. `LANGSMITH_API_KEY`
3. `LANGCHAIN_API_KEY`

对每个变量，CLI 先读项目 `.env`，再读进程环境。交互终端找不到 key 时，CLI 会提示输入并保存到项目 `.env`；因此必须确认 `.gitignore` 已生效，并避免把终端录屏、日志或 CI output 当作秘密存储。

组织级 key 还需要 `LANGSMITH_WORKSPACE_ID` 或 `--workspace-id`。

Secrets 路由：

- Reserved platform 变量用于 CLI auth 与部署路由，不作为 user-managed deployment secret 上传。
- 非 reserved `.env` 项，如 provider key、MCP token 和业务 credential，会被转发到 hosted deployment。
- 空值、`.env` 和 `.env.*` 不进入 build archive。
- Provider key 也可以来自 shell 或 LangSmith workspace secrets；如果只在 shell 中，当前 deploy 会把它转发为 runtime secret。
- CLI 在上传前检查配置模型所需 provider key；缺失会提前失败。

`.env` 优先于 shell 是容易忽略的行为：本地旧值可能遮蔽 CI 或临时导出的新值。发布前应记录实际 key 来源，只记录变量名和来源层，不输出值。

## `mda deploy` 的一致性流程

标准 waited deploy：

1. 校验项目并加载 agent entry。
2. 解析 LangSmith key 与 workspace。
3. 收集合格 secrets，检查模型 provider credential。
4. 同步 deploy-owned Context Hub 内容。
5. 编译 `.mda/build` 并提取 schedules。
6. 创建或查找同名 hosted deployment。
7. 归档上传并触发远端 build。
8. 等待 revision 到达 `DEPLOYED`。
9. 对账 MDA-owned schedules。

`--deployment-type` 只在创建 deployment 时决定 `dev` 或 `prod`，默认是 `dev`。生产创建必须显式标明，避免把默认开发类型误用于生产。

`--no-wait` 只触发远端 build 就退出，不会确认 revision 成功，也不会对账 schedules。它适合异步流水线的“触发”阶段，但后续必须有独立的状态轮询、失败处理和 cron reconciliation；否则不能标记发布完成。

Context Hub 同步期间发生并发更新会报冲突，重新 deploy 前应先确认哪一侧是权威内容。Build 超过 200 MB 会失败；`BUILD_FAILED` 或 `DEPLOY_FAILED` 应从 deployment revision logs 定位，而不是盲目重试。

## CLI 命令与操作风险

| 命令 | 用途 | 关键边界 |
| --- | --- | --- |
| `mda init` | 建项目 | 已存在目录失败；memory 默认关闭 |
| `mda build` | 本地编译 | 输出目录会被清空，必须限定目标 |
| `mda evals init/compile` | 生成 Harbor handoff | 不运行 trial；同名 scaffold 会覆盖 task 目录 |
| `mda dev` | 本地 Agent Server + Studio | mock/fallback 不等于部署环境 |
| `mda deploy` | context sync、build、upload、deploy、cron 对账 | `--no-wait` 跳过完成确认与 cron 对账 |
| `mda logs` | 拉取或跟随部署日志 | 支持 level、lines、follow；日志不得泄密 |
| `mda delete` / `destroy` | 删除 deployment 及其创建的资源 | 破坏性；`--yes` 跳过确认 |

删除 deployment 会连带清理 MDA 创建的 managed sandboxes 等资源。执行前必须确认目标 workspace、deployment 名、数据保留和恢复方案。本次学习任务没有执行任何部署、删除或远端配置动作。

## 生产发布检查

- 固定 Node、npm、`managed-deepagents` 和 lockfile 版本。
- 使用项目级 CLI 或明确记录全局 CLI，验证 API 与 binary 版本一致。
- `mda build`、类型检查、单元测试和 Harbor trials 全部通过。
- 在 development deployment 验证真实 identity、sandbox、memory、channel 和 schedule。
- 检查 `.env` 实际优先级、workspace、deployment type 和 secret 路由。
- 对 Context Hub 在线修改建立审计与 Git/UI 真源策略。
- Schedule 变更使用 waited deploy，并核对远端 cron。
- 监控 build/revision 状态、run error、tool latency、模型成本、interrupt backlog、channel retry 和 missed cron。
- 为 public beta 的 breaking change、美国区限制与服务不可用准备回滚或降级方案。

## 关联

- [[01-TypeScript架构与项目模型|TypeScript 架构与项目模型]]
- [[02-TypeScript扩展能力与安全边界|TypeScript 扩展能力与安全边界]]
- [[03-TypeScript渠道调度与评估|TypeScript 渠道、调度与评估]]