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

最短闭环

通过 uv tool install managed-deepagents 安装 mda。
mda init <name> 创建项目，配置 agent.py、instructions.md、.env 与 tools。
uv sync 安装项目依赖。
mda dev . 编译并在本地 Agent Server + LangSmith Studio 中检查模型响应、工具调用、state 与 interrupts。
为关键行为编写 Harbor evals。
mda deploy . 同步 context、上传代码、构建 hosted deployment，并在等待成功后对账 schedules。
在 LangSmith 检查 revision、trace、tool call、memory read/write、错误和延迟。

`mda dev` 实际做什么

校验项目并编译到 .mda/build。
把项目 .env 放入本地 build，并按需添加本地 identity 配置。
为 instructions、skills 和 memory 创建本地 Context Hub mock。
启动 LangGraph development server 并打开 Studio。
项目文件变更后需要重新运行以重新编译；dev server 是否热重载由参数控制。

本地默认值只用于降低开发门槛：Studio 可提供测试用户；托管 sandbox 不可用时会回退到临时本地目录。它们不等价于线上 identity 和 sandbox，必须在 development deployment 再验证一次。

Build 与 Deploy 的数据路由

instructions.md + skills/**  -> Context Hub deploy-owned context
.env                         -> CLI auth + non-reserved hosted secrets
project source               -> .mda/build -> archive -> hosted deployment
schedules/**                 -> deployment 成功后的 LangSmith cron
evals/**                     -> Harbor workspace，不进入 deployment

.env、.env.*、空值和 reserved platform variables 不进入 build archive。非 reserved provider key、MCP token 和业务 tool credential 会作为 hosted deployment secrets 转发。

部署读取认证 key 的优先级是：LANGGRAPH_HOST_API_KEY、LANGSMITH_API_KEY、LANGCHAIN_API_KEY；每个值又先查项目 .env，再查进程环境。组织级 key 还需要 workspace ID。

主要命令

命令	用途	关键边界
`mda init`	建项目	目标目录已存在时失败；memory 默认关闭
`mda build`	只编译	默认清空 `.mda/build`；自定义输出目录必须是缺失、空目录或先前 build 写入目录
`mda evals init/compile`	建 scaffold、产出 Harbor handoff	不运行 trials
`mda dev`	本地 Agent Server + Studio	本地 fallback 与线上可能不同
`mda deploy`	context sync、build、upload、hosted deploy、schedule reconcile	`--no-wait` 跳过 schedule 对账
`mda logs`	拉取/跟随 Agent Server 日志	可按 severity 与最近行数过滤
`mda delete` / `destroy`	删除 deployment 及其创建的 LangSmith 资源	破坏性操作，CLI 支持 `--yes` 跳过确认

Deploy 步骤与一致性

标准 waited deploy 会：

校验项目并加载 agent entry。
解析 LangSmith key 与 workspace。
收集可上传 secrets 并检查模型 provider key。
同步 deploy-owned Context Hub 内容。
编译项目、提取 schedule 声明。
创建或查找同名 hosted deployment。
归档上传并触发远端 build。
等待 revision 达到 DEPLOYED。
对账 MDA 管理的 schedules。

Context Hub 在部署期间发生并发更新会造成冲突，需要重新执行 deploy。build 超过 200 MB 会失败；应排除生成物和大文件。BUILD_FAILED 或 DEPLOY_FAILED 要到 deployment revision logs 找根因。

生产发布建议

先 mda build 与 Harbor eval，再以 dev deployment 做 identity、sandbox、memory、channel 和 schedule 联调。
生产创建时显式使用 --deployment-type prod，不要只依赖默认 dev。
涉及 schedule 变更时禁止把 --no-wait 当作完成态；等待成功后核对远端 cron。
把 .mda/、.env*、local trial outputs 和 generated Slack manifest 排除版本控制。
监控 build status、run error、tool latency、token/费用、interrupt backlog、channel retry 与 schedule missed run。
删除 deployment 会连带清理其创建的托管资源；执行前必须明确备份和恢复策略。

当前限制

公开 Beta，平台与 API 可能变化。
仅 LangSmith Cloud 美国区。
文档仍以 CLI-first 为主，面向自有应用的程序化调用细节尚未完整公开。
本地 Context Hub mock、test identity 和 fallback sandbox 不构成生产验证。