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

## 最短闭环

1. 通过 `uv tool install managed-deepagents` 安装 `mda`。
2. `mda init <name>` 创建项目，配置 `agent.py`、`instructions.md`、`.env` 与 tools。
3. `uv sync` 安装项目依赖。
4. `mda dev .` 编译并在本地 Agent Server + LangSmith Studio 中检查模型响应、工具调用、state 与 interrupts。
5. 为关键行为编写 Harbor evals。
6. `mda deploy .` 同步 context、上传代码、构建 hosted deployment，并在等待成功后对账 schedules。
7. 在 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 的数据路由

```text
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 会：

1. 校验项目并加载 agent entry。
2. 解析 LangSmith key 与 workspace。
3. 收集可上传 secrets 并检查模型 provider key。
4. 同步 deploy-owned Context Hub 内容。
5. 编译项目、提取 schedule 声明。
6. 创建或查找同名 hosted deployment。
7. 归档上传并触发远端 build。
8. 等待 revision 达到 `DEPLOYED`。
9. 对账 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 不构成生产验证。