Bin✳

学习笔记 · Obsidian

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

LangChainTypeScript
来源更新 2026-08-11下载 Markdown ↓

结论先行

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。

官方页面使用：

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 的数据路由

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 + Studiomock/fallback 不等于部署环境
mda deploycontext 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、美国区限制与服务不可用准备回滚或降级方案。

关联

← 继续探索AI 与智能体回到顶部 ↑